3.12 沙箱安全（Sandboxing）

概述

沙箱为 Claude Code 的 Bash 工具提供 OS 级文件系统和网络隔离，减少频繁权限提示的需求，同时防止提示注入和恶意命令。

工作原理

文件系统隔离

• 默认情况下，沙箱命令只能写入当前工作目录及其子目录
• 读取权限覆盖整台计算机（除拒绝路径外）
• 通过 Seatbelt（macOS）或 bubblewrap（Linux/WSL2）在 OS 级别强制执行

网络隔离

• 所有网络流量通过内置代理路由
• 代理强制执行域名白名单
• 新域名请求触发权限提示（除非启用 allowManagedDomainsOnly）

前提条件

• macOS：开箱即用（Seatbelt）
• Linux/WSL2：需要 bubblewrap 和 socat
• WSL1：不支持

配置选项

settings.json 配置

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build-output"],   // 允许写入的额外路径
      "denyRead": ["/etc/passwd"],           // 拒绝读取的路径
      "denyWrite": ["/bin", "/usr/bin"],      // 拒绝写入的路径
      "allowRead": ["/var/log"]              // 在拒绝区域内重新允许读取
    },
    "network": {
      "allowedDomains": ["github.com", "api.example.com"],
      "deniedDomains": ["evil-site.com"]
    },
    "excludedCommands": ["docker *"],         // 强制在沙箱外执行的命令
    "allowUnsandboxedCommands": false,        // 禁用沙箱失败时的逃生口
    "failIfUnavailable": true                // 沙箱不可用时硬性失败
  }
}

安全优势

• 阻止修改关键文件（~/.bashrc、/bin/ 等）
• 防止数据泄露到未授权域名
• 抵御恶意依赖、被污染脚本和社会工程攻击

重要限制

• TLS 检查：内置代理不终止或检查 TLS 流量。允许 github.com 但不检查与其连接的内容。域名前置理论上是可能的。需要自定义代理进行 TLS 检查以获得更强的保证。
• Unix socket 升级：允许访问 Unix 套接字（如 docker.sock）可能导致沙箱绕过。
• 文件系统升级：过于宽泛的写入权限（如 $PATH 目录）可能导致在其他安全上下文中执行代码。
• Linux Docker 模式：enableWeakerNestedSandbox 会大大削弱安全性，仅在额外隔离被强制执行时使用。
• 内置文件工具：Read、Edit、Write 等内置工具通过权限系统运行，而非通过沙箱。
• Computer Use：在真实桌面而非沙箱中运行。

自动模式

在 Auto-accept 权限模式下，沙箱命令自动运行而不提示。无法沙箱化的命令回退到常规权限流程。

开源

沙箱运行时作为 npx @anthropic-ai/sandbox-runtime 发布，可用于其他 Agent 项目。