沙箱化

了解 CSC 的沙箱化 bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的代理执行。

概述

CSC 具有原生沙箱化功能，可为代理执行提供更安全的环境，同时减少对持续权限提示的需求。沙箱化不是为每个 bash 命令请求权限，而是预先创建定义的边界，使 CSC 可以在降低风险的情况下更自由地工作。

沙箱化的 bash 工具使用操作系统级原语来强制执行文件系统和网络隔离。

为什么沙箱化很重要

传统的基于权限的安全性需要用户不断批准 bash 命令。虽然这提供了控制力，但可能导致：

• 审批疲劳：反复点击"批准"可能导致用户不太关注他们正在批准的内容
• 降低生产力：持续的中断会减慢开发工作流
• 有限的自主性：CSC 在等待批准时无法高效工作

沙箱化通过以下方式解决这些挑战：

1. 定义清晰的边界：精确指定 CSC 可以访问哪些目录和网络主机
2. 减少权限提示：沙箱内的安全命令不需要批准
3. 维护安全性：尝试访问沙箱外资源会触发即时通知
4. 实现自主性：CSC 可以在定义的限制内更独立地运行

⚠️ 警告： 有效的沙箱化需要同时具备文件系统和网络隔离。如果没有网络隔离，受损的代理可能会窃取 SSH 密钥等敏感文件。如果没有文件系统隔离，受损的代理可能会后门系统资源以获取网络访问权限。在配置沙箱化时，确保配置的设置不会在这些系统中创建绕过是非常重要的。

工作原理

文件系统隔离

沙箱化的 bash 工具将文件系统访问限制在特定目录：

• 默认写入行为：对当前工作目录及其子目录的读写访问
• 默认读取行为：对整个计算机的读取访问，除了某些被拒绝的目录
• 阻止的访问：未经明确许可，无法修改当前工作目录之外的文件
• 可配置：通过设置定义自定义允许和拒绝的路径

你可以使用设置中的 sandbox.filesystem.allowWrite 授予对额外路径的写入访问权限。这些限制在操作系统级别强制执行（macOS 上使用 Seatbelt，Linux 上使用 bubblewrap），因此它们适用于所有子进程命令，包括 kubectl、terraform 和 npm 等工具，而不仅仅是 CSC 的文件工具。

网络隔离

网络访问通过在沙箱外运行的代理服务器控制：

• 域名限制：只能访问已批准的域名
• 用户确认：新域名请求会触发权限提示（除非启用了 allowManagedDomainsOnly，这会自动阻止未允许的域名）
• 自定义代理支持：高级用户可以对出站流量实施自定义规则
• 全面覆盖：限制适用于命令生成的所有脚本、程序和子进程

操作系统级强制执行

沙箱化的 bash 工具利用操作系统安全原语：

• macOS：使用 Seatbelt 进行沙箱强制执行
• Linux：使用 bubblewrap 进行隔离
• WSL2：使用 bubblewrap，与 Linux 相同

不支持 WSL1，因为 bubblewrap 需要 WSL2 中才有的内核功能。

这些操作系统级限制确保 CSC 命令生成的所有子进程继承相同的安全边界。

入门

先决条件

在 macOS 上，沙箱化使用内置的 Seatbelt 框架开箱即用。

在 Linux 和 WSL2 上，首先安装所需的包：

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

启用沙箱化

你可以通过运行 /sandbox 命令来启用沙箱化：

/sandbox

这会打开一个菜单，你可以在其中选择沙箱模式。如果缺少所需的依赖项（例如 Linux 上的 bubblewrap 或 socat），菜单会显示你平台的安装说明。

默认情况下，如果沙箱无法启动（缺少依赖项、不支持的平台或平台限制），CSC 会显示警告并在不使用沙箱化的情况下运行命令。要将其改为硬性失败，请将 sandbox.failIfUnavailable 设置为 true。这适用于需要沙箱化作为安全门的托管部署。

沙箱模式

CSC 提供两种沙箱模式：

自动允许模式：Bash 命令将尝试在沙箱内运行，并自动允许而无需权限。无法沙箱化的命令（例如需要网络访问非允许主机的命令）会回退到常规权限流程。明确的拒绝规则始终受到尊重。询问规则仅适用于回退到常规权限流程的命令。

常规权限模式：所有 bash 命令都经过标准权限流程，即使已沙箱化。这提供了更多控制，但需要更多批准。

在两种模式下，沙箱强制执行相同的文件系统和网络限制。区别仅在于沙箱化的命令是自动批准还是需要明确权限。

