docker-sandboxes-network-credentials

Docker Sandboxes：ネットワークポリシーと認証情報

概要

このスキルでは、sbx policy（ネットワークの外向き通信）と sbx secret（サービスのシークレットおよびレジストリの認証情報）を扱います。プロキシが外向き通信のポリシーを適用し、ドメインが一致した場合に保存済みの認証情報を注入します。プロキシが管理するセンチネルは、上流サービスの認証情報としては使用できませんが、OAuth パススルーにより、サンドボックスに実際のトークンが公開される可能性があります。外向き通信のポリシーでは、実際の認証情報がサンドボックスの外部に漏えいした後は保護できません。漏えいした認証情報は失効させるか、ローテーションしてください。

このスキルを使用する場面

次の場合にこのスキルを有効にしてください。

• ユーザーが、サンドボックス（またはすべてのサンドボックス）からアクセス可能なホストを許可、拒否、または確認したい場合。
• ユーザーが、サンドボックス内で生の値を公開せずに、エージェントに API キー、OAuth トークン、その他のサービス認証情報を渡したい場合。
• ユーザーが、認証が必要なレジストリからプライベートテンプレートイメージまたはキットをプルしたい場合。
• ユーザーが、ブロックされたネットワークリクエスト、または注入されない認証情報をデバッグしている場合。

このスキルを使用しない場面

次の場合はこのスキルを使用しないでください。

• docker agent run --sandbox の実行、またはその docker agent sandbox 許可リストの管理を行う場合は、docker-agent-run を使用してください。CLI が不明な場合は、コマンドを選択する前に、ユーザーが Docker Agent とスタンドアロンの sbx のどちらを実行しているか確認してください。
• サンドボックス自体の作成、再接続、削除を行う場合は、docker-sandboxes-lifecycle を使用してください。
• チェックイン済みの sbxenv.yaml ファイル内でシークレット、レジストリ、バインディングを宣言する場合は、ファイル形式について docker-sandboxes-env を使用してください（このファイルがプロビジョニングする内容には、このスキルの優先順位と注入範囲に関するルールも引き続き適用されます）。
• spec.yaml 内でキット独自の credentials:／permissions.network: ブロックを宣言する場合は、スキーマについて docker-sandboxes-kits を使用してください（これらの宣言が実行時に意味する内容については、このスキルのモデルも引き続き適用されます）。

基本的なガイダンス

ネットワークポリシー：グローバル、サンドボックスごとの設定、優先順位

• 最初のサンドボックスを作成する前に、グローバルネットワークポリシーを一度初期化する必要があります：sbx policy init <allow-all|balanced|deny-all>。balancedは推奨される開始設定です（一般的な開発トラフィックであるAIサービスやパッケージレジストリへの通信が許可されます）。これは一度だけ行う設定です。
• **sbx policy resetは破壊的な操作です。ローカルポリシーストア全体を削除し、デーモンと現在実行中のすべてのサンドボックスを停止します。**次にデーモンを使用するコマンドを実行すると、デーモンが再起動します。「最初からやり直す」ための手軽な方法でも、通常の診断手順でもありません。動作に問題のある単一のルールに対する最初のトラブルシューティング手段として、決して提案しないでください。代わりに、対象を絞ったsbx policy rm network（--idまたは--resourceを指定）を使って、ルールを1つ削除してください。sbx policy resetはポリシーストア自体をゼロから再構築する必要がある場合に限って使用し、実行前に実行中のサンドボックスが停止することをユーザーに警告してください。
• sbx policy allow network RESOURCES／sbx policy deny network RESOURCESでルールを追加します。RESOURCESは、完全一致のホスト、単一ラベルのワイルドカード*.example.com、複数ラベルのワイルドカード**.example.com、省略可能な:portサフィックス、CIDRプレフィックス、または「すべてのホスト」を表す**をカンマで区切ったリストです。

  sbx policy init balanced
  sbx policy allow network "api.example.com,cdn.example.com"
  sbx policy deny network ads.example.com
  

