cs-note/claude-code-best/docs/safety/sandbox.md

tags, create time

tags	create time
沙箱 sandbox 权限 Bash 纵深防御 Claude-Code	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，提醒这是例外路径。

完整执行链路

启动期链路

REPL / CLI 启动
  -> isSandboxingEnabled()
  -> convertToSandboxRuntimeConfig(settings)
  -> BaseSandboxManager.initialize(runtimeConfig, callback)
  -> 设置变化时 BaseSandboxManager.updateConfig(newConfig)

命令期链路

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
• permission-model
• plan-mode
• auto-mode