SpyBara
Go Premium

sandboxing.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

This page contains 329 additions and 0 deletions.

2026
Mon 4 22:58

サンドボックス

Claude Code のサンドボックス化された bash ツールがファイルシステムとネットワークの分離を提供し、より安全で自律的なエージェント実行を実現する方法について学びます。

概要

Claude Code はネイティブサンドボックス機能を備えており、エージェント実行のためのより安全な環境を提供しながら、継続的な許可プロンプトの必要性を軽減します。各 bash コマンドの実行許可を求める代わりに、サンドボックス化により事前に定義された境界が作成され、Claude Code はリスクを軽減しながらより自由に動作できます。

サンドボックス化された bash ツールは OS レベルのプリミティブを使用して、ファイルシステムとネットワークの両方の分離を実施します。

サンドボックス化が重要な理由

従来の許可ベースのセキュリティでは、bash コマンドごとに継続的なユーザー承認が必要です。これは制御を提供しますが、以下の問題につながる可能性があります。

  • 承認疲れ：「承認」を繰り返しクリックすると、ユーザーが承認内容に注意を払わなくなる可能性があります
  • 生産性の低下：継続的な中断により開発ワークフローが遅くなります
  • 自律性の制限：Claude Code は承認を待つ際に効率的に動作できません

サンドボックス化はこれらの課題に以下の方法で対処します。

  1. 明確な境界を定義：Claude Code がアクセスできるディレクトリとネットワークホストを正確に指定します
  2. 許可プロンプトを削減：サンドボックス内の安全なコマンドは承認を必要としません
  3. セキュリティを維持：サンドボックス外のリソースへのアクセス試行は即座に通知をトリガーします
  4. 自律性を有効化：Claude Code は定義された制限内でより独立して実行できます

仕組み

ファイルシステム分離

サンドボックス化された bash ツールはファイルシステムアクセスを特定のディレクトリに制限します。

  • デフォルトの書き込み動作：現在の作業ディレクトリとそのサブディレクトリへの読み取りおよび書き込みアクセス
  • デフォルトの読み取り動作：特定の拒否ディレクトリを除く、コンピュータ全体への読み取りアクセス
  • ブロックされたアクセス：明示的な許可なしに現在の作業ディレクトリ外のファイルを変更できません
  • 設定可能：設定を通じてカスタム許可パスと拒否パスを定義します

sandbox.filesystem.allowWrite を設定で使用して、追加のパスへの書き込みアクセスを付与できます。これらの制限は OS レベル（macOS の Seatbelt、Linux の bubblewrap）で実施されるため、Claude のファイルツールだけでなく、kubectl、terraform、npm などのツールを含むすべてのサブプロセスコマンドに適用されます。

ネットワーク分離

ネットワークアクセスはサンドボックス外で実行されるプロキシサーバーを通じて制御されます。

  • ドメイン制限：承認されたドメインのみにアクセスできます
  • ユーザー確認：新しいドメインリクエストは許可プロンプトをトリガーします（allowManagedDomainsOnly が有効な場合を除き、許可されていないドメインを自動的にブロックします）
  • カスタムプロキシサポート：高度なユーザーは発信トラフィックにカスタムルールを実装できます
  • 包括的なカバレッジ：制限はすべてのスクリプト、プログラム、およびコマンドによって生成されるサブプロセスに適用されます

OS レベルの実施

サンドボックス化された bash ツールは OS セキュリティプリミティブを活用します。

  • macOS：Seatbelt をサンドボックス実施に使用します
  • Linux：分離に bubblewrap を使用します
  • WSL2：Linux と同じく bubblewrap を使用します

WSL1 は bubblewrap が WSL2 でのみ利用可能なカーネル機能を必要とするため、サポートされていません。

これらの OS レベルの制限により、Claude Code のコマンドによって生成されたすべての子プロセスが同じセキュリティ境界を継承することが保証されます。

開始方法

前提条件

macOS では、サンドボックス化は組み込みの Seatbelt フレームワークを使用してすぐに動作します。

Linux と WSL2 では、まず必要なパッケージをインストールしてください。

sudo apt-get install bubblewrap socat

WSL1 は必要な Linux 名前空間プリミティブが不足しているため、サンドボックス化をサポートしていません。Sandboxing requires WSL2 が表示される場合は、ディストリビューションを WSL2 にアップグレードするか、Claude Code をサンドボックス化なしで実行してください。

