mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-23 00:35:51 +00:00
docs: 完成大量文档
This commit is contained in:
claude-code-best
@@ -3,33 +3,212 @@ title: "沙箱机制"
|
||||
description: "即使命令被允许执行，也不意味着它可以为所欲为"
|
||||
---
|
||||
|
||||
{/* 本章目标：解释沙箱的作用和原理 */}
|
||||
|
||||
## 权限之外的第二道防线
|
||||
|
||||
权限系统决定"这条命令能不能执行"，沙箱决定"执行时能做到什么程度"。
|
||||
|
||||
即使一条命令通过了权限审批，沙箱仍然可以限制它的行为：
|
||||
即使一条命令通过了权限审批，沙箱仍然可以限制它的行为。两者构成纵深防御的两层：
|
||||
- **权限层**（应用级）：在工具调用前检查，决定是否弹窗审批
|
||||
- **沙箱层**（OS 级）：在进程级别强制约束，即使 AI 生成了恶意命令也无法突破
|
||||
|
||||
| 限制维度 | 说明 |
|
||||
|----------|------|
|
||||
| **文件系统** | 只能访问项目目录及其子目录 |
|
||||
| **网络** | 可以禁止或限制网络访问 |
|
||||
| **进程** | 限制可启动的子进程 |
|
||||
| **时间** | 超时自动终止 |
|
||||
## 执行链路：从用户输入到沙箱包裹
|
||||
|
||||
## 何时启用沙箱
|
||||
一条 Bash 命令的完整执行路径如下：
|
||||
|
||||
沙箱不是默认对所有命令生效——它根据风险评估动态决定：
|
||||
```
|
||||
用户输入 → BashTool.call()
|
||||
→ shouldUseSandbox(input) ─── 是否需要沙箱？
|
||||
→ Shell.exec(command, { shouldUseSandbox })
|
||||
→ SandboxManager.wrapWithSandbox(command)
|
||||
→ spawn(wrapped_command) ─── 实际进程创建
|
||||
```
|
||||
|
||||
- 用户显式请求禁用沙箱的命令（`dangerouslyDisableSandbox`）不走沙箱
|
||||
- 已通过安全规则白名单的命令可以跳过沙箱
|
||||
- 未知命令或高风险命令强制进入沙箱
|
||||
关键判定发生在 `shouldUseSandbox()`（`src/tools/BashTool/shouldUseSandbox.ts`），它执行以下检查：
|
||||
|
||||
## 沙箱的实现思路
|
||||
1. **全局开关**：`SandboxManager.isSandboxingEnabled()` — 检查平台支持 + 依赖完整性 + 用户设置
|
||||
2. **显式跳过**：如果 `dangerouslyDisableSandbox: true` 且策略允许（`allowUnsandboxedCommands`），则不走沙箱
|
||||
3. **排除列表**：用户可在 `settings.json` 中配置 `sandbox.excludedCommands`，匹配的命令跳过沙箱
|
||||
4. **默认行为**：以上条件都不满足时，**进入沙箱**
|
||||
|
||||
不同平台使用不同的沙箱技术：
|
||||
## `shouldUseSandbox()` 判定逻辑详解
|
||||
|
||||
- **macOS**：利用系统级沙箱机制限制文件和网络访问
|
||||
- **Linux**：基于命名空间和 cgroup 的进程隔离
|
||||
- 沙箱策略由系统自动选择，用户不需要手动配置
|
||||
```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 → 展示给用户
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user