# 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 模式下的所有命令
```

## 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 权限设置](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 在安全的沙箱中更自主地工作 🛡️*
