CodeBuddy Bash 沙箱

二、为什么沙箱很重要

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

·审批疲劳：重复点击"批准"可能导致用户对批准的内容关注度降低

·降低生产力：持续的中断会减慢开发工作流程

·有限的自主性：在等待批准时，CodeBuddy Code 无法高效工作

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

1. 定义清晰的边界：明确指定 CodeBuddy Code 可以访问哪些目录和网络主机

2. 减少权限提示：沙箱内的安全命令不需要批准

3. 保持安全性：访问沙箱外资源的尝试会立即触发通知

4. 实现自主性：CodeBuddy Code 可以在定义的限制内更独立地运行

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

四、文件系统隔离

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

·默认写入行为：对当前工作目录及其子目录具有读写访问权限

·默认读取行为：对整个计算机具有读取访问权限，除了某些被拒绝的目录

·阻止访问：未经明确许可，无法修改当前工作目录之外的文件

·可配置：通过设置定义自定义的允许和拒绝路径

五、网络隔离

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

·域限制：只能访问批准的域

·用户确认：新的域请求会触发权限提示

·自定义代理支持：高级用户可以对出站流量实施自定义规则

·全面覆盖：限制适用于命令生成的所有脚本、程序和子进程

六、操作系统级强制执行

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

·Linux: 使用 bubblewrap 进行隔离

·macOS：使用 Seatbelt 进行沙箱强制执行

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

八、启用沙箱

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

> /sandbox

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

九、配置沙箱

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

注意：说明：

注意：并非所有命令都能开箱即用地与沙箱兼容。以下一些注意事项可能帮助你充分利用沙箱：

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

你可以通过在沙箱设置中设置 "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 中启用沙箱自动批准：

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

十三、使用场景

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

# 在 AcceptEdits 模式下，这些命令会自动批准npm testnpm run buildls -lagrep "pattern" file.txt

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

# 1. 排除的命令 （在 excludedCommands 中）git push# 2. 明确禁用沙箱的命令# （使用 dangerouslyDisableSandbox 参数）# 3. 在非 AcceptEdits 模式下的所有命令

十四、Bypass 权限模式下的沙箱越权自动放行

