Bash 沙箱 ​

了解 CodeBuddy Code 的沙箱化 Bash 工具如何提供文件系统和网络隔离，实现更安全、更自主的智能体执行。

概述 ​

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

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

为什么沙箱很重要 ​

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

  • 审批疲劳：重复点击"批准"可能导致用户对批准的内容关注度降低
  • 降低生产力：持续的中断会减慢开发工作流程
  • 有限的自主性：在等待批准时，CodeBuddy Code 无法高效工作

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

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

WARNING

有效的沙箱需要**同时**具备文件系统和网络隔离。没有网络隔离，受损的智能体可能会窃取敏感文件（如 SSH 密钥）。没有文件系统隔离，受损的智能体可能会后门系统资源以获得网络访问。配置沙箱时，确保你的配置设置不会在这些系统中创建绕过方式非常重要。

工作原理 ​

文件系统隔离 ​

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

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

网络隔离 ​

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

  • 域限制：只能访问批准的域
  • 用户确认：新的域请求会触发权限提示
  • 自定义代理支持：高级用户可以对出站流量实施自定义规则
  • 全面覆盖：限制适用于命令生成的所有脚本、程序和子进程

操作系统级强制执行 ​

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

  • Linux: 使用 bubblewrap 进行隔离
  • macOS：使用 Seatbelt 进行沙箱强制执行

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

入门 ​

启用沙箱 ​

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

> /sandbox

这将使用默认设置激活沙箱化 Bash 工具，允许访问当前工作目录，同时阻止访问敏感的系统位置。

配置沙箱 ​

通过 settings.json 文件自定义沙箱行为。完整的配置参考请参阅[设置](settings.md#bash沙箱设置）。

TIP

并非所有命令都能开箱即用地与沙箱兼容。以下一些注意事项可能帮助你充分利用沙箱：
  • 许多 CLI 工具需要访问某些主机。当你使用这些工具时，它们会请求访问某些主机的权限。授予权限将允许它们现在和将来访问这些主机，使它们能够在沙箱内安全执行。
  • watchman 与在沙箱中运行不兼容。如果你正在运行 jest,请考虑使用 jest --no-watchman
  • docker 与在沙箱中运行不兼容。考虑在 excludedCommands 中指定 docker 以强制其在沙箱外运行。

NOTE

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

你可以通过在[沙箱设置](settings.md#bash沙箱设置）中设置 "allowUnsandboxedCommands": false 来禁用此逃生舱。禁用后,dangerouslyDisableSandbox 参数会被完全忽略,所有命令必须在沙箱中运行或明确列在 excludedCommands 中。

沙箱自动批准 ​

在 AcceptEdits 权限模式下，CodeBuddy Code 提供了沙箱自动批准功能，进一步减少权限提示：

工作原理 ​

当启用沙箱自动批准时，满足以下所有条件的 Bash 命令将自动批准执行，无需用户确认：

  1. 当前处于 AcceptEdits 权限模式
  2. 沙箱已启用 (sandbox.enabled = true)
  3. 自动批准配置已开启 (sandbox.autoAllowBashIfSandboxed = true)
  4. 命令将在沙箱中运行 （不在 excludedCommands 列表中）
  5. 未使用 dangerouslyDisableSandbox 参数

配置示例 ​

在 .codebuddy/settings.json 中启用沙箱自动批准：

json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  }
}

使用场景 ​

自动批准 （无需用户确认）:

bash
# 在 AcceptEdits 模式下，这些命令会自动批准
npm test
npm run build
ls -la
grep "pattern" file.txt

需要批准 （以下情况仍需用户确认）:

bash
# 1. 排除的命令 （在 excludedCommands 中）
git push

# 2. 明确禁用沙箱的命令
# （使用 dangerouslyDisableSandbox 参数）

# 3. 在非 AcceptEdits 模式下的所有命令

安全保障 ​

沙箱自动批准在保持安全的同时提升效率：

  • ✅ 只在沙箱环境内：只有沙箱化的命令才能自动批准
  • ✅ 文件系统隔离：命令只能访问允许的目录
  • ✅ 网络隔离：命令只能访问批准的域名
  • ✅ 可配置边界：通过 excludedCommands 排除高风险命令
  • ✅ 安全优先：任何配置错误或异常都会回退到需要用户批准

