自学教程

Claude Agent SDK 安全加固

Claude Code 教程

简介

Claude Agent SDK 的安全风险不只是 API Key 泄露。Agent 具备调用工具、读写文件、访问外部资源能力，一旦被劫持，可能造成文件泄露、数据篡改、越权访问、业务数据丢失。
核心风险清单：

  1. API Key、租户密钥泄露
  2. 提示词注入，劫持 Agent 行为
  3. 工具权限过大，任意文件读写、命令执行
  4. 多租户场景跨租户数据越权访问
  5. 敏感业务数据明文进出模型
  6. 恶意输入造成资源耗尽（DoS）
  7. 模型输出内容包含恶意代码、泄露内部信息

安全加固目标：最小权限原则，Agent 仅拥有完成任务必需的权限，限制攻击面，所有操作可审计。

前置准备

  1. Python3.10+ / Node.js18+
  2. SDK：anthropic / @anthropic-ai/sdk
  3. 依赖：数据库加密组件、Redis、日志审计组件

一、密钥安全管理（最高优先级）

1. API Key 禁止硬编码

❌ 错误：直接写在源码、前端代码、配置文件明文提交Git
✅ 正确：通过环境变量、密钥管理服务（AWS Secrets Manager / HashiCorp Vault）读取

租户自带 Anthropic Key：数据库存储必须 AES 加密，只在调用SDK时解密，解密后内存用完立即销毁。

2. 密钥权限与轮换

  • 平台API Key：限制账号额度，设置月度token上限，防止密钥被盗后巨额账单
  • 定期密钥轮换，废弃旧密钥
  • 密钥泄露告警：异常地区、突增流量、大量token消耗触发告警

3. 禁止前端直连 Anthropic API

所有模型请求必须经过后端代理，前端不能直接访问 Claude API，防止密钥被抓包窃取。

二、提示注入防御

提示注入是Agent最常见攻击手段，用户输入嵌入指令，覆盖system规则。

  1. 用户输入永远不拼接进 system 提示词
    system 固定模板；用户输入放在独立 messages user 块，二者分离。
  2. 使用分隔符隔离用户原始内容
==== 用户输入开始（不可修改） ====
{{user_content}}
==== 用户输入结束 ====
  1. 输入内容清洗：过滤特殊指令标记，限制输入长度，防止超长输入耗尽token
  2. 输出校验：强制Agent输出固定JSON结构，解析失败直接拒绝结果，不执行后续工具操作
  3. 禁止用户自定义 system 提示词（多租户场景如需开放，增加安全审核和长度限制）

三、工具调用安全加固（高危模块）

Agent 的工具（文件读取、shell、数据库、HTTP请求）是安全重灾区，严格遵守最小权限。

1. 文件操作工具加固

  • 每个租户独立工作目录，路径强制前缀绑定 tenant_id
  • 路径校验：禁止 ../、绝对路径，拦截路径穿越攻击
  • 白名单扩展名：只允许读取 .txt .md .js .py 等业务需要文件，禁止读取 .env、密钥文件、数据库配置
  • 只读/读写分离：默认文件工具只读；写入文件单独授权开关

示例路径校验伪代码 Python

import os
def safe_resolve_path(tenant_root: str, user_path: str):
    real_path = os.path.abspath(os.path.join(tenant_root, user_path))
    if not real_path.startswith(os.path.abspath(tenant_root)):
        raise Exception("路径越权，禁止访问")
    return real_path

2. Shell / 命令行工具（强烈不建议开放）

非必要不提供 shell 执行工具。如果业务必须使用：

  • 沙箱隔离容器，每个任务一次性容器，执行完销毁
  • 禁止root权限
  • 命令白名单，只允许预设命令，禁止传入任意用户参数
  • 超时限制，最长执行时间，防止卡死
  • 输出截断，防止返回超大内容

3. HTTP 请求工具

  • 请求域名白名单，禁止访问内网地址、元数据地址（169.254.169.254）、内网数据库
  • 禁止自动跟随重定向
  • 限制请求大小、超时时间

