古法编程

Appearance

本页介绍如何为 Claude Code 和 Agent SDK 的安全部署配置隔离、凭证管理和网络控制。你可以在内置权限系统（按工具/命令设置允许/阻止/审批）、沙箱运行时（轻量级文件系统和网络限制）、容器（Docker 隔离 + 只读挂载 + Unix socket 代理）、gVisor（系统调用级隔离）或虚拟机（Firecracker 微 VM）之间选择。凭证管理推荐代理注入模式：代理运行在隔离边界之外，自动为请求添加 API 密钥，代理本身永不见明文凭证。关键验证命令：设置 ANTHROPIC_BASE_URL 指向本地代理后测试 Claude API 调用是否经过代理。此方案适用于单开发者、CI/CD 以及多租户环境，但沙箱运行时和容器各有安全限制（如无 TLS 检查、共享内核）。

Claude Code 和 Agent SDK 安全部署指南 ​

Claude Code 和 Agent SDK 是强大的工具，可以代表你执行代码、访问文件以及与外部服务交互。与传统软件遵循固定代码路径不同，这些工具根据上下文和目标动态生成动作。这种灵活性带来了便利，但也意味着它们的行为会受到所处理内容（文件、网页或用户输入）的影响——即所谓的 Prompt 注入。例如，如果仓库的 README 包含异常指令，Claude Code 可能会以操作员未预料的方式将其纳入行动。本指南涵盖降低此风险的实际方法。

好消息是，保护 Agent 部署不需要特殊基础设施。适用于任何半可信代码的原则同样适用：隔离、最小权限和纵深防御。Claude Code 包含多项安全功能，本指南将逐一介绍，并为需要更高安全性的部署提供额外的加固选项。

并非所有部署都需要最大安全：开发者在笔记本上运行 Claude Code 与公司在多租户环境中处理客户数据的要求不同。本指南提供的选项范围从 Claude Code 内置安全功能到加固的生产架构，你可根据自身情况选择。

威胁模型 ​

由于 Prompt 注入（Agent 所处理内容中嵌入的指令）或模型错误，Agent 可能采取非预期的动作。Claude 模型设计为抵抗此类情况；详情请参阅 模型概览 和你所部署模型的系统卡。

但纵深防御仍是良好实践。例如，如果 Agent 处理了一个恶意文件，指示它将客户数据发送到外部服务器，网络控制可以完全阻止该请求。

内置安全功能 ​

Claude Code 包含多项解决常见安全顾虑的功能。完整细节请参阅 安全文档。

  • 权限系统：每个工具和 bash 命令都可配置为允许、阻止或提示用户批准。使用 glob 模式创建规则，如 "允许所有 npm 命令" 或 "阻止任何包含 sudo 的命令"。组织可以设置适用于所有用户的策略。详见 权限。
  • 命令解析用于权限：在执行 bash 命令前，Claude Code 将其解析为 AST，并与权限规则匹配。无法干净解析的命令或未匹配到允许规则的命令需要显式批准。一小部分结构（如 eval）无论允许规则如何都始终需要批准。这是权限门，而非沙箱；它不会根据目标路径或效果推断命令是否危险。
  • 网页搜索摘要：搜索结果以摘要形式呈现，而非将原始内容直接传入上下文，降低了恶意网页内容注入 Prompt 的风险。
  • 沙箱模式：bash 命令可在限制文件系统和网络访问的沙箱环境中运行。详见 沙箱文档。

安全原则 ​

对于需要超出 Claude Code 默认设置的额外加固的部署，以下原则指导可用选项。

安全边界 ​

安全边界将不同信任级别的组件隔离开。对于高安全性部署，可将敏感资源（如凭证）放置在包含 Agent 的边界之外。如果 Agent 环境出现问题，边界外的资源仍受保护。

例如，不给 Agent 直接访问 API 密钥，而是在 Agent 环境外运行一个代理，将密钥注入请求。Agent 可以发起 API 调用，但永远看不到凭证本身。此模式对多租户部署或处理不可信内容时非常有用。

最小权限 ​

必要时，可将 Agent 限制为仅拥有其特定任务所需的能力：

资源限制选项
文件系统仅挂载需要的目录，推荐只读
网络通过代理限制到特定端点
凭证通过代理注入，而非直接暴露
系统能力在容器中删除 Linux capabilities

纵深防御 ​

对于高安全环境，叠加多层控制提供额外保护。选项包括：

  • 容器隔离
  • 网络限制
  • 文件系统控制
  • 代理上的请求验证

正确的组合取决于你的威胁模型和运维要求。

隔离技术 ​

不同隔离技术在安全强度、性能和运维复杂度之间存在权衡。

