Hotdry.
归档
ai-security

Claude Code沙箱执行隔离架构：双隔离模型与工程实现

深入解析Claude Code沙箱执行隔离的双隔离模型，涵盖文件系统与网络隔离的工程实现、配置参数与安全最佳实践。

在 AI 代理日益普及的今天，Claude Code 作为开发者的智能编程助手，能够直接读写代码文件、执行系统命令，这带来了巨大的生产力提升，同时也引入了显著的安全风险。Anthropic 为解决这一矛盾，推出了基于沙箱执行隔离的安全架构，将权限提示减少了 84%，同时大幅提升了系统的安全性。本文将深入解析这一架构的工程实现，提供可落地的配置参数与监控要点。

双隔离模型：安全沙箱的基石

Claude Code 沙箱架构的核心是双隔离模型—— 文件系统隔离与网络隔离必须同时存在，缺一不可。这一设计理念源于对攻击场景的深刻理解：没有网络隔离，被入侵的代理可以外泄敏感文件（如 SSH 密钥）；没有文件系统隔离，代理可能轻易逃逸沙箱并获取网络访问权限。

Anthropic 在官方博客中明确指出："有效的沙箱化需要文件系统和网络隔离两者兼备。" 这一观点得到了实际攻击场景的验证。例如，一个被提示注入攻击的 Claude Code 实例，如果只实施了文件系统隔离，仍可能通过 DNS 隧道或 HTTP 请求将敏感数据外泄；反之，如果只有网络隔离，攻击者可能通过修改系统配置文件或环境变量来间接获取网络访问。

文件系统隔离：允许写 / 拒绝读的精细控制

文件系统隔离采用了两种不同的控制模式，这种设计体现了 "最小权限原则" 的精髓：

读权限控制（拒绝模式）：默认允许读取所有文件，但可以配置拒绝特定路径。这种设计符合开发场景的实际需求 ——Claude Code 需要读取系统库、依赖包等文件来理解代码上下文。典型的拒绝配置包括：

"denyRead": ["~/.ssh", "~/.aws", "~/.npmrc"]

写权限控制（允许模式）：默认拒绝所有写入操作，必须显式允许特定路径。这是安全性的关键保障，防止 Claude Code 意外或恶意修改系统文件。配置示例如下：

"allowWrite": [".", "src/", "test/", "/tmp"],
"denyWrite": [".env", "config/production.json"]

这种不对称的设计哲学很值得借鉴：开发环境通常需要广泛的读取权限来理解代码上下文，但写入权限必须严格限制。Anthropic 的 sandbox-runtime 开源项目还内置了强制拒绝路径机制，即使路径在允许列表中，某些敏感文件也始终被阻止写入，包括：

  • Shell 配置文件：.bashrc、.zshrc等
  • Git 配置文件：.gitconfig、.gitmodules
  • IDE 配置目录：.vscode/、.idea/

网络隔离：代理过滤与域名控制

网络隔离采用了 "仅允许" 模式 —— 默认拒绝所有网络访问，必须显式配置允许的域名。这种白名单策略虽然严格，但对于 AI 代理场景是必要的，因为代理的网络行为往往难以预测。

代理架构设计：Claude Code 的网络隔离通过双层代理实现：

  1. HTTP/HTTPS 代理：处理 Web 请求，验证域名是否在允许列表中
  2. SOCKS5 代理：处理其他 TCP 连接（SSH、数据库等）

平台实现差异显著：

  • macOS：使用 Seatbelt 配置文件，只允许连接到特定的 localhost 端口，代理服务监听这些端口
  • Linux：通过 bubblewrap 完全移除网络命名空间，所有网络流量必须通过 Unix 域套接字路由到主机上的代理

配置示例：

"network": {
  "allowedDomains": [
    "github.com",
    "*.github.com",
    "api.github.com",
    "npmjs.org",
    "*.npmjs.org"
  ],
  "deniedDomains": ["malicious.com"],
  "allowUnixSockets": [],
  "allowLocalBinding": false
}

值得注意的是，域名支持通配符模式（如*.github.com），这为开发工作流提供了必要的灵活性，同时保持了安全边界。

操作系统级原语：平台特定的实现策略

Claude Code 沙箱没有重新发明轮子，而是充分利用了操作系统提供的安全原语：

