View a markdown version of this page

使用 AI 编码代理安全使用机密 - Amazon Secrets Manager
工作原理先决条件安装插件{{resolve:...}} 句法使用 asm-exec 运行带有密钥的命令Cross-region 秘密安全注意事项挂钩如何阻止直接秘密访问问题排查
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 AI 编码代理安全使用机密

当 AI 编码代理拥有 shell 或Amazon API 访问权限时，他们可以在上下文窗口中调用get-secret-value和接收纯文本密钥。这会带来多种风险：秘密值可能会泄露到对话历史记录、日志或下游工具调用中。

为防止这种情况，请使用代理工具包中的秘密安全技能Amazon。该技能教导 AI 代理使用在运行时解析的动态引用，因此代理在不看到明文值的情况下编排秘密用法。

重要

这是尽力而为的防御，而不是安全边界。它可以防止最常见的泄漏路径，但无法阻止所有逃避向量。与 IAM 最低权限、 CloudTrail 监控和 VPC 终端节点策略相结合。

工作原理

秘密安全技能提供两层保护：

  1. 技能指导-教导代理使用{{resolve:secretsmanager:...}}动态引用asm-exec，这是一种在运行时解析引用的包装脚本。纯文本值仅存在于子进程中，并且永远不会进入代理的上下文窗口。

  2. 结构强制执行（挂钩）— PreToolUse 挂钩会自动阻止任何尝试调用get-secret-value或batch-get-secret-value通过 SDK Amazon CLI、MCP 工具或直接访问Amazon工作负载凭证提供程序守护程序的尝试。无需手动配置。

先决条件

  • 支持插件的 AI 编码代理，例如 Claude C ode 或 OpenAI Cod ex。

  • 已安装Amazonaws-core插件的代理工具包。

  • 以下秘密解析后端之一：

  • IAM 权限：secretsmanager:GetSecretValue针对您要解析的密钥。

安装插件

安装适用于您的代理平台的aws-core插件。秘密安全技能和钩子会自动激活。

对于克劳德密码：

claude plugin add ./plugins/aws-core

对于 OpenAI 手抄本：

codex plugin add ./plugins/aws-core

有关其他支持的平台，请参阅Amazon自述文件代理工具包。

{{resolve:...}} 句法

当代理需要将密钥传递给命令时，它会使用动态引用而不是调用get-secret-value：

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}
组件 必填 默认值 Description
secret-id 是 – 机密名称或完整的 ARN
field-type 否 SecretString 必须是 SecretString
json-key 否 （全值） 要从 JSON 密钥值中提取的密钥
version-stage 否 AWSCURRENT 版本阶段标签

使用 asm-exec 运行带有密钥的命令

asm-exec是一个包装脚本，它解析命令参数中的{{resolve:...}}引用，然后运行目标命令。密钥值仅存在于子进程中。

asm-exec -- <command> [arguments with {{resolve:...}} references]

asm-exec通过第一个可用的后端解析引用：

  1. Amazon工作负载凭证提供程序已开启 localhost:2773-本地缓存。

  2. Amazon MCP 端点 — 使用可用Amazon凭证进行 SigV4-signed 请求。

例连接到 PostgreSQL 数据库
asm-exec -- psql \
  "host=mydb.example.com \
  user={{resolve:secretsmanager:prod/db-creds:SecretString:username}} \
  password={{resolve:secretsmanager:prod/db-creds:SecretString:password}}" \
  -c "SELECT * FROM users LIMIT 10"
例使用不记名令牌进行 API 调用
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data
例使用多个密钥连接到 MySQL
asm-exec -- mysql \
  -h {{resolve:secretsmanager:prod/mysql:SecretString:host}} \
  -u {{resolve:secretsmanager:prod/mysql:SecretString:username}} \
  -p{{resolve:secretsmanager:prod/mysql:SecretString:password}} \
  -e "SHOW TABLES"
例将密钥作为环境变量传递给 Docker 容器
asm-exec -- docker run \
  -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \
  myapp:latest

Cross-region 秘密

对于存储在与默认区域不同的区域的密钥，请使用完整的 ARN（包括该区域）或设置AWS_REGION环境变量。

# Using full ARN (region is extracted automatically)
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/key-a1b2c3}}" \
  https://eu.api.example.com/data

# Using AWS_REGION
export AWS_REGION=eu-west-1
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:prod/key}}" \
  https://eu.api.example.com/data

安全注意事项

  • 子进程隔离-目标命令通过subprocess.run运行。秘密值仅存在于asm-exec进程内存和子进程参数中。

挂钩如何阻止直接秘密访问

启用aws-core插件后，PreToolUse挂钩会在执行前拦截工具调用。它会阻挡：

  • aws secretsmanager get-secret-value并batch-get-secret-value通过 CLI

  • get_secret_value并batch_get_secret_value通过脚本中的 SDK 调用

  • 直接访问Amazon工作负载凭证提供程序守护程序路径 () localhost:2773/secretsmanager/get

  • GetSecretValue通过 MCP 工具或结构化Amazon API 调用进行操作

当呼叫被屏蔽时，代理会收到一条拒绝消息，指示其asm-exec改用{{resolve:...}}引用。

问题排查

“未找到秘密” 错误

验证密钥是否存在且您的 IAM 角色拥有secretsmanager:GetSecretValue权限。机密名称区分大小写。

Amazon工作负载凭证提供程序连接被拒绝

工作Amazon负载凭证提供程序可能未运行。这不是致命的——会一直asm-exec延伸到 SigV4-signed MCP 端点。确保Amazon凭据可用，以便后端可以进行身份验证。

“无法解决” 错误

两个后端都无法访问。检查Amazon工作负载凭证提供程序是否正在运行或Amazon凭据是否有效（aws sts get-caller-identity），密钥的区域是否正确，以及密钥secretsmanager:GetSecretValue上是否有您的身份。

分辨率生成空字符串

密钥值中可能不存在 JSON 密钥。在Amazon控制台中验证密钥结构或要求密钥所有者确认可用的密钥。

Hook 不会屏蔽通话

代理会话开始时会加载挂钩。如果您在会话中安装了插件，请重新启动代理会话以激活挂机。