WSL2 では、サンドボックス化されたコマンドは cmd.exe、powershell.exe、または /mnt/c/ 下のものなどの Windows バイナリを起動できません。WSL はこれらを Unix ソケット経由で Windows ホストに渡しますが、サンドボックスはこれをブロックします。コマンドが Windows バイナリを呼び出す必要がある場合は、excludedCommands に追加して、サンドボックス外で実行するようにしてください。

サンドボックス化を有効化

/sandbox コマンドを実行してサンドボックス化を有効化できます。

/sandbox

これはサンドボックスモードを選択できるメニューを開きます。必要な依存関係（Linux の bubblewrap や socat など）が不足している場合、メニューはプラットフォームのインストール手順を表示します。

デフォルトでは、サンドボックスが起動できない場合（依存関係の不足またはサポートされていないプラットフォーム）、Claude Code は警告を表示してサンドボックス化なしでコマンドを実行します。これをハード失敗にするには、sandbox.failIfUnavailable を true に設定します。これは、セキュリティゲートとしてサンドボックス化を必要とする管理デプロイメント向けです。

サンドボックスモード

Claude Code は 2 つのサンドボックスモードを提供します。

自動許可モード：Bash コマンドはサンドボックス内で実行を試みられ、許可なしに自動的に許可されます。サンドボックス化できないコマンド（許可されていないホストへのネットワークアクセスが必要なコマンドなど）は通常の許可フローにフォールバックします。明示的な拒否ルールは常に尊重されます。また、rm または rmdir コマンドが /、ホームディレクトリ、または他の重要なシステムパスをターゲットにしている場合でも、許可プロンプトがトリガーされます。Ask ルールは通常の許可フローにフォールバックするコマンドにのみ適用されます。

通常の許可モード：すべての bash コマンドは、サンドボックス化されている場合でも標準的な許可フローを通じます。これはより多くの制御を提供しますが、より多くの承認が必要です。

両方のモードで、サンドボックスは同じファイルシステムとネットワーク制限を実施します。違いは、サンドボックス化されたコマンドが自動承認されるか明示的な許可が必要かだけです。

サンドボックス化を設定

settings.json ファイルを通じてサンドボックス動作をカスタマイズします。完全な設定リファレンスについては Settings を参照してください。

特定のパスへのサブプロセス書き込みアクセスの付与

デフォルトでは、サンドボックス化されたコマンドは現在の作業ディレクトリにのみ書き込みできます。kubectl、terraform、npm などのサブプロセスコマンドがプロジェクトディレクトリ外に書き込む必要がある場合、sandbox.filesystem.allowWrite を使用して特定のパスへのアクセスを付与します。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

これらのパスは OS レベルで実施されるため、サンドボックス内で実行されるすべてのコマンド（その子プロセスを含む）がそれらを尊重します。これは、excludedCommands でツールをサンドボックスから除外するのではなく、ツールが特定の場所への書き込みアクセスを必要とする場合の推奨アプローチです。

allowWrite（または denyWrite/denyRead/allowRead）が複数の 設定スコープ で定義されている場合、配列はマージされます。つまり、すべてのスコープからのパスが結合され、置き換えられません。たとえば、管理設定が /opt/company-tools への書き込みを許可し、ユーザーが個人設定で ~/.kube を追加する場合、両方のパスが最終的なサンドボックス設定に含まれます。これは、ユーザーとプロジェクトが、より高い優先度のスコープで設定されたパスを複製または上書きすることなく、リストを拡張できることを意味します。

パスプレフィックスはパスの解決方法を制御します。

プレフィックス 意味 例
/ ファイルシステムルートからの絶対パス /tmp/build は /tmp/build のままです
~/ ホームディレクトリからの相対パス ~/.kube は $HOME/.kube になります
./ またはプレフィックスなし プロジェクト設定の場合はプロジェクトルートからの相対パス、またはユーザー設定の場合は ~/.claude からの相対パス .claude/settings.json の ./output は <project-root>/output に解決されます

古い //path プレフィックスは絶対パスの場合でも機能します。以前に単一スラッシュ /path を使用してプロジェクト相対解決を期待していた場合は、./path に切り替えてください。この構文は Read と Edit 許可ルール とは異なります。これらは絶対パスに //path を使用し、プロジェクト相対に /path を使用します。サンドボックスファイルシステムパスは標準的な規則を使用します。/tmp/build は絶対パスです。

sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して書き込みまたは読み取りアクセスを拒否することもできます。これらは Edit(...) と Read(...) 許可ルールからのパスとマージされます。拒否された領域内の特定のパスの読み取りを再度許可するには、sandbox.filesystem.allowRead を使用します。これは denyRead より優先されます。管理設定で allowManagedReadPathsOnly が有効な場合、管理 allowRead エントリのみが尊重されます。ユーザー、プロジェクト、ローカルの allowRead エントリは無視されます。denyRead はすべてのソースからマージされます。

たとえば、ホームディレクトリ全体からの読み取りをブロックしながら、現在のプロジェクトからの読み取りを許可するには、プロジェクトの .claude/settings.json に以下を追加します。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

この設定がプロジェクト設定に存在するため、allowRead の . はプロジェクトルートに解決されます。同じ設定を ~/.claude/settings.json に配置した場合、. は ~/.claude に解決され、プロジェクトファイルは denyRead ルールによってブロックされたままになります。

セキュリティ上の利点

プロンプトインジェクションからの保護

攻撃者がプロンプトインジェクションを通じて Claude Code の動作を正常に操作した場合でも、サンドボックスはシステムのセキュリティを確保します。

ファイルシステム保護：

  • ~/.bashrc などの重要な設定ファイルを変更できません
  • /bin/ のシステムレベルファイルを変更できません
  • Claude 許可設定 で拒否されたファイルを読み取ることができません

ネットワーク保護：

  • 攻撃者が制御するサーバーへのデータ流出はできません
  • 許可されていないドメインから悪意のあるスクリプトをダウンロードできません
  • 承認されていないサービスへの予期しない API 呼び出しを行うことができません
  • 明示的に許可されていないドメインに連絡することはできません

監視と制御：

  • サンドボックス外のすべてのアクセス試行は OS レベルでブロックされます
  • 境界がテストされるときに即座に通知を受け取ります
  • リクエストを拒否、1 回だけ許可、または設定を永続的に更新することを選択できます

攻撃面の削減

サンドボックス化は以下からの潜在的な損害を制限します。

  • 悪意のある依存関係：有害なコードを含む NPM パッケージまたは他の依存関係
  • 侵害されたスクリプト：セキュリティ脆弱性を持つビルドスクリプトまたはツール
  • ソーシャルエンジニアリング：ユーザーに危険なコマンドを実行させるための攻撃
  • プロンプトインジェクション：Claude に危険なコマンドを実行させるための攻撃

透過的な操作

Claude Code がサンドボックス外のネットワークリソースにアクセスしようとする場合：

  1. 操作は OS レベルでブロックされます
  2. 即座に通知を受け取ります
  3. 以下を選択できます。
    • リクエストを拒否する
    • 1 回だけ許可する
    • サンドボックス設定を永続的に更新して許可する

セキュリティ上の制限

  • ネットワークサンドボックス化の制限：ネットワークフィルタリングシステムは、プロセスが接続を許可されるドメインを制限することで動作します。プロキシを通じて渡されるトラフィックを検査することはなく、ユーザーはポリシーで許可されたドメインが信頼できるドメインのみであることを確認する責任があります。
  • Unix ソケットを通じた権限昇格：allowUnixSockets 設定は、サンドボックスバイパスにつながる可能性のある強力なシステムサービスへのアクセスを不注意に付与する可能性があります。たとえば、/var/run/docker.sock へのアクセスを許可するために使用される場合、docker ソケットを悪用してホストシステムへのアクセスを効果的に付与します。ユーザーはサンドボックスを通じて許可する Unix ソケットを慎重に検討することをお勧めします。
  • ファイルシステム許可昇格：過度に広いファイルシステム書き込み許可は権限昇格攻撃を有効にする可能性があります。$PATH の実行可能ファイルを含むディレクトリ、システム設定ディレクトリ、またはユーザーシェル設定ファイル（.bashrc、.zshrc）への書き込みを許可すると、他のユーザーまたはシステムプロセスがこれらのファイルにアクセスするときに異なるセキュリティコンテキストでコード実行につながる可能性があります。
  • Linux サンドボックス強度：Linux 実装は強力なファイルシステムとネットワーク分離を提供しますが、特権のない名前空間なしで Docker 環境内で動作できるようにする enableWeakerNestedSandbox モードが含まれています。このオプションはセキュリティを大幅に弱め、追加の分離が別の方法で実施される場合にのみ使用する必要があります。

サンドボックス化が許可とどのように関連するか

サンドボックス化と 許可 は、一緒に動作する補完的なセキュリティレイヤーです。

  • 許可 は Claude Code が使用できるツールを制御し、任意のツールが実行される前に評価されます。これらは Bash、Read、Edit、WebFetch、MCP などすべてのツールに適用されます。
  • サンドボックス化 は、Bash コマンドがファイルシステムとネットワークレベルでアクセスできるものを制限する OS レベルの実施を提供します。これは Bash コマンドとその子プロセスにのみ適用されます。