4. 数据库工具

禁止直接使用高权限账号。使用只读账号，限定只能查询租户隔离的数据，SQL增加强制 tenant_id 条件。

四、多租户安全加固

  1. 所有数据表查询/更新，强制带上 tenant_id，防止越权读取其他租户会话、消息
  2. 租户资源隔离：文件目录、缓存Key、会话全部绑定租户ID
  3. 租户开关：支持一键禁用租户账号，紧急阻断攻击
  4. 租户配额限制：token上限、最大并发，防止单个租户耗尽平台资源

五、数据隐私保护

1. 敏感数据脱敏

传入模型前，自动脱敏：手机号、身份证、银行卡、密钥、内部密码。
示例：138****1234，原始敏感数据不发给 Claude API。

2. 数据传输与存储

  • HTTPS 传输所有API请求
  • 会话消息存储：可对消息内容加密（包含tool_use/tool_result）
  • 数据留存策略：会话设置自动过期删除，满足合规要求

3. 数据出境

需要遵守国内数据合规法规，敏感业务数据谨慎发送至境外模型服务。

六、子代理安全隔离

  1. 子代理继承主代理租户权限，不能拥有高于主代理的权限
  2. 子代理独立权限限制：独立文件目录、独立配额
  3. 子代理输出必须校验，子代理返回结果不能直接执行工具操作，主代理做二次校验
  4. 子代理最大数量限制，防止恶意请求无限创建子代理耗尽资源

七、审计日志与异常监控

所有Agent动作必须记录审计日志，日志不可篡改：
日志字段：
request_id, tenant_id, session_id, user_id, 操作类型, 工具名称, 参数摘要, token消耗, 时间戳, 结果状态

监控告警规则：

  • 短时间大量工具调用
  • 多次提示注入攻击命中
  • 尝试访问非法路径、内网地址
  • 突增token用量
  • 大量4xx认证错误

日志不要存储完整用户原始敏感内容，只保留摘要。

八、应用层防DoS保护

  1. 请求限流：用户/租户维度请求频率限制
  2. 输入长度限制，限制单轮用户最大字符长度
  3. 限制单会话最大工具调用总次数，防止无限循环工具调用消耗额度
  4. 任务超时，长时间运行任务强制终止

九、安全测试清单（上线前）

  • [ ] 提示注入测试：尝试绕过system指令
  • [ ] 路径穿越测试：../ ../../etc 读取系统文件
  • [ ] 越权测试：更换session_id，尝试读取其他租户会话
  • [ ] 超长输入DoS测试
  • [ ] 密钥泄露扫描：代码仓库扫描密钥
  • [ ] 工具越权读写文件测试

十、常见安全误区

❌ 认为 Claude 模型本身会自动拒绝恶意指令，不做应用层防护

模型防护不可靠，必须在代码层、工具层做权限校验。

❌ 工具返回内容可信，直接交给Agent继续执行

所有工具返回结果都不可信，需要校验。

❌ 多租户只靠业务代码隔离，数据库SQL不带tenant_id

极易造成越权漏洞。

❌ 把密钥明文保存在数据库、配置文件。

最佳实践

  1. 最小权限原则：Agent、工具、租户账号权限能给多小就多小。
  2. 多层防御：提示防护 + 参数校验 + 工具沙箱 + 审计日志，纵深防御。
  3. 不信任任何输入：用户输入、模型输出、工具返回全部视为不可信。
  4. 分离职责：模型负责推理，应用代码负责权限、校验、安全控制。
  5. 定期安全审计，持续监控异常行为。

小结

Claude Agent SDK安全加固核心是纵深防御，最小权限。重点做好密钥保护、提示注入防御、工具沙箱隔离；多租户场景强制行级数据隔离。模型不能替代代码层安全校验，所有Agent操作必须可审计、可阻断。

标签：

0 条笔记