sandbox.network.tlsTerminateは資格情報マスクに必須のTLS終端設定

sandbox.network.tlsTerminateは、サンドボックスの組み込みプロキシにTLSを終端させ、HTTPS通信の中身を読めるようにする設定です。既定ではオフで、通信のホスト名しか見ません。オンにすると、資格情報を実値と入れ替えるmask機能が動くようになります。実験的機能扱いで、Claude Code v2.1.199以降が必要です。

sandbox.network.tlsTerminateとは

サンドボックス化されたBashコマンドの通信は、外部のプロキシサーバーを経由します。このプロキシは既定では通信先のホスト名だけを見て許可・拒否を判定し、HTTPSの中身までは終端も検査もしません。sandbox.network.tlsTerminateをオンにすると、このプロキシ自身がTLSを終端し、リクエストの中身を読めるようになります。

設定値は2通りです。{}を指定すると、そのセッション限りの一時的な認証局(CA)がその場で生成されます。caCertPathとcaKeyPathを指定すれば、自分で用意したCA証明書と秘密鍵を使わせることもできます。どちらの場合も、サンドボックス内のコマンドが見るのはClaude Codeのプロキシが発行した証明書であって、接続先が本来持つ証明書ではありません。

{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}

設定方法 — 一時CAと自前CAの違い

一時CA({})はセッションごとに使い捨てられるため、証明書の管理コストがかかりません。反面、CAをどこかに固定して他ツールに信頼させたい場合には向きません。自前CAを使う構成は、caCertPathとcaKeyPathにファイルパスを指定します。

{
  "sandbox": {
    "network": {
      "tlsTerminate": {
        "caCertPath": "~/.claude/sandbox-ca.pem",
        "caKeyPath": "~/.claude/sandbox-ca.key"
      }
    }
  }
}

複数の設定ソースがこの値を同時に指定した場合、Claude Codeはmanaged settings、次に--settingsフラグ、最後にuser settingsという優先順で1つを採用します。設定は上書きではなく置き換えです。ソースをまたいで値をマージすることはありません。

mask機能はなぜこの設定を要求するか

sandbox.credentials.filesやsandbox.credentials.envVarsに"mode": "mask"を指定すると、サンドボックス内のコマンドには本物の代わりにプレースホルダー(sentinel)が見えます。許可したホストへ通信が出ていく瞬間だけ、プロキシがsentinelを実際の値に差し替えます。この差し替えはリクエストのヘッダーと本文の両方が対象です。

差し替えを行うには、プロキシがリクエストの中身を読める状態でなければなりません。tlsTerminateが要るのはこのためです。平文HTTPのテストネットワーク限定なら、代わりにallowPlaintextInjectを使う選択肢もあります。

設定を忘れても、資格情報が漏れるわけではありません。サンドボックス内のコマンドが見るのは相変わらずsentinelで、それがそのまま宛先に届いて認証が通らなくなるだけです。Claude Codeはこの設定ミスを起動時に報告します。

maskエントリにはinjectHostsを指定でき、実値を差し込む宛先ホストを絞り込めます。指定がなければ、allowedDomainsに含まれるすべてのホストへの通信が差し替え対象になります。injectHostsに書けるのはallowedDomainsが既に許可しているホストだけで、許可リストの外へ実値を送る抜け道にはなりません。

ファイルをmaskする場合は、プラットフォームで挙動が変わります。LinuxとWSL2では、サンドボックス内のコマンドが読むのはプレースホルダーに置き換えたsentinelのコピーで、外部への送信時にプロキシが実値へ差し替えます。macOSでは、対象ファイルはサンドボックス内から一切読めなくなり、denyと同じ扱いになります。tlsTerminateが要るのは、この差し替えのうちLinux・WSL2側の動作のためです。対象がディレクトリやglobパターン、8MiBを超えるファイル、UTF-8以外のテキストである場合、Claude Codeは安全にmaskできないと判断しdenyへフォールバックします。

値そのものではなく値から導出した署名で認証するリクエスト(AWSのSigV4署名付きリクエストなど)は、単純な差し替えでは済みません。プロキシ側での再署名が必要で、AWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYをどちらもmaskしていれば自動で連携します。ただし、aws-chunkedのストリーミングアップロード・署名済みURL・SigV4Aの3形式はプロキシが再署名できません。これらがmask対象の資格情報で署名されていた場合、credentials.sigv4でフォームごとにpassthroughを指定すれば、プロキシのエラーではなくAWS側からの本来のエラー応答を受け取れるようになります。

リポジトリ設定でオンにできない理由

maskは本物の資格情報を許可ホストへ送信する権限をプロキシに与える機能です。そのためtlsTerminate・maskエントリ・allowPlaintextInjectは、あなたか管理者が制御できる設定ソース(user settings・managed settings・--settingsフラグ)からしか読まれません。プロジェクトの.claude/settings.jsonや.claude/settings.local.jsonに書いても無視されます。