当命令尝试越过沙箱边界时（例如写入 .git/refs/*.lock、模型带 dangerouslyDisableSandbox=true 调用 Bash），沙箱会弹出"是否在沙箱外运行此命令"的二次审批。

从 v2.90.x 起，在 bypassPermissions 权限模式下，此类沙箱越权审批会对非高危命令自动放行，避免 cd X && yarn build 这类日常组合命令反复触发审批：

·自动放行：命令安全等级为 SAFE / LOW / MEDIUM 时，直接以 allow_once 继续执行

·仍需确认：命令安全等级为 HIGH / CRITICAL 时（如 rm -rf /、chmod 777 /etc 等），即使在 bypass 模式下也保留交互式审批

该策略与 bypass 模式下对 Bash 危险命令的保护语义一致——bypassPermissions 不等于无脑放行，高危操作永远需要显式确认。

十五、安全保障

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

·只在沙箱环境内：只有沙箱化的命令才能自动批准

·文件系统隔离：命令只能访问允许的目录

·网络隔离：命令只能访问批准的域名

·可配置边界：通过 excludedCommands 排除高风险命令

·安全优先：任何配置错误或异常都会回退到需要用户批准

十六、使用技巧

1. 谨慎使用：只在理解沙箱限制的情况下启用自动批准

2. 排除高风险命令：将 git push、rm -rf 等危险操作加入 excludedCommands

3. 定期审查：检查日志了解哪些命令被自动批准

4. 组合使用：配合 IAM 权限规则使用，提供深度防御

十八、防范提示注入

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

文件系统保护：

·无法修改关键配置文件，如 ~/.bashrc

·无法修改 /bin/ 中的系统级文件

·无法修改 CodeBuddy 配置文件（settings.json、settings.local.json），防止通过注入 hooks 实现沙箱逃逸

·无法读取在 CodeBuddy 权限设置中被拒绝的文件

网络保护：

·无法将数据窃取到攻击者控制的服务器

·无法从未授权的域下载恶意脚本

·无法对未批准的服务进行意外的 API 调用

·无法联系任何未明确允许的域

监控和控制：

·所有访问沙箱外的尝试都在操作系统级别被阻止

·当边界被测试时，你会立即收到通知

·你可以选择拒绝、允许一次或永久更新配置

十九、配置文件保护

沙箱默认阻止对 CodeBuddy 配置文件的写入，以防止沙箱逃逸攻击。攻击者可能通过提示注入让 Agent 写入 settings.json，注入恶意 SessionStart hooks，在用户下次启动 CodeBuddy 时以主机权限执行恶意命令。

以下配置文件在沙箱中受到写保护：

·~/.codebuddy/settings.json – 用户全局设置

·~/.codebuddy/settings.local.json – 用户本地设置

·.codebuddy/settings.json – 项目共享设置

·.codebuddy/settings.local.json – 项目本地设置

此保护同时应用于 Bash 命令和文件编辑工具（Write、Edit、MultiEdit），确保沙箱的 denyWrite 规则在所有工具中统一生效。

20、减少攻击面

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

·恶意依赖：具有有害代码的 NPM 包或其他依赖项

·受损脚本：具有安全漏洞的构建脚本或工具

·社会工程：诱骗用户运行危险命令的攻击

·提示注入：诱骗 CodeBuddy 运行危险命令的攻击

21、透明操作

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

1. 操作在操作系统级别被阻止

2. 你立即收到通知

3. 你可以选择：

·拒绝请求

·允许一次

·更新沙箱配置以永久允许

22、安全限制

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

注意：用户应该意识到允许广泛域名(如 github.com)可能带来的风险，这可能允许数据窃取。此外，在某些情况下，可能通过域前置绕过网络过滤。

·通过 Unix 套接字的权限提升: allowUnixSockets 配置可能会无意中授予对强大系统服务的访问权限,这可能导致沙箱绕过。例如,如果使用它允许访问 /var/run/docker.sock,这将通过利用 docker 套接字有效地授予对主机系统的访问权限。鼓励用户仔细考虑他们允许通过沙箱的任何 unix 套接字。

·文件系统权限提升：过于宽泛的文件系统写入权限可能会启用权限提升攻击。允许对包含 $PATH 中可执行文件的目录、系统配置目录或用户 shell 配置文件(.bashrc、.zshrc)进行写入，当其他用户或系统进程访问这些文件时，可能导致在不同安全上下文中执行代码。

·Linux 沙箱强度: Linux 实现提供了强大的文件系统和网络隔离，但包括一个 enableWeakerNestedSandbox 模式，使其能够在没有特权命名空间的 Docker 环境中工作。此选项会大大削弱安全性，只应在其他方式强制执行额外隔离的情况下使用。

24、自定义代理配置

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

·解密和检查 HTTPS 流量

·应用自定义过滤规则

·记录所有网络请求

·与现有安全基础设施集成

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

25、与现有安全工具集成

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

·IAM 策略：与权限设置结合使用以实现深度防御

·开发容器：与 devcontainers 一起使用以实现额外隔离

·企业策略：通过管理设置强制执行沙箱配置

26、使用技巧

1. 从限制性开始：从最小权限开始，根据需要扩展

2. 监控日志：审查沙箱违规尝试以了解 CodeBuddy Code 的需求

3. 使用特定于环境的配置：为开发和生产环境使用不同的沙箱规则

4. 与权限结合：将沙箱与 IAM 策略一起使用以实现全面安全

5. 测试配置：验证你的沙箱设置不会阻止合法工作流程

6. 谨慎使用自动批准：只在充分理解沙箱限制的情况下启用 autoAllowBashIfSandboxed

27、开源

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

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

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

28、限制

·性能开销：最小，但某些文件系统操作可能略慢

·兼容性：一些需要特定系统访问模式的工具可能需要配置调整，甚至可能需要在沙箱外运行

·平台支持：目前支持 Linux 和 macOS;计划支持 Windows

29、相关文档

·安全 – 全面的安全功能和实践教程

·IAM – 权限配置和访问控制

·设置 – 完整的配置参考