• **同じホスト名／CIDRに一致する場合、拒否は常に許可より優先されます。**許可されたホスト名は、解決されたIPに対するCIDR拒否ルールとの照合対象になりません。
• ルールはデフォルトでグローバルに適用されます。1つのサンドボックスのローカルポリシーだけに適用するには、--sandbox NAMEを指定します：

  sbx policy allow network --sandbox my-sandbox api.example.com
  

• sbx create／sbx runでは、作成時に限り、--deny-network RESOURCE（繰り返し指定可能）を使ってサンドボックスごとの拒否ルールを追加できます。ローカルの拒否ルールは送信通信を制限することしかできず、範囲を広げることは決してないため、集中管理（組織）ガバナンス下でも安全に使用できます。組織レベルの許可を、より広範な許可に上書きすることはできません。
• sbx policy check network [--sandbox NAME] TARGETを使うと、ホスト／URLに対して現在のポリシーがどのように適用されるかを、影響が出る前にテストできます。また、sbx policy log [SANDBOX]を使うと、実際に許可またはブロックされた通信の履歴と、一致したルールを確認できます。

  sbx policy check network --sandbox my-sandbox api.example.com:443
  sbx policy log my-sandbox --json
  

• sbx policy ls [SANDBOX] [--wide]は有効なポリシー／ルールを一覧表示します。--wideを指定すると、ルールID（sbx policy rm network --idで必要）とリソースごとのステータスが追加されます。sbx policy inspect <policy-or-rule>を使うと、各ルールの正確な削除コマンド、または読み取り専用である理由（組織管理など）を含む詳細を確認できます。サンドボックスにスコープされたルールを削除するには、--sandbox NAMEを指定したままにしてください。省略すると、代わりにグローバルポリシーが対象になります：

  sbx policy rm network --sandbox my-sandbox --resource api.example.com
  sbx policy check network --sandbox my-sandbox api.example.com
  

  ルールを1つ削除しても、最終的な判定は決まりません。一致する他のルールも引き続き適用されます。

サービスシークレット：注入の仕組み

• sbx secret set [SERVICE] は、エージェントに代わって送信リクエストを認証するためにプロキシが使用する認証情報を保存します。通常のプロキシ管理フローでは、サンドボックスに見えるのは生のシークレットではなくセンチネルです。プロキシは、対応するキット／バインディングで宣言されたドメインへのリクエストに、実際の値を代わりに挿入します。

  sbx secret set github                       # interactive
  printf '%s' "$ANTHROPIC_API_KEY" | sbx secret set anthropic
  

  シークレットを保存しても、ネットワークアクセスは許可されません。 エグレスは別途 sbx policy で管理されます。認証のデバッグを始める前に、意図したスコープで対象ドメインを確認してください。

  sbx policy check network --sandbox my-sandbox api.anthropic.com
  

• OAuth パススルーは例外であり、シークレットが公開されないことを保証するものではありません。 キットがリフレッシュ用センチネルなしで oauth.passthrough: true を設定すると、プロキシは実際のトークンレスポンスをサンドボックスに転送します。組み込みの devin キットはこのモードを使用します。トークンを読み取れないと断言する前に、エージェントの認証情報設定を確認してください。認証失敗を回避するためだけにパススルーを有効にしないでください。センチネルを使用していても、エージェントは許可されたサービスで認証情報の権限を行使できます。ネットワークアクセスに加えて、トークンの権限も制限してください。
• サービスシークレットはデフォルトでグローバルです。--sandbox NAME を指定すると、1 つのサンドボックスにスコープを限定できます。
• 動的シークレットは値を直接保存する代わりに、使用時にホスト上で値を解決します。--ref（1Password の op://... または AWS Secrets Manager の ARN。認証済みの op／aws CLI が必要）または --command（シェルコマンドを実行し、その標準出力を使用）を指定します。--refresh で解決／キャッシュポリシーを設定します（デフォルトは 55m、または on-demand）。

  sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
  sbx secret set github --command 'gh auth token'
  

  --command と --ref は、ホスト上でユーザー自身の権限を使って解決され、信頼された実行として扱われます。信頼できないファイルやエージェント自身の出力に影響される可能性のあるものを、--command に決して指定しないでください。