管理者がmanaged settings経由でこれらを配布する場合は、通常のmanaged settingsとは別に、承認ダイアログの対象になります。組織のポリシーとしてmaskを配りたいときは、この承認フローを前提に運用を組む必要があります。

httpProxyPortとの違いをどう使い分けるか

サンドボックスにはTLSやプロキシに関わる設定が複数あり、目的が混同されがちです。tlsTerminateはClaude Code自身の組み込みプロキシがTLSを終端する設定で、外部プロキシへの接続を差し替えるhttpProxyPortや、macOS固有のenableWeakerNetworkIsolationとは別物です。

enableWeakerNetworkIsolationは、httpProxyPortでMITMプロキシと独自CAを使う構成のときに、ghやgcloud、terraformのようなGo製CLIが証明書検証で失敗するのを防ぐための設定です。tlsTerminateとは目的も動く場所も違います。オンにすると、システムのTLS信頼サービス経由でデータを持ち出せる経路が新たに開くため、セキュリティを下げる代償を伴います。

組織の外側にあるプロキシへ単に転送したいだけなら、httpProxyPortではなくHTTPS_PROXY/HTTP_PROXY/NO_PROXYという環境変数を使う経路もあります。この場合もClaude Code側のドメイン許可リストが先に働き、許可された接続だけが上流プロキシへトンネリングされます。一方httpProxyPortが指すのは、検査や独自フィルタリングのためにサンドボックスの内部に直接差し込む、自分自身が実装するプロキシです。組織がhttpProxyPortで独自プロキシを差し込む動機は主に次の4つです。

• HTTPS通信を復号して中身を検査する
• 組織独自のフィルタリングルールを適用する
• すべてのリクエストをログに残す
• 既存のセキュリティ基盤と統合する

組織側の外部プロキシで通信全体を検査したいならhttpProxyPort、Claude Code自身のプロキシにmaskだけ動かしたいならtlsTerminate、というのが基本の切り分けです。ドメイン許可リストやfilesystem.disabledといった他のサンドボックス設定と同様、こちらも既定ではオフになっている点は共通しています。

TLSを終端してもドメインフロンティングは防げない

tlsTerminateをオンにしても、それだけでサンドボックスの通信が全面的に検査されるわけではありません。公式ドキュメントは、この設定が追加するのはmask置換のためのTLS終端だけで、コンテンツフィルタリングは追加しないと明記しています。

ドメインの許可判定は、依然としてクライアントが名乗ったホスト名ベースで行われます。そのため、サンドボックス内のコードがドメインフロンティングのような手法を使えば、許可リスト外のホストに到達する余地が理論上は残ります。github.comのような広いドメインを許可リストに入れるほど、この余地は広がります。

より強い保証が必要な脅威モデルでは、tlsTerminateではなく、TLSを終端・検査したうえで独自のCA証明書をサンドボックス内にインストールする「カスタムプロキシ」構成(httpProxyPort/socksProxyPort)を選ぶ方が筋が通っています。tlsTerminateはmask機能のための最小限の仕組みであって、通信全体を監査する仕組みではありません。公式ドキュメントも、TLSを意識したより強いネットワーク分離を「活発に開発が進んでいる領域」と位置付けています。今のtlsTerminateはその途中にある実験的な機能で、恒久的な仕様として固定されたものではありません。この線引きを取り違えると、設定した安心感だけが先に立ってしまいます。

サンドボックスが分離するのはBashサブプロセスの通信だけという点も、設計の射程を見るうえで押さえておく価値があります。Read・Edit・Writeといった組み込みファイルツールは、サンドボックスを経由せず権限システムを直接使います。サブエージェントは親セッションと同じプロセスで動くため、親セッションでサンドボックスが有効なら、サブエージェント内のBashコマンドにもtlsTerminateを含む同じサンドボックス設定がそのまま適用されます。

まとめ — tlsTerminateが必要になる場面

sandbox.network.tlsTerminateが要るのは、sandbox.credentialsでmaskモードの資格情報保護を使いたい人だけです。denyモードで資格情報を隠すだけなら、この設定は不要です。設定はuser settingsかmanaged settings、または--settingsフラグからしか効かず、プロジェクト単位の.claude/settings.jsonでは有効になりません。組織でmaskを配布するなら、managed settingsの承認ダイアログを運用に織り込んでおくと導入がスムーズです。

v2.1.199より前のClaude Codeにはこのキー自体が存在しないため、mask機能を検討する前にバージョンを確認しておく必要があります。通信全体をTLS込みで検査したい場合は、tlsTerminateではなくhttpProxyPortによるカスタムプロキシ構成を検討する場面です。