308 lines
14 KiB
Markdown
308 lines
14 KiB
Markdown
---
|
||
tags: [沙箱, sandbox, 权限, Bash, 纵深防御, Claude-Code]
|
||
create time: 2026-06-09 22:30
|
||
---
|
||
|
||
# 沙箱机制 - 权限系统之外的第二道防线
|
||
|
||
## 概述
|
||
|
||
Claude Code 的沙箱不是用来替代权限系统，而是为 shell 命令再套一层 OS 级能力边界。权限系统决定"这次工具调用要不要执行"，沙箱决定"就算执行了，这个子进程最多能碰到哪些文件、哪些网络目标"。两者组合构成真正的 Defense-in-Depth。
|
||
|
||
## 正文
|
||
|
||
### 实现分层：仓库里的适配器 + 底层运行时
|
||
|
||
沙箱实现分成两层：
|
||
|
||
- **仓库自身负责**：策略、配置转换、启停判断、命令包裹、清理和权限联动
|
||
- **底层隔离**：由外部运行时 `@anthropic-ai/sandbox-runtime` 执行
|
||
|
||
在 `src/utils/sandbox/sandbox-adapter.ts` 里可以清楚看到这条边界：项目导入 `SandboxManager as BaseSandboxManager`、`SandboxViolationStore` 等运行时对象，然后在外面再包一层符合 Claude Code 自身权限模型的适配器。
|
||
|
||
底层隔离在不同平台上的落地：
|
||
|
||
| 平台 | 实现方式 |
|
||
|------|---------|
|
||
| macOS | `sandbox-exec`（Seatbelt profile） |
|
||
| Linux / WSL2 | `bubblewrap + seccomp` |
|
||
| Windows 原生 | 不支持 shell 沙箱 |
|
||
|
||
### 它到底解决什么问题
|
||
|
||
如果只有应用层权限系统，Claude Code 需要在命令执行前尽量判断：
|
||
|
||
- 这条命令是不是只读
|
||
- 会不会写危险路径
|
||
- 会不会连到外网
|
||
- 会不会通过复合命令、重定向、子进程、解释器脚本绕过检查
|
||
|
||
这些检查都很有价值，但本质上仍然是"执行前推断"。而 shell 命令的真实副作用经常取决于运行时行为：
|
||
|
||
- `bash script.sh`
|
||
- `python -c "..."`
|
||
- `make`
|
||
- `npm install`
|
||
- 某个命令再启动另一个子进程
|
||
|
||
> [!info] 沙箱的核心价值
|
||
> 沙箱把这些运行时行为的能力范围压缩到一个明确边界内。即使应用层检查漏了，命令也不能随意写系统目录或访问不允许的网络目标。
|
||
|
||
### 四个核心价值
|
||
|
||
#### 1. 给 shell 一个 OS 级兜底
|
||
|
||
`src/utils/bash/ast.ts` 开头就写得很明确：Bash AST 分析不是沙箱，它只是在判断我们能不能可靠地理解命令结构，不能阻止危险命令真的运行。
|
||
|
||
像 `bash script.sh`、`python -c "..."`、`make`、`npm install` 这类命令，真实副作用都要到运行时才完全展开。沙箱即使前面的分析漏了，进程到了 OS 层以后仍然只能写允许目录、访问允许域名。
|
||
|
||
#### 2. 让"安全边界内"的命令可以少弹窗甚至自动放行
|
||
|
||
默认沙箱白名单里包含当前工作目录和 Claude 临时目录，工作区内的大多数开发命令都能顺畅运行：`npm test`、`rg`、`git status`、工作区内的构建和测试。
|
||
|
||
项目专门提供了 `autoAllowBashIfSandboxed`。核心思路不是"更大胆地信任模型"，而是"既然命令已经被 OS 级边界收紧，就没必要再让用户为大量低风险 Bash 命令反复点确认"。
|
||
|
||
#### 3. 把"出错"的后果从系统级破坏降成一次受限失败
|
||
|
||
模型偶尔会出错，应用层规则也可能有漏判。例如 `sudo tee /etc/hosts`、`mv ... ~/.ssh/...`、`curl 外网 | bash`——如果没有运行时约束，可能直接修改系统配置或把未知脚本落到机器上。放进沙箱后，更常见的结果是：因为写权限或网络权限不满足而失败。
|
||
|
||
#### 4. 拦截运行时绕过和逃逸路径
|
||
|
||
`src/utils/sandbox/sandbox-adapter.ts` 专门把一些高风险路径额外加入 `denyWrite`，例如 `settings.json`、`.claude/skills`、一些 bare git repo 相关路径。这样做的目的是：即使命令已经执行，也别让它顺手把护栏本身拆掉。
|
||
|
||
### 设计边界：它保护什么，不保护什么
|
||
|
||
#### 保护对象
|
||
|
||
- Bash / shell 命令执行
|
||
- 在支持平台上的 PowerShell 执行
|
||
- shell 子进程的文件系统写入范围
|
||
- shell 子进程的网络访问范围
|
||
- 一些已知的高风险路径和沙箱逃逸向量
|
||
|
||
#### 不直接保护的对象
|
||
|
||
- `FileEditTool` / `FileWriteTool` 这类直接文件工具
|
||
- 纯应用层的权限弹窗和规则匹配
|
||
- Bash AST 解析本身
|
||
|
||
> [!warning] 重要区分
|
||
> Bash AST 分析不是沙箱。源码自己写得很明确，它只回答"我们能不能可信地提取 argv 结构"，并不负责阻止危险命令真正运行。
|
||
|
||
### 哪些场景会走沙箱
|
||
|
||
#### 启动阶段先判断"沙箱能不能用"
|
||
|
||
REPL / CLI 启动时就会先检查当前环境是否具备沙箱条件：
|
||
|
||
1. 当前平台是否受底层 runtime 支持
|
||
2. 依赖是否齐全
|
||
3. `sandbox.enabled` 是否打开
|
||
4. 当前平台是否落在 `enabledPlatforms` 范围内
|
||
|
||
如果用户显式开启了沙箱但当前环境不满足条件，启动期会先给出 warning；如果同时配置了 `sandbox.failIfUnavailable`，则会直接拒绝启动。
|
||
|
||
启动时真的会调用初始化流程，把当前设置转换成 runtime 配置并交给底层 `BaseSandboxManager.initialize(...)`。后续如果设置变化，还会通过 `updateConfig(...)` 热更新。
|
||
|
||
#### BashTool 默认会走
|
||
|
||
只要满足以下条件，Bash 命令默认会进入沙箱：
|
||
|
||
1. 当前平台支持沙箱
|
||
2. 沙箱依赖齐全
|
||
3. `sandbox.enabled` 打开
|
||
4. 当前平台在 `enabledPlatforms` 范围内
|
||
5. 这条命令没有被显式排除
|
||
6. 这次调用没有被允许以 `dangerouslyDisableSandbox` 绕过
|
||
|
||
#### PowerShell 只在支持平台上走
|
||
|
||
| 平台 | 行为 |
|
||
|------|------|
|
||
| Linux / macOS / WSL2 | 可以走沙箱 |
|
||
| Windows 原生 | 不支持沙箱，直接返回 `shouldUseSandbox: false` |
|
||
|
||
#### Hook 命令会复用"网络专用沙箱"
|
||
|
||
Hook 不是完整复用 Bash 那套文件系统限制，而是额外套了一层 network-only sandbox——重点拦网络访问，文件系统不额外收紧。
|
||
|
||
### 哪些场景不会走沙箱
|
||
|
||
#### FileEditTool / FileWriteTool
|
||
|
||
这类工具不是靠 shell 修改文件，而是直接在应用层做文件 I/O，所以它们不通过 `Shell.exec()`，自然也不会被 `wrapWithSandbox()` 包裹。
|
||
|
||
> [!tip] 理解两种拦截路径
|
||
> - "shell 改 `/etc/hosts`"通常是沙箱在 OS 层拦
|
||
> - "FileEdit 改 `/etc/hosts`"通常是权限系统在应用层拦
|
||
|
||
#### 明确排除的命令
|
||
|
||
如果命中 `sandbox.excludedCommands`，这条命令会直接跳过沙箱。支持精确匹配、前缀匹配和通配符匹配三种模式。
|
||
|
||
#### 允许 unsandboxed fallback 的命令
|
||
|
||
如果这次调用显式设置了 `dangerouslyDisableSandbox: true` 并且策略允许 `allowUnsandboxedCommands`，那它也可以不进沙箱。命名故意写得很重：`dangerouslyDisableSandbox`，提醒这是例外路径。
|
||
|
||
### 完整执行链路
|
||
|
||
#### 启动期链路
|
||
|
||
```text
|
||
REPL / CLI 启动
|
||
-> isSandboxingEnabled()
|
||
-> convertToSandboxRuntimeConfig(settings)
|
||
-> BaseSandboxManager.initialize(runtimeConfig, callback)
|
||
-> 设置变化时 BaseSandboxManager.updateConfig(newConfig)
|
||
```
|
||
|
||
#### 命令期链路
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
U["用户请求"] --> CP["BashTool.checkPermissions()"]
|
||
CP --> SUS["shouldUseSandbox(input)"]
|
||
SUS --> SE["Shell.exec(command)"]
|
||
SE --> WS["SandboxManager.wrapWithSandbox(...)"]
|
||
WS --> SP["spawn(wrapped command)"]
|
||
SP --> CL["cleanupAfterCommand()"]
|
||
```
|
||
|
||
这里真正把命令"包进沙箱"的关键点是 `Shell.exec()`。它会在真正 `spawn(...)` 之前调用 `SandboxManager.wrapWithSandbox(...)`，把原始命令改写成底层 runtime 可执行的沙箱命令串。
|
||
|
||
#### 两个容易混淆的判定点
|
||
|
||
- **判定点 A：要不要进沙箱** — `shouldUseSandbox()` 的职责，回答"这条命令要不要被 OS 级沙箱包起来执行？"
|
||
- **判定点 B：这条命令要不要弹权限确认** — 权限系统和 Bash 权限检查的职责，回答"这条命令在应用层看来是 allow、ask 还是 deny？"
|
||
|
||
这两个判定点是并列协作的，不是互相替代的。
|
||
|
||
### 默认沙箱到底限制了什么
|
||
|
||
沙箱运行时配置最终由 `convertToSandboxRuntimeConfig()` 生成。它把项目自己的设置、权限规则和安全加固逻辑转换成底层运行时需要的配置。
|
||
|
||
#### 限制怎么从权限系统推导出来
|
||
|
||
- `WebFetch(domain:...)` 和 `sandbox.network.allowedDomains` 被合并成网络白名单
|
||
- `Edit(...)` / `Read(...)` 这类权限规则被翻译成文件系统读写限制
|
||
- `sandbox.filesystem.allowWrite` / `allowRead` / `denyWrite` / `denyRead` 会继续叠加到最终 runtime 配置上
|
||
|
||
#### 文件系统默认写入范围
|
||
|
||
默认 `allowWrite` 只有两类：
|
||
|
||
- 当前工作目录 `.`
|
||
- Claude 的临时目录
|
||
|
||
这意味着工作区内的构建、测试、生成临时文件通常能正常运行，而根路径如 `/etc/...`、`/usr/...`、`/var/...` 默认不在写白名单里。
|
||
|
||
#### 强制 deny 的路径
|
||
|
||
即使有别的配置，项目还会额外加固一些高风险路径：
|
||
|
||
- settings 文件
|
||
- `.claude/skills`
|
||
- 一些 bare git repo 相关路径
|
||
|
||
这样做的原因是：这些路径一旦可写，攻击者可能反过来修改 Claude Code 自己的配置、技能或 git 行为，从而扩大权限。
|
||
|
||
#### 网络限制
|
||
|
||
网络白名单来自两部分：
|
||
|
||
- `sandbox.network.allowedDomains`
|
||
- `WebFetch(domain:...)` 这类权限规则
|
||
|
||
被允许的域名会进入沙箱网络配置；不在白名单里的访问在运行时会被拦截或触发额外的网络授权流程。
|
||
|
||
### autoAllowBashIfSandboxed 的真实意义
|
||
|
||
这是沙箱设计里最值得注意的开关之一。它表达的信任假设是：
|
||
|
||
> 如果命令已经被 OS 级沙箱约束在安全边界内，那么应用层就没有必要再对大量低风险 Bash 命令逐条弹确认框。
|
||
|
||
当这个开关开启时：
|
||
|
||
1. 命令先检查显式 `deny` / `ask` 规则
|
||
2. 如果没有命中这些硬规则
|
||
3. 且命令确实会在沙箱里执行
|
||
4. 那么 BashTool 可以直接自动允许它运行
|
||
|
||
> [!warning] 边界条件
|
||
> 它只对"真正会进沙箱的命令"生效。命中了 `excludedCommands`、显式使用了 `dangerouslyDisableSandbox: true`、当前平台不支持沙箱——这些命令依然要遵守正常的 `ask` 规则。
|
||
|
||
这也是沙箱存在的一个核心产品价值：不是让更多危险操作通过，而是让更多**受限范围内的常规命令**可以无感运行。
|
||
|
||
### 平台差异
|
||
|
||
| 平台 | 实现 | 特点 |
|
||
|------|------|------|
|
||
| macOS | `sandbox-exec` | 路径和网络规则通过 Seatbelt profile 落地，原生 OS 级进程隔离 |
|
||
| Linux | `bubblewrap + seccomp` | 建立 mount / PID / network 等隔离，glob 路径支持比 macOS 弱 |
|
||
| WSL | 仅 WSL2 | WSL1 视为不支持平台 |
|
||
| Windows 原生 | 不支持 | 只能依赖权限系统和工具级检查 |
|
||
|
||
### 工作区内外：应用层与沙箱层如何配合
|
||
|
||
#### 工作区内路径
|
||
|
||
工作区内路径通常有两层保护：应用层权限检查 + 沙箱默认允许写当前工作目录。这使得"工作区内构建/测试/格式化/生成文件"成为最顺滑的一条路径。
|
||
|
||
#### 工作区外路径
|
||
|
||
工作区外路径则更严格：应用层通常会视为高风险要求确认或阻止，即使应用层允许，如果不在沙箱白名单里运行时也会失败。
|
||
|
||
### 用户真的会看到什么
|
||
|
||
被拦截至少有三类体验：
|
||
|
||
| 类型 | 时机 | 用户看到 |
|
||
|------|------|---------|
|
||
| 执行前的权限确认 | 命令还没运行 | 标准权限对话框（Bash/FileEdit/FileWrite） |
|
||
| 执行中的沙箱违规 | 命令已进入沙箱 | 命令失败 + stderr 附加 `<sandbox_violations>` 标签 |
|
||
| 网络越界请求 | 运行时 | 专门的网络授权对话框（"Network request outside of sandbox"） |
|
||
|
||
### 常见误区
|
||
|
||
> [!warning] 误区 1：沙箱会保护所有文件修改
|
||
> 不是。它主要保护 **shell 子进程**。直接文件编辑工具走的是应用层权限系统，不是 shell 沙箱。
|
||
|
||
> [!warning] 误区 2：只要启用了沙箱，就不会再需要权限系统
|
||
> 不是。沙箱只限制进程能力，不负责解释用户意图、路径安全语义、工具模式、审批体验。
|
||
|
||
> [!warning] 误区 3：危险操作被沙箱拦住说明应用层检查没价值
|
||
> 不是。应用层检查的价值在于更早提示、更好的用户体验、更细的语义判断、对不走 shell 的工具同样生效。沙箱负责的是最终兜底。
|
||
|
||
### 推荐的阅读路径
|
||
|
||
如果你想继续顺着源码深入，推荐按下面顺序看：
|
||
|
||
1. `packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts`
|
||
2. `src/utils/Shell.ts`
|
||
3. `src/utils/sandbox/sandbox-adapter.ts`
|
||
4. `src/utils/permissions/permissions.ts`
|
||
5. `packages/builtin-tools/src/tools/BashTool/bashPermissions.ts`
|
||
6. `src/utils/permissions/pathValidation.ts`
|
||
7. `src/utils/permissions/filesystem.ts`
|
||
|
||
### FAQ
|
||
|
||
> [!question] Linux 下 `echo hi > /etc/hosts` 会怎样？
|
||
> 如果是 BashTool：通常会进沙箱，默认沙箱不允许写 `/etc`，所以命令会在运行时失败。如果是 FileEditTool：不进沙箱，通常会在应用层文件权限检查里先被拦下。
|
||
|
||
> [!question] Windows 下改 `C:\Windows\System32\drivers\etc\hosts` 会怎样？
|
||
> 在 Windows 原生环境里，通常没有这套 shell 沙箱兜底，所以主要依赖应用层权限系统和工具自己的检查逻辑。
|
||
|
||
> [!question] 既然沙箱这么强，为什么还保留 `dangerouslyDisableSandbox`？
|
||
> 因为有些真实开发任务确实需要越过默认边界，例如访问未加入白名单的工具链目录、调试系统级环境、做管理员明确允许的例外操作。但项目把这个入口做得非常显眼，也允许管理员通过策略直接禁掉。
|
||
|
||
> [!question] 什么时候最能感受到沙箱的价值？
|
||
> 当你开启 `autoAllowBashIfSandboxed` 时最明显。这时大量工作区内命令可以少弹窗甚至不弹窗，但即使模型偶尔给出过界命令，系统级写入和网络能力仍然被边界限制住。
|
||
|
||
## 关联笔记
|
||
|
||
- [[why-safety-matters|AI 安全至关重要]]
|
||
- [[permission-model|权限模型]]
|
||
- [[plan-mode|计划模式]]
|
||
- [[auto-mode|Auto Mode]]
|