macOS 实现：基于sandbox-exec和 Seatbelt 框架。Seatbelt 是 macOS 的内置沙箱机制，通过配置文件定义进程的权限边界。Anthropic 的动态生成 Seatbelt 配置文件，根据用户配置实时创建沙箱规则。这种方法的优势是与系统深度集成，性能开销小，且能利用 macOS 的沙箱违规日志系统进行实时监控。

Linux 实现：基于bubblewrap（bwrap）容器化工具。bubblewrap 通过命名空间隔离（特别是网络命名空间）和绑定挂载来实现文件系统隔离。Linux 版本还引入了seccomp BPF 过滤器来阻止 Unix 域套接字的创建，这是防御本地 IPC 攻击的重要层。

平台差异带来的配置差异需要注意：macOS 支持类 gitignore 的 glob 模式路径匹配，而 Linux 目前只支持字面路径。这意味着相同的配置文件在不同平台上可能有不同的安全效果。

可落地的配置参数与监控要点

基础配置模板

对于大多数开发场景，推荐以下配置起点：

{
  "network": {
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "api.github.com",
      "npmjs.org",
      "registry.npmjs.org"
    ],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["~/.ssh", "~/.aws", "~/.docker"],
    "allowWrite": [".", "src/", "test/", "/tmp"],
    "denyWrite": [".env", "*.secret.*", "config/production.*"]
  },
  "mandatoryDenySearchDepth": 3
}

监控与调试命令

macOS 沙箱违规监控：

# 实时查看沙箱违规日志
log stream --predicate 'process == "sandbox-exec"' --style syslog

# 查看历史违规记录
log show --predicate 'process == "sandbox-exec"' --last 1h

Linux 调试命令：

# 跟踪被拒绝的系统调用
strace -f srt "your-command" 2>&1 | grep EPERM

# 特定文件操作跟踪
strace -f -e trace=open,openat,stat,access srt "npm install" 2>&1 | grep EPERM

安全最佳实践清单

  1. 渐进式权限开放：从不允许网络开始，按需添加域名；从不允许写入开始，按需开放目录
  2. 定期审计配置：每月审查一次 allowedDomains 和 allowWrite 列表，移除不再需要的条目
  3. 敏感文件保护：始终将 SSH 密钥、API 密钥、配置文件等加入 denyRead 列表
  4. 深度搜索配置：对于包含敏感文件的复杂目录结构，适当增加 mandatoryDenySearchDepth
  5. 平台特性利用：在 macOS 上利用 glob 模式进行精细控制，在 Linux 上注意路径字面匹配

已知风险与限制

尽管 Claude Code 沙箱架构设计精良，但仍存在一些已知限制：

  1. 域名伪装风险：网络过滤可能被域名伪装（domain fronting）技术绕过，特别是当允许的域名托管在 CDN 服务上时
  2. Unix 套接字权限提升：允许访问 Unix 套接字（如/var/run/docker.sock）可能提供逃逸沙箱的途径
  3. Linux 代理绕过：某些应用程序可能不尊重 HTTP_PROXY 环境变量，导致网络过滤失效
  4. 嵌套沙箱削弱：在 Docker 环境中使用的enableWeakerNestedSandbox模式会显著降低安全性

开源生态与扩展应用

Anthropic 将 sandbox-runtime 开源，不仅是为了 Claude Code，更是为了推动整个 AI 代理生态的安全发展。该项目可作为独立的 CLI 工具（srt命令）或 Node.js 库使用，适用于：

  • 沙箱化本地 MCP 服务器
  • 限制第三方构建工具的网络访问
  • 为 CI/CD 流水线提供安全执行环境

配置 MCP 服务器的示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

结语

Claude Code 的沙箱执行隔离架构代表了 AI 代理安全领域的重要进步。通过双隔离模型、操作系统级原语利用和精细的权限控制，它在安全性与开发效率之间找到了平衡点。对于正在构建或使用 AI 代理系统的团队，理解并实施类似的沙箱机制不应是可选项，而是基本要求。

随着 AI 代理能力的不断增强，安全边界的设计将变得越来越关键。Claude Code 的实践表明，通过合理的架构设计和持续的安全投入，我们可以在享受 AI 带来的生产力提升的同时，有效控制相关的安全风险。

资料来源：

  1. Anthropic 官方博客：Making Claude Code more secure and autonomous with sandboxing
  2. GitHub 仓库：anthropic-experimental/sandbox-runtime（开源沙箱运行时）
查看归档