216 lines
9.4 KiB
Plaintext
216 lines
9.4 KiB
Plaintext
---
|
||
title: "沙箱机制 - 权限之外的第二道防线"
|
||
description: "深入 Claude Code 沙箱机制：文件系统隔离、网络限制和资源约束，即使命令通过权限审批，沙箱仍可限制其行为范围。"
|
||
keywords: ["沙箱", "sandbox", "文件隔离", "安全沙箱", "命令隔离"]
|
||
---
|
||
|
||
## 权限之外的第二道防线
|
||
|
||
权限系统决定"这条命令能不能执行"，沙箱决定"执行时能做到什么程度"。
|
||
|
||
即使一条命令通过了权限审批，沙箱仍然可以限制它的行为。两者构成纵深防御的两层：
|
||
- **权限层**（应用级）：在工具调用前检查，决定是否弹窗审批
|
||
- **沙箱层**（OS 级）：在进程级别强制约束，即使 AI 生成了恶意命令也无法突破
|
||
|
||
## 执行链路：从用户输入到沙箱包裹
|
||
|
||
一条 Bash 命令的完整执行路径如下：
|
||
|
||
```
|
||
用户输入 → BashTool.call()
|
||
→ shouldUseSandbox(input) ─── 是否需要沙箱？
|
||
→ Shell.exec(command, { shouldUseSandbox })
|
||
→ SandboxManager.wrapWithSandbox(command)
|
||
→ spawn(wrapped_command) ─── 实际进程创建
|
||
```
|
||
|
||
关键判定发生在 `shouldUseSandbox()`（`src/tools/BashTool/shouldUseSandbox.ts`），它执行以下检查：
|
||
|
||
1. **全局开关**：`SandboxManager.isSandboxingEnabled()` — 检查平台支持 + 依赖完整性 + 用户设置
|
||
2. **显式跳过**：如果 `dangerouslyDisableSandbox: true` 且策略允许（`allowUnsandboxedCommands`），则不走沙箱
|
||
3. **排除列表**：用户可在 `settings.json` 中配置 `sandbox.excludedCommands`，匹配的命令跳过沙箱
|
||
4. **默认行为**：以上条件都不满足时，**进入沙箱**
|
||
|
||
## `shouldUseSandbox()` 判定逻辑详解
|
||
|
||
```typescript
|
||
// src/tools/BashTool/shouldUseSandbox.ts
|
||
function shouldUseSandbox(input: Partial<SandboxInput>): boolean {
|
||
// 1. 全局未启用 → 直接跳过
|
||
if (!SandboxManager.isSandboxingEnabled()) return false
|
||
|
||
// 2. 显式禁用 + 策略允许 → 跳过
|
||
if (input.dangerouslyDisableSandbox &&
|
||
SandboxManager.areUnsandboxedCommandsAllowed()) return false
|
||
|
||
// 3. 无命令 → 跳过
|
||
if (!input.command) return false
|
||
|
||
// 4. 匹配排除列表 → 跳过
|
||
if (containsExcludedCommand(input.command)) return false
|
||
|
||
// 5. 其他情况 → 必须沙箱化
|
||
return true
|
||
}
|
||
```
|
||
|
||
`containsExcludedCommand()` 的匹配机制值得注意——它不只是简单的前缀匹配，而是支持三种模式：
|
||
|
||
| 模式 | 示例 | 匹配行为 |
|
||
|------|------|----------|
|
||
| **精确匹配** | `npm run lint` | 完全相等 |
|
||
| **前缀匹配** | `npm run test:*` | 前缀 + 空格或完全相等 |
|
||
| **通配符** | `docker*` | 使用 `matchWildcardPattern` |
|
||
|
||
对于复合命令（如 `docker ps && curl evil.com`），系统会先拆分为子命令，逐一检查。还会迭代剥离环境变量前缀（`FOO=bar bazel ...`）和包装命令（`timeout 30 bazel ...`），直到不动点——防止通过嵌套包装绕过。
|
||
|
||
## 沙箱的配置模型
|
||
|
||
沙箱配置来自 `settings.json` 中的 `sandbox` 字段（`src/entrypoints/sandboxTypes.ts`）：
|
||
|
||
```jsonc
|
||
{
|
||
"sandbox": {
|
||
"enabled": true, // 主开关
|
||
"autoAllowBashIfSandboxed": true, // 沙箱中的命令自动允许（跳过审批）
|
||
"allowUnsandboxedCommands": true, // 是否允许 dangerouslyDisableSandbox
|
||
"failIfUnavailable": false, // 沙箱依赖缺失时是否报错退出
|
||
|
||
"network": {
|
||
"allowedDomains": ["github.com"], // 网络白名单
|
||
"deniedDomains": [], // 网络黑名单
|
||
"allowLocalBinding": true, // 允许 localhost 绑定
|
||
"httpProxyPort": 8888 // HTTP 代理端口（MITM）
|
||
},
|
||
|
||
"filesystem": {
|
||
"allowWrite": ["~/projects"], // 额外可写路径
|
||
"denyWrite": ["~/.ssh"], // 禁止写入路径
|
||
"denyRead": [], // 禁止读取路径
|
||
"allowRead": [] // 在 denyRead 中重新放行
|
||
},
|
||
|
||
"excludedCommands": ["docker", "npm:*"] // 不走沙箱的命令
|
||
}
|
||
}
|
||
```
|
||
|
||
`SandboxSettingsSchema` 定义了完整的 Zod 验证规则，包含一些未公开的设置如 `enabledPlatforms`（限制沙箱只在特定平台生效）。
|
||
|
||
## 平台实现差异
|
||
|
||
### macOS：sandbox-exec（Seatbelt）
|
||
|
||
macOS 使用 Apple 的 Seatbelt 沙箱（`sandbox-exec` 命令），这是 macOS 原生的进程隔离机制。
|
||
|
||
执行流程：
|
||
1. `SandboxManager.wrapWithSandbox()` 调用 `@anthropic-ai/sandbox-runtime` 的 `BaseSandboxManager`
|
||
2. 运行时生成 Seatbelt profile（基于配置中的网络/文件系统规则）
|
||
3. 通过 `sandbox-exec -p <profile> -- <command>` 包裹原始命令
|
||
4. Seatbelt 在内核级别强制执行约束
|
||
|
||
网络隔离的实现方式：
|
||
- 通过代理端口拦截 HTTP/HTTPS 请求
|
||
- 域名白名单/黑名单在代理层过滤
|
||
- Unix socket 可单独配置允许路径
|
||
|
||
### Linux：bubblewrap（bwrap）+ seccomp
|
||
|
||
Linux 使用 `bubblewrap`（bwrap）创建命名空间隔离，配合 seccomp 过滤系统调用：
|
||
|
||
依赖项（`apt install`）：
|
||
| 包 | 作用 |
|
||
|----|------|
|
||
| `bubblewrap` | 创建 mount/PID/network 命名空间 |
|
||
| `socat` | 网络代理（HTTP/SOCKS） |
|
||
| `libseccomp` / seccomp filter | 过滤 Unix socket 系统调用 |
|
||
|
||
bwrap 的实现差异：
|
||
- **不支持 glob 路径模式**（macOS 的 Seatbelt 支持）— Linux 上带 glob 的权限规则会触发警告
|
||
- 执行后会在当前目录留下 0 字节的 mount-point 文件（如 `.bashrc`），需要 `cleanupAfterCommand()` 清理
|
||
- seccomp 无法按路径过滤 Unix socket（只能全允许或全拒绝），与 macOS 的按路径放行形成差异
|
||
|
||
### 平台支持矩阵
|
||
|
||
| 特性 | macOS | Linux | WSL |
|
||
|------|-------|-------|-----|
|
||
| 沙箱引擎 | sandbox-exec (Seatbelt) | bubblewrap + seccomp | 仅 WSL2 |
|
||
| 文件 glob | ✅ 完整支持 | ⚠️ 仅 `/**` 后缀 | 同 Linux |
|
||
| 网络 Unix socket 按路径 | ✅ | ❌ | ❌ |
|
||
| 依赖检查 | ripgrep | bwrap + socat + ripgrep + seccomp | 同 Linux |
|
||
|
||
## 沙箱初始化流程
|
||
|
||
```
|
||
REPL/SDK 启动
|
||
→ main.tsx → init.ts
|
||
→ SandboxManager.initialize(sandboxAskCallback)
|
||
→ detectWorktreeMainRepoPath() // 检测 git worktree，放行主仓库 .git
|
||
→ convertToSandboxRuntimeConfig() // 构建 SandboxRuntimeConfig
|
||
→ BaseSandboxManager.initialize() // 启动底层运行时
|
||
→ settingsChangeDetector.subscribe() // 订阅设置变更，动态更新配置
|
||
```
|
||
|
||
`convertToSandboxRuntimeConfig()`（`src/utils/sandbox/sandbox-adapter.ts`）完成从用户设置到运行时配置的转换：
|
||
|
||
1. **网络规则**：从 `WebFetch(domain:...)` 权限规则提取域名 → `allowedDomains`
|
||
2. **文件系统规则**：从 `Edit(...)` / `Read(...)` 权限规则提取路径 → `allowWrite` / `denyWrite` / `denyRead`
|
||
3. **安全加固**：
|
||
- 自动将项目目录加入 `allowWrite`
|
||
- 自动将 `settings.json` 路径加入 `denyWrite`（防止沙箱逃逸）
|
||
- 自动将 `.claude/skills` 加入 `denyWrite`（防止技能注入）
|
||
- 检测 bare git repo 攻击向量，对 `HEAD`/`objects`/`refs` 做保护
|
||
|
||
## `dangerouslyDisableSandbox` 的设计权衡
|
||
|
||
这个参数的命名本身就传达了设计意图——它不是"关闭沙箱"，而是"**危险地禁用沙箱**"。
|
||
|
||
双重保险机制：
|
||
1. **调用侧**：模型在 BashTool 的 `inputSchema` 中可以设置 `dangerouslyDisableSandbox: true`
|
||
2. **策略侧**：管理员可通过 `allowUnsandboxedCommands: false` 完全禁止此参数（企业部署场景）
|
||
|
||
```typescript
|
||
// 即使 AI 请求了 dangerouslyDisableSandbox，策略层仍可覆盖
|
||
if (input.dangerouslyDisableSandbox &&
|
||
SandboxManager.areUnsandboxedCommandsAllowed()) {
|
||
return false // 只有策略允许时才真正跳过沙箱
|
||
}
|
||
```
|
||
|
||
`autoAllowBashIfSandboxed` 进一步补充了这个模型：当启用时，**在沙箱中的命令自动获得执行许可**，无需逐条审批。这基于一个信任假设——如果 OS 级沙箱已经限制了命令的能力，那么应用层的逐条审批就变得多余。
|
||
|
||
## 沙箱违规处理
|
||
|
||
当命令尝试违反沙箱约束时：
|
||
|
||
1. 运行时捕获违规事件（文件/网络访问被拒绝）
|
||
2. `SandboxManager.annotateStderrWithSandboxFailures()` 在输出中注入 `<sandbox_violations>` 标签
|
||
3. UI 层通过 `removeSandboxViolationTags()` 清理显示
|
||
4. 违规事件通过 `SandboxViolationStore` 持久化，可用于审计
|
||
|
||
## 完整执行链路示例
|
||
|
||
以 `npm install` 为例：
|
||
|
||
```
|
||
1. 用户在 REPL 中输入 → Claude 决定调用 BashTool
|
||
2. BashTool.validateInput() → 通过
|
||
3. BashTool.checkPermissions() → 检查权限规则
|
||
├── autoAllowBashIfSandboxed = true 且沙箱可用 → 自动允许
|
||
└── 否则 → 弹窗请用户确认
|
||
4. BashTool.call() → runShellCommand()
|
||
5. shouldUseSandbox({ command: "npm install" })
|
||
├── SandboxManager.isSandboxingEnabled() → true
|
||
├── dangerouslyDisableSandbox → undefined
|
||
└── containsExcludedCommand() → false（除非用户配置了排除 npm）
|
||
→ 结果: true，需要沙箱
|
||
6. Shell.exec() → SandboxManager.wrapWithSandbox("npm install")
|
||
├── macOS: sandbox-exec -p <generated-profile> -- bash -c 'npm install'
|
||
└── Linux: bwrap ... bash -c 'npm install'
|
||
7. spawn(wrapped_command) → 子进程在沙箱内执行
|
||
8. 执行完成 → SandboxManager.cleanupAfterCommand()
|
||
├── 清理 bwrap 残留文件（Linux）
|
||
└── scrubBareGitRepoFiles()（安全清理）
|
||
9. 结果返回给 Claude → 展示给用户
|
||
```
|