ℹ️ 信息： 自动允许模式独立于你的权限模式设置运行。即使你不在"接受编辑"模式下，启用自动允许时沙箱化的 bash 命令也会自动运行。这意味着在沙箱边界内修改文件的 bash 命令将在不提示的情况下执行，即使文件编辑工具通常需要批准。

配置沙箱化

通过 settings.json 文件自定义沙箱行为。有关完整的配置参考，请参阅设置。

授予子进程对特定路径的写入访问权限

默认情况下，沙箱化的命令只能写入当前工作目录。如果 kubectl、terraform 或 npm 等子进程命令需要在项目目录之外写入，请使用 sandbox.filesystem.allowWrite 授予对特定路径的访问权限：

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

这些路径在操作系统级别强制执行，因此在沙箱内运行的所有命令（包括其子进程）都会遵守它们。当工具需要对特定位置的写入访问权限时，这是推荐的方法，而不是使用 excludedCommands 将工具完全排除在沙箱之外。

当 allowWrite（或 denyWrite/denyRead/allowRead）在多个设置范围中定义时，数组会被合并，这意味着来自每个范围的路径会被组合，而不是替换。例如，如果托管设置允许写入 /opt/company-tools，而用户在其个人设置中添加了 ~/.kube，则两个路径都包含在最终的沙箱配置中。这意味着用户和项目可以扩展列表，而无需复制或覆盖更高优先级范围设置的路径。

路径前缀控制路径的解析方式：

前缀	含义	示例
/	从文件系统根目录的绝对路径	/tmp/build 保持为 /tmp/build
~/	相对于主目录	~/.kube 变为 $HOME/.kube
./ 或无前缀	对于项目设置相对于项目根目录，对于用户设置相对于 ~/.costrict	.costrict/settings.json 中的 ./output 解析为 <project-root>/output

旧的 //path 前缀用于绝对路径仍然有效。如果你之前使用单斜杠 /path 期望项目相对解析，请切换到 ./path。此语法不同于读取和编辑权限规则，后者使用 //path 表示绝对路径，/path 表示项目相对路径。沙箱文件系统路径使用标准约定：/tmp/build 是绝对路径。

你还可以使用 sandbox.filesystem.denyWrite 和 sandbox.filesystem.denyRead 拒绝写入或读取访问。这些与 Edit(...) 和 Read(...) 权限规则中的任何路径合并。要重新允许读取被拒绝区域内的特定路径，请使用 sandbox.filesystem.allowRead，它优先于 denyRead。当在托管设置中启用 allowManagedReadPathsOnly 时，仅尊重托管的 allowRead 条目；用户、项目和本地的 allowRead 条目将被忽略。denyRead 仍然从所有来源合并。

例如，要阻止从整个主目录读取，同时仍允许从当前项目读取，请将以下内容添加到项目的 .costrict/settings.json 中：

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

allowRead 中的 . 解析为项目根目录，因为此配置位于项目设置中。如果你将相同的配置放在 ~/.costrict/settings.json 中，. 将解析为 ~/.costrict，项目文件仍将被 denyRead 规则阻止。

💡 提示： 并非所有命令都与沙箱化开箱即用兼容。以下提示可能有助于你充分利用沙箱：

• 许多 CLI 工具需要访问某些主机。当你使用这些工具时，它们会请求访问某些主机的权限。授予权限将允许它们现在和将来访问这些主机，使它们能够在沙箱内安全执行。
• watchman 与在沙箱中运行不兼容。如果你正在运行 jest，请考虑使用 jest --no-watchman
• docker 与在沙箱中运行不兼容。请考虑在 excludedCommands 中指定 docker * 以强制其在沙箱外运行。

注意： CSC 包含一个有意设计的逃逸机制，允许命令在必要时在沙箱外运行。当命令因沙箱限制（例如网络连接问题或不兼容的工具）而失败时，CSC 会被提示分析失败原因，并可能使用 dangerouslyDisableSandbox 参数重试命令。使用此参数的命令会经过正常的 CSC 权限流程，需要用户权限才能执行。这允许 CSC 处理某些工具或网络操作无法在沙箱约束内运行的情况。

你可以通过在沙箱设置中设置 "allowUnsandboxedCommands": false 来禁用此逃逸机制。禁用后，dangerouslyDisableSandbox 参数将被完全忽略，所有命令必须在沙箱中运行或明确列在 excludedCommands 中。

安全优势

防御提示注入

即使攻击者通过提示注入成功操纵了 CSC 的行为，沙箱也能确保你的系统保持安全：

文件系统保护：

• 无法修改关键配置文件，如 ~/.bashrc
• 无法修改 /bin/ 中的系统级文件
• 无法读取 CSC 权限设置中被拒绝的文件