ファイルシステムとネットワーク制限は、サンドボックス設定と許可ルールの両方を通じて設定されます。

  • sandbox.filesystem.allowWrite を使用して、作業ディレクトリ外のパスへのサブプロセス書き込みアクセスを付与します
  • sandbox.filesystem.denyWrite と sandbox.filesystem.denyRead を使用して、特定のパスへのサブプロセスアクセスをブロックします
  • sandbox.filesystem.allowRead を使用して、denyRead 領域内の特定のパスの読み取りを再度許可します
  • Read と Edit 拒否ルールを使用して、特定のファイルまたはディレクトリへのアクセスをブロックします
  • WebFetch 許可/拒否ルールを使用してドメインアクセスを制御します
  • サンドボックス allowedDomains を使用して、Bash コマンドが到達できるドメインを制御します
  • サンドボックス deniedDomains を使用して、より広い allowedDomains ワイルドカードが許可する場合でも、特定のドメインをブロックします

sandbox.filesystem 設定と許可ルールからのパスは、最終的なサンドボックス設定にマージされます。

この リポジトリ には、一般的なデプロイメントシナリオ（サンドボックス固有の例を含む）のスターター設定が含まれています。これらを出発点として使用し、ニーズに合わせて調整してください。

高度な使用方法

カスタムプロキシ設定

高度なネットワークセキュリティを必要とする組織の場合、カスタムプロキシを実装して以下を行うことができます。

  • HTTPS トラフィックを復号化して検査する
  • カスタムフィルタリングルールを適用する
  • すべてのネットワークリクエストをログに記録する
  • 既存のセキュリティインフラストラクチャと統合する
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

既存のセキュリティツールとの統合

サンドボックス化された bash ツールは以下と連携します。

  • 許可ルール：許可設定 と組み合わせて多層防御を実現します
  • 開発コンテナ：dev containers と共に使用して追加の分離を実現します
  • エンタープライズポリシー：管理設定 を通じてサンドボックス設定を実施します

ベストプラクティス

  1. 制限的に開始：最小限の許可で開始し、必要に応じて拡張します
  2. ログを監視：サンドボックス違反の試みを確認して、Claude Code のニーズを理解します
  3. 環境固有の設定を使用：開発環境と本番環境で異なるサンドボックスルールを使用します
  4. 許可と組み合わせる：包括的なセキュリティのためにサンドボックス化を IAM ポリシーと共に使用します
  5. 設定をテスト：サンドボックス設定が正当なワークフローをブロックしないことを確認します

オープンソース

サンドボックスランタイムは、独自のエージェントプロジェクトで使用するためのオープンソース npm パッケージとして利用可能です。これにより、より広い AI エージェントコミュニティがより安全で安全な自律システムを構築できます。これは、サンドボックス化したい他のプログラムをサンドボックス化するためにも使用できます。たとえば、MCP サーバーをサンドボックス化するには、以下を実行できます。

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

実装の詳細とソースコードについては、GitHub リポジトリ を参照してください。

制限事項

  • パフォーマンスオーバーヘッド：最小限ですが、一部のファイルシステム操作はわずかに遅くなる可能性があります
  • 互換性：特定のシステムアクセスパターンを必要とするツールの中には、設定調整が必要な場合や、サンドボックス外で実行する必要がある場合があります
  • プラットフォームサポート：macOS、Linux、WSL2 をサポートします。WSL1 はサポートされていません。ネイティブ Windows サポートは計画中です。

サンドボックス化がカバーしていないもの

サンドボックスは Bash サブプロセスを分離します。他のツールは異なる境界の下で動作します。

  • 組み込みファイルツール：Read、Edit、Write はサンドボックスを通じて実行するのではなく、許可システムを直接使用します。許可 を参照してください。
  • コンピュータ使用：Claude が macOS でアプリを開いてスクリーンを制御する場合、分離された環境ではなく実際のデスクトップで実行されます。アプリごとの許可プロンプトが各アプリケーションをゲートします。CLI でのコンピュータ使用 または Desktop でのコンピュータ使用 を参照してください。

関連項目

  • Security - 包括的なセキュリティ機能とベストプラクティス
  • Permissions - 許可設定とアクセス制御
  • Settings - 完全な設定リファレンス
  • CLI reference - コマンドラインオプション