最佳实践 ​

  1. 谨慎使用：只在理解沙箱限制的情况下启用自动批准
  2. 排除高风险命令：将 git push、rm -rf 等危险操作加入 excludedCommands
  3. 定期审查：检查日志了解哪些命令被自动批准
  4. 组合使用：配合 IAM 权限规则使用，提供深度防御

安全优势 ​

防范提示注入 ​

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

文件系统保护：

  • 无法修改关键配置文件，如 ~/.bashrc
  • 无法修改 /bin/ 中的系统级文件
  • 无法读取在 [CodeBuddy 权限设置](iam.md#配置权限）中被拒绝的文件

网络保护：

  • 无法将数据窃取到攻击者控制的服务器
  • 无法从未授权的域下载恶意脚本
  • 无法对未批准的服务进行意外的 API 调用
  • 无法联系任何未明确允许的域

监控和控制：

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

减少攻击面 ​

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

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

透明操作 ​

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

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

安全限制 ​

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

WARNING

用户应该意识到允许广泛域名(如 `github.com`)可能带来的风险,这可能允许数据窃取。此外,在某些情况下,可能通过[域前置](https://en.wikipedia.org/wiki/Domain_fronting)绕过网络过滤。
  • 通过 Unix 套接字的权限提升: allowUnixSockets 配置可能会无意中授予对强大系统服务的访问权限,这可能导致沙箱绕过。例如,如果使用它允许访问 /var/run/docker.sock,这将通过利用 docker 套接字有效地授予对主机系统的访问权限。鼓励用户仔细考虑他们允许通过沙箱的任何 unix 套接字。
  • 文件系统权限提升：过于宽泛的文件系统写入权限可能会启用权限提升攻击。允许对包含 $PATH 中可执行文件的目录、系统配置目录或用户 shell 配置文件(.bashrc、.zshrc)进行写入，当其他用户或系统进程访问这些文件时，可能导致在不同安全上下文中执行代码。
  • Linux 沙箱强度: Linux 实现提供了强大的文件系统和网络隔离，但包括一个 enableWeakerNestedSandbox 模式，使其能够在没有特权命名空间的 Docker 环境中工作。此选项会大大削弱安全性，只应在其他方式强制执行额外隔离的情况下使用。

高级用法 ​

自定义代理配置 ​

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

  • 解密和检查 HTTPS 流量
  • 应用自定义过滤规则
  • 记录所有网络请求
  • 与现有安全基础设施集成
json
{
  "sandbox": {
    "network": {
      "httpProxyPort"：8080,
      "socksProxyPort"：8081
    }
  }
}

与现有安全工具集成 ​

沙箱化 Bash 工具与以下工具协同工作：

  • IAM 策略：与权限设置结合使用以实现深度防御
  • 开发容器：与 devcontainers 一起使用以实现额外隔离
  • 企业策略：通过[管理设置](settings.md#设置优先级）强制执行沙箱配置

最佳实践 ​

  1. 从限制性开始：从最小权限开始，根据需要扩展
  2. 监控日志：审查沙箱违规尝试以了解 CodeBuddy Code 的需求
  3. 使用特定于环境的配置：为开发和生产环境使用不同的沙箱规则
  4. 与权限结合：将沙箱与 IAM 策略一起使用以实现全面安全
  5. 测试配置：验证你的沙箱设置不会阻止合法工作流程
  6. 谨慎使用自动批准：只在充分理解沙箱限制的情况下启用 autoAllowBashIfSandboxed

开源 ​

沙箱运行时可作为开源 npm 包用于你自己的智能体项目。这使更广泛的 AI 智能体社区能够构建更安全、更可靠的自主系统。这也可以用于沙箱化你可能希望运行的其他程序。例如，要沙箱化 MCP 服务器，你可以运行：

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

有关实现细节和源代码,请访问 GitHub 仓库。

限制 ​

  • 性能开销：最小，但某些文件系统操作可能略慢
  • 兼容性：一些需要特定系统访问模式的工具可能需要配置调整，甚至可能需要在沙箱外运行
  • 平台支持：目前支持 Linux 和 macOS;计划支持 Windows

相关文档 ​

  • 安全 - 全面的安全功能和最佳实践
  • IAM - 权限配置和访问控制
  • 设置 - 完整的配置参考

让 CodeBuddy Code 在安全的沙箱中更自主地工作 🛡️