在所有配置中，Claude Code（或你的 Agent SDK 应用程序）运行在隔离边界（沙箱、容器或虚拟机）内。下文描述的安全控制限制了 Agent 从该边界内能访问的内容。

技术隔离强度性能开销复杂度
沙箱运行时良好（安全默认值）极低低
容器（Docker）取决于设置低中等
gVisor优秀（正确设置后）中/高中等
虚拟机（Firecracker, QEMU）优秀（正确设置后）高中/高

沙箱运行时 ​

如需轻量级隔离而不使用容器，sandbox-runtime 在操作系统层面强制执行文件系统和网络限制。主要优势是简单：无需 Docker 配置、容器镜像或网络设置。代理和文件系统限制已内置。只需提供一个设置文件，指定允许的域名和路径。

工作原理：

  • 文件系统：使用操作系统原语（Linux 上为 bubblewrap，macOS 上为 sandbox-exec）限制对已配置路径的读写访问
  • 网络：移除网络命名空间（Linux）或使用 Seatbelt 配置文件（macOS）将网络流量路由到内置代理
  • 配置：基于 JSON 的域名和文件系统路径允许列表

设置：

bash
npm install @anthropic-ai/sandbox-runtime

然后创建一个配置文件，指定允许的路径和域名。

安全注意事项：

  1. 共享主机内核：与虚拟机不同，沙箱进程与主机共享内核。内核漏洞理论上可能导致逃逸。对于某些威胁模型这可以接受，但如果需要内核级隔离，请使用 gVisor 或独立虚拟机。

  2. 无 TLS 检查：代理基于客户端提供的主机名允许域名，不终止或检查加密流量。沙箱内运行的代码可能使用域前置或类似技术访问允许列表之外的主机。如果你的威胁模型需要更强保证，请配置 TLS 终止代理。更多细节请参阅 沙箱安全限制。另外，如果 Agent 对允许的域名拥有宽松凭证，请确保它不能利用该域名触发其他网络请求或泄露数据。

对于许多单开发和 CI/CD 场景，sandbox-runtime 以极少的设置显著提升了安全性。下文介绍需要更强隔离的容器和虚拟机。

容器 ​

容器通过 Linux 命名空间提供隔离。每个容器拥有独立的文件系统视图、进程树和网络栈，同时共享主机内核。

安全加固的容器配置可能如下：

bash
docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt seccomp=/path/to/seccomp-profile.json \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /home/agent:rw,noexec,nosuid,size=500m \
  --network none \
  --memory 2g \
  --cpus 2 \
  --pids-limit 100 \
  --user 1000:1000 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

各选项的作用：

选项用途
--cap-drop ALL移除 Linux capabilities，如 NET_ADMIN 和 SYS_ADMIN，防止权限提升
--security-opt no-new-privileges阻止进程通过 setuid 二进制文件获得权限
--security-opt seccomp=...限制可用的系统调用；Docker 默认阻止约 44 个，自定义配置文件可阻止更多
--read-only使容器的根文件系统不可写，防止 Agent 持久化更改
--tmpfs /tmp:...提供可写的临时目录，容器停止时清除
--network none移除所有网络接口；Agent 通过下面挂载的 Unix socket 通信
--memory 2g限制内存使用，防止资源耗尽
--pids-limit 100限制进程数量，防止 fork 炸弹
--user 1000:1000以非 root 用户运行
-v ...:/workspace:ro只读挂载代码目录，Agent 可分析但不能修改。避免挂载敏感主机目录如 ~/.ssh、~/.aws 或 ~/.config
-v .../proxy.sock:...挂载连接到主机上运行代理的 Unix socket（见下文）

Unix socket 架构：

使用 --network none 时，容器完全没有网络接口。Agent 访问外界的唯一方式是通过挂载的 Unix socket，连接到主机上运行的代理。此代理可实施域名允许列表、注入凭证并记录所有流量。

这与 sandbox-runtime 使用的架构相同。即使 Agent 因 Prompt 注入被攻破，也无法向任意服务器泄露数据——它只能通过代理通信，而代理控制着可访问的域名。更多细节请参阅 Claude Code 沙箱博客。

额外加固选项：

选项用途
--userns-remap将容器 root 映射到非特权主机用户；需要 daemon 配置，但限制了容器逃逸的损害
--ipc private隔离进程间通信，防止跨容器攻击

gVisor ​

标准容器共享主机内核：容器内代码进行系统调用时，直接到达运行主机的同一个内核。这意味着内核漏洞可能导致容器逃逸。gVisor 通过在用户空间中拦截系统调用（在到达主机内核之前），实现自己的兼容层，处理大多数系统调用而不涉及真实内核。

