Claude Code 插件系统的 Capability 安全架构：从权限声明到沙箱隔离

AI Agent 插件系统的安全设计正成为工程实践的关键瓶颈。当 Claude Code 获得访问代码库、执行命令、调用外部工具的能力时，如何确保这些权限不被滥用或绕过？Anthropic 给出的答案是 Capability-based 安全架构 —— 通过显式权限声明与 OS 级沙箱隔离，实现最小权限原则的工程化落地。

Capability 模型的核心设计

Claude Code 的安全架构遵循 "默认拒绝、显式授权" 的原则。与传统 Unix 权限模型不同，Capability 模型要求每个操作必须持有对应的权限凭证才能执行。这种设计在 Claude Code 中体现为三层防护：

权限层：默认只读模式，任何文件修改或命令执行都需要用户显式批准。系统通过权限提示减少 84% 的重复确认，同时保持安全边界。

声明层：插件和 MCP 服务器通过配置文件声明所需能力，包括允许访问的域名、文件路径和网络端点。这种声明式安全让权限边界在运行前即可审计。

隔离层：OS 级沙箱通过 Linux bubblewrap 或 macOS seatbelt 强制执行限制，确保即使 Agent 被提示注入攻击控制，也无法突破预定义边界。

双重隔离：文件系统与网络的协同防护

有效的沙箱必须同时实现文件系统和网络隔离，缺一不可。没有网络隔离，被入侵的 Agent 可外泄 SSH 密钥等敏感文件；没有文件隔离，恶意代码可轻易逃逸并获取网络访问能力。

文件系统隔离采用差异化的权限模式：

• 读取：默认允许，支持 "拒绝 - 再允许" 模式。可配置 denyRead 阻止敏感目录（如 ~/.ssh），再通过 allowRead 放行特定子路径。
• 写入：默认拒绝，采用 "仅允许" 模式。必须通过 allowWrite 显式声明可写路径，denyWrite 可在允许范围内进一步排除敏感文件。

网络隔离通过代理层实现流量管控：

• HTTP/HTTPS 流量经 HTTP 代理过滤，SOCKS5 代理处理其他 TCP 连接
• Linux 使用 Unix domain socket 将流量路由至宿主机代理，macOS 通过 seatbelt 限制仅能连接特定本地端口
• 域名白名单支持通配符（如 *.github.com），deniedDomains 优先于允许列表

特别值得注意的是强制拒绝路径机制：.bashrc、.zshrc、.gitconfig、.git/hooks/ 等敏感文件和目录即使在被允许的写入路径内也会被自动阻止，形成纵深防御。

可落地的配置实践

Claude Code 的沙箱配置存储于 ~/.srt-settings.json，以下是一份面向 MCP 服务器沙箱化的生产级配置模板：

{
  "network": {
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "api.github.com",
      "npmjs.org",
      "*.npmjs.org"
    ],
    "deniedDomains": [],
    "allowUnixSockets": [],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": ["~/.ssh", "~/.aws", "~/.kube"],
    "allowRead": ["."],
    "allowWrite": ["."],
    "denyWrite": [".env", "secrets/", "config/production.json"]
  },
  "ignoreViolations": {
    "git push": ["/usr/bin/nc"],
    "npm": ["/private/tmp"]
  }
}

关键配置原则：

1. 网络最小化：仅放行必需的 API 端点，避免使用过于宽泛的域名（如允许整个 github.com 可能导致向任意仓库推送代码的数据外泄风险）
2. 读写分离：敏感凭证目录加入 denyRead，构建输出目录加入 allowWrite
3. Unix Socket 管控：谨慎配置 allowUnixSockets，开放 /var/run/docker.sock 实质上等同于赋予宿主机 root 权限
4. 路径通配符：macOS 支持 gitignore 风格的 glob 模式（如 src/**/*.ts），Linux 目前仅支持字面路径

风险边界与已知局限

沙箱并非万能。Claude Code 官方文档明确指出了若干安全限制：

网络层绕过：当前通过环境变量（HTTP_PROXY 等）强制流量走代理，但某些程序可能忽略这些变量导致绕过。域名前置（Domain Fronting）技术也可能突破域名过滤。

权限升级风险：过度宽松的文件写入权限可能引发权限升级攻击。允许写入 $PATH 中的可执行文件目录或系统配置目录，可能在其他用户或系统进程访问这些文件时触发代码执行。

Linux 特有局限：

• 强制拒绝路径仅阻止已存在文件，Linux 的 bind-mount 机制无法阻止在受保护模式内创建新文件
• Unix Socket 限制依赖 seccomp BPF 过滤器，仅 x64 和 arm64 架构提供预编译二进制文件
• Ubuntu 24.04+ 默认启用 kernel.apparmor_restrict_unprivileged_userns，需手动禁用才能使用 bubblewrap

macOS 权衡选项：enableWeakerNetworkIsolation 允许访问 com.apple.trustd.agent 以支持 Go 程序的 TLS 证书验证，但这会打开通过 trustd 服务的数据外泄通道。

结语

Claude Code 的 Capability-based 安全架构为 AI Agent 插件系统提供了可复用的工程范式：权限声明前置、沙箱强制执行、纵深防御兜底。对于构建自有 Agent 平台的团队，Anthropic 已开源 sandbox-runtime 作为参考实现。在生产环境部署时，建议遵循 "最小权限 + 双重隔离 + 持续审计" 的三位一体策略，将安全边界从代码层下沉到 OS 层。

资料来源

• Anthropic Engineering: "Making Claude Code more secure and autonomous with sandboxing" — 官方技术博客，详述沙箱架构设计与内部实践数据
• GitHub: anthropic-experimental/sandbox-runtime — 开源沙箱运行时实现，包含配置 Schema 与平台适配细节
• Claude Code Docs: Security & Sandboxing — 权限模型、MCP 安全、云执行隔离等官方文档

ai-systems