网络保护：

• 无法将数据泄露到攻击者控制的服务器
• 无法从未经授权的域名下载恶意脚本
• 无法向未批准的服务发出意外的 API 调用
• 无法联系任何未明确允许的域名

监控和控制：

• 所有沙箱外的访问尝试都在操作系统级别被阻止
• 当边界受到测试时，你会收到即时通知
• 你可以选择拒绝、允许一次或永久更新你的配置

减少攻击面

沙箱化限制了以下潜在损害：

• 恶意依赖项：包含有害代码的 NPM 包或其他依赖项
• 受损的脚本：具有安全漏洞的构建脚本或工具
• 社会工程：诱骗用户运行危险命令的攻击
• 提示注入：诱骗 CSC 运行危险命令的攻击

透明操作

当 CSC 尝试访问沙箱外的网络资源时：

1. 操作在操作系统级别被阻止
2. 你会收到即时通知
3. 你可以选择：
   • 拒绝请求
   • 允许一次
   • 更新你的沙箱配置以永久允许

安全限制

• 网络沙箱化限制：网络过滤系统通过限制进程允许连接的域名来运作。它不会以其他方式检查通过代理的流量，用户有责任确保他们在策略中仅允许受信任的域名。

⚠️ 警告： 用户应注意允许广泛域名（如 github.com）可能带来的潜在风险，这可能允许数据泄露。此外，在某些情况下，可能通过域名前置绕过网络过滤。

• 通过 Unix 套接字的权限提升：allowUnixSockets 配置可能无意中授予对强大系统服务的访问权限，这可能导致沙箱绕过。例如，如果它被用于允许访问 /var/run/docker.sock，这将通过利用 docker 套接字有效地授予对主机系统的访问权限。鼓励用户仔细考虑他们通过沙箱允许的任何 Unix 套接字。
• 文件系统权限提升：过于宽泛的文件系统写入权限可能导致权限提升攻击。允许写入包含 $PATH 中可执行文件的目录、系统配置目录或用户 shell 配置文件（.bashrc、.zshrc）的目录，可能导致在其他用户或系统进程访问这些文件时在不同安全上下文中执行代码。
• Linux 沙箱强度：Linux 实现提供了强大的文件系统和网络隔离，但包含一个 enableWeakerNestedSandbox 模式，使其能够在没有特权命名空间的 Docker 环境中工作。此选项会大大削弱安全性，应仅在其他隔离已被强制执行的情况下使用。

沙箱化与权限的关系

沙箱化和权限是协同工作的互补安全层：

• 权限控制 CSC 可以使用哪些工具，并在任何工具运行之前进行评估。它们适用于所有工具：Bash、Read、Edit、WebFetch、MCP 等。
• 沙箱化提供操作系统级强制执行，限制 Bash 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash 命令及其子进程。

文件系统和网络限制通过沙箱设置和权限规则共同配置：

• 使用 sandbox.filesystem.allowWrite 授予子进程对工作目录之外路径的写入访问权限
• 使用 sandbox.filesystem.denyWrite 和 sandbox.filesystem.denyRead 阻止子进程对特定路径的访问
• 使用 sandbox.filesystem.allowRead 重新允许读取 denyRead 区域内的特定路径
• 使用 Read 和 Edit 拒绝规则阻止对特定文件或目录的访问
• 使用 WebFetch 允许/拒绝规则控制域名访问
• 使用沙箱 allowedDomains 控制 Bash 命令可以访问的域名

来自 sandbox.filesystem 设置和权限规则的路径会合并到最终的沙箱配置中。

此仓库包含常见部署场景的入门设置配置，包括沙箱特定的示例。将这些作为起点并根据你的需求进行调整。

高级用法

自定义代理配置

对于需要高级网络安全性的组织，你可以实现自定义代理以：

• 解密和检查 HTTPS 流量
• 应用自定义过滤规则
• 记录所有网络请求
• 与现有安全基础设施集成

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

与现有安全工具集成

沙箱化的 bash 工具可与以下工具配合使用：

• 权限规则：与权限设置结合实现纵深防御
• 开发容器：与开发容器一起使用以获得额外隔离
• 企业策略：通过托管设置强制执行沙箱配置

最佳实践

1. 从限制开始：从最小权限开始，根据需要扩展
2. 监控日志：查看沙箱违规尝试以了解 CSC 的需求
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 直接使用权限系统，而不是通过沙箱运行。请参阅权限。
• 计算机使用：当 CSC 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离环境中运行。每个应用程序的权限提示控制每个应用程序。请参阅 CLI 中的计算机使用或桌面中的计算机使用。