如果 Agent 运行了恶意代码（可能由于 Prompt 注入），该代码运行在容器内并可能尝试内核攻击。使用 gVisor 后，攻击面大大缩小：恶意代码需要首先利用 gVisor 的用户空间实现，并且对真实内核的访问有限。

使用 gVisor 与 Docker，安装 runsc 运行时并配置 daemon：

json
// /etc/docker/daemon.json
{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

然后运行容器：

bash
docker run --runtime=runsc agent-image

性能考虑：

工作负载开销
CPU 密集型计算~0%（无系统调用拦截）
简单系统调用~2 倍慢
文件 I/O 密集型重开/关闭模式下可达 10-200 倍慢

对于多租户环境或处理不可信内容时，额外的隔离通常值得开销。

虚拟机 ​

虚拟机通过 CPU 虚拟化扩展提供硬件级隔离。每个 VM 运行自己的内核，形成强边界。客户内核中的漏洞不会直接危害主机。但虚拟机并非自动比 gVisor 等替代方案"更安全"。VM 安全性很大程度上依赖于 hypervisor 和设备模拟代码。

Firecracker 专为轻量级微 VM 隔离设计。它可在 125ms 内启动 VM，内存开销小于 5 MiB，剥离了不必要的设备模拟以减少攻击面。

在此方法中，Agent 虚拟机没有外部网络接口，而是通过 vsock（虚拟 socket）通信。所有流量经过 vsock 到达主机上的代理，该代理实施允许列表并在转发请求前注入凭证。

云部署 ​

对于云部署，可以将任意上述隔离技术与云原生网络控制结合：

  1. 在没有互联网网关的私有子网中运行 Agent 容器
  2. 配置云防火墙规则（AWS Security Groups、GCP VPC firewall）以阻止除代理外的所有出站流量
  3. 运行一个代理（如 Envoy 及其 credential_injector 过滤器），验证请求、实施域名允许列表、注入凭证并转发到外部 API
  4. 为 Agent 的服务账号分配最小 IAM 权限，尽可能通过代理路由敏感访问
  5. 在代理上记录所有流量用于审计

凭证管理 ​

Agent 通常需要凭证来调用 API、访问仓库或与云服务交互。挑战在于提供此访问而不暴露凭证本身。

代理模式 ​

推荐的方法是在 Agent 安全边界外运行一个代理，将凭证注入出站请求。Agent 发送不带凭证的请求，代理添加凭证，然后转发到目标。

此模式有几个好处：

  1. Agent 永远不会看到实际的凭证
  2. 代理可以实施允许的端点列表
  3. 代理可以记录所有请求用于审计
  4. 凭证存储在一个安全位置，而非分发到每个 Agent

配置 Claude Code 使用代理 ​

Claude Code 支持两种将采样请求路由到代理的方法：

选项 1：ANTHROPIC_BASE_URL（简单，但仅适用于采样 API 请求）

bash
export ANTHROPIC_BASE_URL="http://localhost:8080"

这告诉 Claude Code 和 Agent SDK 将采样请求发送到你的代理，而非直接发送到 Claude API。你的代理接收纯文本 HTTP 请求，可以检查并修改它们（包括注入凭证），然后转发到真实 API。

选项 2：HTTP_PROXY / HTTPS_PROXY（系统级）

bash
export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

Claude Code 和 Agent SDK 会识别这些标准环境变量，将所有 HTTP 流量路由到代理。对于 HTTPS，代理创建一个加密的 CONNECT 隧道：它无法查看或修改请求内容，除非进行 TLS 拦截。

实现代理 ​

你可以构建自己的代理或使用现有方案：

  • Envoy Proxy：生产级代理，带有 credential_injector 过滤器用于添加认证头
  • mitmproxy：TLS 终止代理，用于检查和修改 HTTPS 流量
  • Squid：带有访问控制列表的缓存代理
  • LiteLLM：LLM 网关，支持凭证注入和速率限制

其他服务的凭证 ​

除了从 Claude API 采样，Agent 通常还需要认证访问其他服务，如 git 仓库、数据库和内部 API。主要有两种方法：

自定义工具 ​

通过 MCP 服务器或自定义工具，将请求路由到运行在 Agent 安全边界之外的服务。Agent 调用工具，但实际认证请求发生在外部。工具调用到代理，代理注入凭证。

例如，git MCP 服务器可以从 Agent 接收命令，但将它们转发到主机上运行的 git 代理，该代理在联系远程仓库之前添加认证。Agent 永远不会看到凭证。

优点：

  • 无需 TLS 拦截：外部服务直接发起认证请求
  • 凭证保持在外：Agent 只看到工具接口，看不到底层凭证

流量转发 ​

对于 Claude API 调用，ANTHROPIC_BASE_URL 允许你将请求路由到可以明文检查和修改的代理。但对于其他 HTTPS 服务（GitHub、npm 仓库、内部 API），流量通常是端到端加密的。即使通过 HTTP_PROXY 路由，代理也只看到一个不透明的 TLS 隧道，无法注入凭证。

要修改到任意服务的 HTTPS 流量（而不使用自定义工具），你需要一个 TLS 终止代理，解密流量、检查或修改它，然后在转发前重新加密。这需要：

  1. 在 Agent 容器外运行代理
  2. 将代理的 CA 证书安装到 Agent 的信任存储（使 Agent 信任代理的证书）
  3. 配置 HTTP_PROXY/HTTPS_PROXY 以通过代理路由流量

此方法可以处理任何基于 HTTP 的服务而无需编写自定义工具，但增加了证书管理的复杂性。

请注意，并非所有程序都遵循 HTTP_PROXY/HTTPS_PROXY。大多数工具（curl、pip、npm、git）会遵循，但有些可能绕过这些变量直接连接。例如，Node.js 的 fetch() 默认忽略这些变量；在 Node 24+ 中，可设置 NODE_USE_ENV_PROXY=1 启用支持。如需全面覆盖，可使用 proxychains 拦截网络调用，或配置 iptables 将出站流量重定向到透明代理。

透明代理在网络层面拦截流量，客户端无需配置即可使用。常规代理需要客户端显式连接并使用 HTTP CONNECT 或 SOCKS。透明代理（如 Squid 或 mitmproxy 的透明模式）可以处理原始重定向的 TCP 连接。

两种方法仍然需要 TLS 终止代理和受信任的 CA 证书。它们只是确保流量实际到达代理。

文件系统配置 ​

文件系统控制决定 Agent 可以读取和写入哪些文件。

只读代码挂载 ​

当 Agent 需要分析代码但不修改时，将目录挂载为只读：

bash
docker run -v /path/to/code:/workspace:ro agent-image

即使只读访问代码目录也可能暴露凭证。挂载前应排除或清理的常见文件：

文件风险
.env, .env.localAPI 密钥、数据库密码、机密
~/.git-credentialsGit 密码/令牌明文
~/.aws/credentialsAWS 访问密钥
~/.config/gcloud/application_default_credentials.jsonGoogle Cloud ADC 令牌
~/.azure/Azure CLI 凭证
~/.docker/config.jsonDocker 注册表认证令牌
~/.kube/configKubernetes 集群凭证
.npmrc, .pypirc包注册表令牌
*-service-account.jsonGCP 服务账号密钥
*.pem, *.key私钥

考虑只复制需要的源文件，或使用 .dockerignore 样式过滤。

可写入位置 ​

如果 Agent 需要写入文件，根据你是否希望持久化更改，有几种选项：

对于容器中的临时工作区，使用 tmpfs 挂载，仅存在于内存中，容器停止时清除：

bash
docker run \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /workspace:rw,noexec,size=500m \
  agent-image

如果希望先审查更改再持久化，overlay 文件系统允许 Agent 写入而不修改底层文件。更改存储在一个单独的层中，你可以检查、应用或丢弃。对于完全持久化输出，挂载专用卷，但保持与敏感目录分离。

进一步阅读 ​

常见问题 ​

部署 Claude Code 时怎么防止 Prompt 注入导致数据泄露？ ​

使用纵深防御：配置内置权限系统（允许/阻止/审批），结合网络代理实施域名允许列表，并将凭证放在隔离边界外。容器内设置 --network none 并通过 Unix socket 连接代理，是阻止任意出站请求的有效方法。同时避免挂载敏感主机目录（如 ~/.ssh、~/.aws）。

怎么在 Docker 容器中安全运行 Claude Code 并管理 API 密钥？ ​

推荐代理模式：在容器外运行代理（如 Envoy 或 mitmproxy），设置 ANTHROPIC_BASE_URL 指向该代理。代理持有 API 密钥，在转发请求时注入 x-api-key 头。容器内 Agent 从不直接拥有密钥。配合 --cap-drop ALL、--read-only 和 --network none + Unix socket 可进一步加固。

沙箱运行时（sandbox-runtime）和 Docker 容器哪个隔离更安全？ ​

取决于威胁模型。沙箱运行时（基于 bubblewrap/sandbox-exec）轻量且配置简单，但共享主机内核且无 TLS 检查，适用于单开发和 CI/CD。Docker 容器可以结合 gVisor 或虚拟机实现更强隔离（如内核级隔离），但配置复杂且性能开销高。如果处理不可信内容或多租户，推荐 gVisor 或虚拟机 + 代理模式。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策