• シークレットをプレーンな --env 値や --kit-arg／--env-arg の値として渡さないでください。 どちらもマスクされないリテラルテキストとして、サンドボックスの環境、sbx env plan の状態ファイル、さらにはシェルの履歴に残る可能性があり、認証情報ストアの目的が損なわれます。代わりに sbx secret set（または同じストアを経由する sbxenv.yaml の secrets:／registries: ブロック）を使用してください。
• sbx secret set-custom（実験的機能）は、sbx に組み込みサポートがないサービスに対応します。サンドボックスには指定した環境変数（--env）にプレースホルダー値が表示され、プロキシは宣言した --host パターンへのリクエストに限って、実際のシークレットに差し替えます。
• sbx secret ls [--global|--sandbox NAME] [--service NAME] [--json] は、値を明かさずに保存済みの項目を一覧表示します。sbx secret rm [SERVICE] [--sandbox NAME] [--all|--registry HOST] [--force] は削除します。
• sbx secret import [SERVICE] [--all] [--dry-run] [--force] は、ホストの環境変数（例：OPENAI_API_KEY、GH_TOKEN）にすでに設定されているシークレットをグローバルストアにインポートするかどうかを確認します。--all／--force を指定しない場合、項目ごとに確認します。OAuth トークンがすでに設定されているサービスはスキップされます。実行時には、インポートした API キーより OAuth が優先されます。

レジストリ認証情報：デフォルトではホストでのプル専用、注入スコープは2種類

• sbx secret set --registry HOST --password-stdin（任意で --username）は、コンテナレジストリのプル認証情報を保存します。これは プライベートなテンプレートイメージやキットのアーティファクトのプルに使用されます。サービス シークレットとは異なり、レジストリ認証情報はデフォルトでホスト専用です。ホストでのプルを認証しますが、サンドボックスには一切注入されません。

  gh auth token | sbx secret set --registry ghcr.io --password-stdin
  

• --all-sandboxes と --sandbox では対象範囲の広げ方が異なります。混同しないでください。
  • --all-sandboxes：ホストでのプルに加えて、プロキシによって新しいすべてのサンドボックスのレジストリログインに認証情報が注入されます（認証情報そのものがサンドボックスのファイルシステムに入ることはありません）。
  • --sandbox NAME：認証情報が注入されるのは、指定した1つのサンドボックスのみです。
  • どちらのフラグも指定しない場合：ホストでのプル専用となり、どこにも注入されません。

  gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
  gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin
  

• Bearer 認証エンドポイントのホスト名がレジストリ自体のホスト名と異なるレジストリの場合は、信頼する HTTPS URL を正確に指定する --registry-auth-endpoint を渡してください。指定しない場合、ホストをまたぐトークン交換は拒否されます。
• sbx secret rm --registry HOST --sandbox NAME は、そのサンドボックスのレジストリ認証情報のみを削除します。ホスト専用およびグローバル（すべてのサンドボックス対象）のエントリには影響しません。この操作で上流のトークンが失効することも、別の適用可能な認証情報が使用されなくなることもありません。

  sbx secret rm --registry ghcr.io --sandbox my-sandbox
  

• --sandbox を指定せずに sbx secret rm --registry HOST を実行すると、ホスト専用とグローバルの両方のエントリが削除されます。グローバルのエントリのみを削除するには、--all-sandboxes を追加してください。

関連するスキル

• docker agent run --sandbox および docker agent sandbox コマンドには、 docker-agent-run を使用してください。

• これらのポリシーやシークレットが適用されるサンドボックスの作成、再接続、削除には、docker-sandboxes-lifecycle を使用してください。

• チェックインされた sbxenv.yaml ファイル内で secrets:／registries:／bindings: を宣言し、環境の作成時にプロビジョニングするには、docker-sandboxes-env を使用してください。

• キット独自の credentials: および permissions.network: の宣言（ユーザーが承認した内容ではなく、キットが要求する内容）には、docker-sandboxes-kits を使用してください。

参照

• references/sources.md — 上記の各ルールの根拠（ヘルプの記録、ソースパス、ドキュメントの URL）。

アセット

• なし。

チェック

• checks/verification.md — ネットワークポリシーとシークレットコマンドの検証手順（未実行の手順書です。実際のシークレット値は使用せず、分離された --app-name を指定して手動で実行してください）。