@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/cn/cli/bash-sandboxing.md

@@ -0,0 +1,290 @@
+# Bash 沙箱
+
+> 了解 CodeBuddy Code 的沙箱化 Bash 工具如何提供文件系统和网络隔离，实现更安全、更自主的智能体执行。
+
+## 概述
+
+CodeBuddy Code 具有原生沙箱功能，为智能体执行提供更安全的环境，同时减少持续的权限提示。沙箱不需要为每个 bash 命令请求权限，而是预先创建定义好的边界，让 CodeBuddy Code 可以在降低风险的情况下更自由地工作。
+
+沙箱化 Bash 工具使用操作系统级原语来强制执行文件系统和网络隔离。
+
+## 为什么沙箱很重要
+
+传统的基于权限的安全性需要持续的用户批准才能执行 bash 命令。虽然这提供了控制，但可能导致：
+
+* **审批疲劳**：重复点击"批准"可能导致用户对批准的内容关注度降低
+* **降低生产力**：持续的中断会减慢开发工作流程
+* **有限的自主性**：在等待批准时，CodeBuddy Code 无法高效工作
+
+沙箱通过以下方式解决这些挑战：
+
+1. **定义清晰的边界**：明确指定 CodeBuddy Code 可以访问哪些目录和网络主机
+2. **减少权限提示**：沙箱内的安全命令不需要批准
+3. **保持安全性**：访问沙箱外资源的尝试会立即触发通知
+4. **实现自主性**: CodeBuddy Code 可以在定义的限制内更独立地运行
+
+<Warning>
+  有效的沙箱需要**同时**具备文件系统和网络隔离。没有网络隔离，受损的智能体可能会窃取敏感文件（如 SSH 密钥）。没有文件系统隔离，受损的智能体可能会后门系统资源以获得网络访问。配置沙箱时，确保你的配置设置不会在这些系统中创建绕过方式非常重要。
+</Warning>
+
+## 工作原理
+
+### 文件系统隔离
+
+沙箱化 Bash 工具将文件系统访问限制在特定目录：
+
+* **默认写入行为**：对当前工作目录及其子目录具有读写访问权限
+* **默认读取行为**：对整个计算机具有读取访问权限，除了某些被拒绝的目录
+* **阻止访问**：未经明确许可，无法修改当前工作目录之外的文件
+* **可配置**：通过设置定义自定义的允许和拒绝路径
+
+### 网络隔离
+
+网络访问通过在沙箱外运行的代理服务器控制：
+
+* **域限制**：只能访问批准的域
+* **用户确认**：新的域请求会触发权限提示
+* **自定义代理支持**：高级用户可以对出站流量实施自定义规则
+* **全面覆盖**：限制适用于命令生成的所有脚本、程序和子进程
+
+### 操作系统级强制执行
+
+沙箱化 Bash 工具利用操作系统安全原语：
+
+* **Linux**: 使用 [bubblewrap](https://github.com/containers/bubblewrap) 进行隔离
+* **macOS**：使用 Seatbelt 进行沙箱强制执行
+
+这些操作系统级限制确保 CodeBuddy Code 命令生成的所有子进程都继承相同的安全边界。
+
+## 入门
+
+### 启用沙箱
+
+你可以通过运行 `/sandbox` 斜杠命令来启用沙箱：
+
+```
+> /sandbox
+```
+
+这将使用默认设置激活沙箱化 Bash 工具，允许访问当前工作目录，同时阻止访问敏感的系统位置。
+
+### 配置沙箱
+
+通过 `settings.json` 文件自定义沙箱行为。完整的配置参考请参阅[设置](settings.md#bash沙箱设置)。
+
+<Tip>
+  并非所有命令都能开箱即用地与沙箱兼容。以下一些注意事项可能帮助你充分利用沙箱：
+
+  * 许多 CLI 工具需要访问某些主机。当你使用这些工具时，它们会请求访问某些主机的权限。授予权限将允许它们现在和将来访问这些主机，使它们能够在沙箱内安全执行。
+  * `watchman` 与在沙箱中运行不兼容。如果你正在运行 `jest`,请考虑使用 `jest --no-watchman`
+  * `docker` 与在沙箱中运行不兼容。考虑在 `excludedCommands` 中指定 `docker` 以强制其在沙箱外运行。
+</Tip>
+
+<Note>
+  CodeBuddy Code 包含一个有意设置的逃生舱机制，允许在必要时在沙箱外运行命令。当命令因沙箱限制（如网络连接问题或不兼容的工具）而失败时，CodeBuddy 会被提示分析失败，并可能使用 `dangerouslyDisableSandbox` 参数重试命令。使用此参数的命令会经过正常的 CodeBuddy Code 权限流程，需要用户权限才能执行。这允许 CodeBuddy Code 处理某些工具或网络操作无法在沙箱约束内运行的边缘情况。
+
+  你可以通过在[沙箱设置](settings.md#bash沙箱设置)中设置 `"allowUnsandboxedCommands": false` 来禁用此逃生舱。禁用后,`dangerouslyDisableSandbox` 参数会被完全忽略,所有命令必须在沙箱中运行或明确列在 `excludedCommands` 中。
+</Note>
+
+## 沙箱自动批准
+
+在 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 配置文件（`settings.json`、`settings.local.json`），防止通过注入 hooks 实现沙箱逃逸
+* 无法读取在 [CodeBuddy 权限设置](iam.md#配置权限)中被拒绝的文件
+
+**网络保护：**
+
+* 无法将数据窃取到攻击者控制的服务器
+* 无法从未授权的域下载恶意脚本
+* 无法对未批准的服务进行意外的 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` 规则在所有工具中统一生效。
+
+### 减少攻击面
+
+沙箱限制了以下潜在损害：
+
+* **恶意依赖**：具有有害代码的 NPM 包或其他依赖项
+* **受损脚本**：具有安全漏洞的构建脚本或工具
+* **社会工程**：诱骗用户运行危险命令的攻击
+* **提示注入**：诱骗 CodeBuddy 运行危险命令的攻击
+
+### 透明操作
+
+当 CodeBuddy Code 尝试访问沙箱外的网络资源时：
+
+1. 操作在操作系统级别被阻止
+2. 你立即收到通知
+3. 你可以选择：
+   * 拒绝请求
+   * 允许一次
+   * 更新沙箱配置以永久允许
+
+## 安全限制
+
+* **网络沙箱限制**：网络过滤系统通过限制进程允许连接的域来运作。它不会检查通过代理的流量，用户有责任确保他们只允许其策略中的受信任域。
+
+<Warning>
+  用户应该意识到允许广泛域名(如 `github.com`)可能带来的风险,这可能允许数据窃取。此外,在某些情况下,可能通过[域前置](https://en.wikipedia.org/wiki/Domain_fronting)绕过网络过滤。
+</Warning>
+
+* **通过 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 策略**：与[权限设置](iam.md)结合使用以实现深度防御
+* **开发容器**：与 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 仓库](https://github.com/anthropic-experimental/sandbox-runtime)。
+
+## 限制
+
+* **性能开销**：最小，但某些文件系统操作可能略慢
+* **兼容性**：一些需要特定系统访问模式的工具可能需要配置调整，甚至可能需要在沙箱外运行
+* **平台支持**：目前支持 Linux 和 macOS;计划支持 Windows
+
+## 相关文档
+
+* [安全](security.md) - 全面的安全功能和最佳实践
+* [IAM](iam.md) - 权限配置和访问控制
+* [设置](settings.md) - 完整的配置参考
+
+---
+
+*让 CodeBuddy Code 在安全的沙箱中更自主地工作 🛡️*