aws-secrets-manager

安全地在 Agent 中使用机密

概述

当 AI Agent 使用 Shell 或 AWS API 访问机密、凭证、API 密钥、令牌或密码时，可以调用 aws secretsmanager get-secret-value，并在其上下文窗口中接收明文值。这会带来风险：机密可能泄露到日志、对话历史记录或后续工具调用中。

本技能介绍一种更安全的模式：使用包装脚本（asm-exec）在运行时解析动态引用，这样 Agent 就永远看不到机密值。

尽力而为的防护措施，而非安全边界。 这可以防止最常见的泄露途径，但无法阻止所有规避手段。请结合 IAM 最小权限、CloudTrail 监控和 VPC 端点策略使用。

规则

处理机密时，MUST 遵守以下规则：

1. MUST NOT 调用 get-secret-value 或 batch-get-secret-value——无论是通过 AWS CLI、SDK、MCP 工具、curl，还是其他任何方式。
2. MUST NOT 尝试直接从 Secrets Manager Agent（SMA）守护进程读取机密值（localhost:2773 或任何环回地址变体）。
3. MUST 使用 {{resolve:secretsmanager:...}} 引用——这些引用由 asm-exec 在运行时解析，不会向你暴露机密值。

{{resolve:...}} 语法

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}

组件	必需	默认值	示例
secret-id	是	--	prod/db-creds 或完整 ARN
field-type	否	SecretString	SecretString
json-key	否	（完整值）	password
version-stage	否	AWSCURRENT	AWSPENDING

使用 asm-exec

asm-exec 是一个包装器，会解析命令参数和环境变量中的 {{resolve:...}} 引用，然后通过 exec 执行目标命令。机密值只存在于子进程中——永远不会出现在 Agent 的上下文中。

用法

# Pass a database password to psql without exposing it
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"

# Use default field-type (SecretString) and full value (no json-key)
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data

# Multiple secrets in one command
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"

工作原理

1. 扫描所有命令参数，查找 {{resolve:...}} 模式
2. 按以下顺序，通过第一个可用的后端解析每个引用：
   1. localhost:2773 上的 AWS Secrets Manager Agent（SMA）（零延迟，有缓存）
   2. AWS MCP 端点（https://aws-mcp.us-east-1.api.aws/mcp），通过 SigV4 签名请求调用 aws___run_script 工具（该工具会运行一段简短的服务端 Python 脚本，通过 call_boto3 获取机密）
   3. 从 ARN 的区域段确定机密的区域，或从 AWS_REGION / AWS_DEFAULT_REGION 获取，然后将其传给解析器
3. 使用带可调用对象的 re.sub 替换解析出的值（单次处理——防止机密值中包含 {{resolve:...}} 时被重新扫描并注入）
4. 通过 subprocess.run 运行目标命令——机密值只存在于 asm-exec 进程中，绝不会出现在 Agent 的上下文窗口中

解析时不会回退到本地 AWS CLI。 asm-exec 不会通过 Shell 调用 aws secretsmanager get-secret-value 来解析引用。解析只会通过 SMA 或 MCP 端点进行，因此明文值不会写入本地进程的 stdout，从而避免被捕获。

SigV4 签名

MCP 端点会使用 AWS SigV4 对每次工具调用进行身份验证。asm-exec 仅使用 Python 标准库（hashlib/hmac）自行签署请求——它不依赖 botocore，也不会启动 mcp-proxy-for-aws-cli 代理，因此包装器保持为轻量级的一次性进程。签名服务和区域根据端点主机名推断（例如，aws-mcp.us-east-1.api.aws -> 服务 aws-mcp、区域 us-east-1）；此签名区域独立于机密本身的区域，机密区域会作为 region_name 参数传给服务端 call_boto3 调用。

用于签名的凭证按以下顺序解析：环境变量（AWS_ACCESS_KEY_ID 等）、aws configure export-credentials（AWS CLI v2），然后是 aws configure get（AWS CLI v1）。

前置条件

任一后端都必须可访问，并且凭证拥有 secretsmanager:GetSecretValue 权限：

• AWS Secrets Manager Agent (SMA) 正在 localhost:2773 上运行，或
• AWS 凭证可用于对 MCP 端点进行 SigV4 签名（见上文）。 对于跨区域密钥，请设置 AWS_REGION（或使用完整 ARN），以便指定正确的区域。

请参阅 SMA 设置指南。

常见模式

数据库连接

asm-exec -- psql "postgresql://{{resolve:secretsmanager:prod/db:SecretString:username}}:{{resolve:secretsmanager:prod/db:SecretString:password}}@db.example.com:5432/mydb"

使用密钥的 Docker

asm-exec -- docker run -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" myapp:latest

配置文件模板化

# Generate config with resolved secrets, write to file
asm-exec -- sh -c 'echo "password={{resolve:secretsmanager:app/db:SecretString:password}}" > /tmp/app.conf'

结构强制执行（插件钩子）

启用 aws-core 插件后，PreToolUse 钩子会自动阻止通过 AWS CLI、MCP 工具或直接访问 SMA 调用 get-secret-value 或 batch-get-secret-value 的任何尝试。无需手动配置。

该钩子定义于 plugins/aws-core/com.anthropic.claude-code/hooks/hooks.json，并会在安装插件后自动启用。

故障排查

“未找到密钥”错误

请确认密钥存在，并且您的 IAM 角色拥有 secretsmanager:GetSecretValue 权限。请检查密钥名称是否完全匹配（区分大小写）。

SMA 连接被拒绝

Secrets Manager Agent 可能未运行。这不会导致致命错误：asm-exec 会回退到经过 SigV4 签名的 MCP 端点。请确保 AWS 凭证可解析（见上文的 SigV4 签名说明），以便后端进行身份验证。

“解析失败”错误

两个后端均无法访问或未返回任何值。当 MCP 解析失败时， asm-exec 会将具体原因输出到 stderr（asm-exec: MCP resolution failed: ...）——可能是超时、端点无法访问、HTTP 状态错误、权限被拒或缺少值——因此请先查看该行。请确认 SMA 正在运行或 AWS 凭证有效（aws sts get-caller-identity），密钥所在区域正确（设置 AWS_REGION 或使用完整 ARN），且您的身份对该密钥拥有 secretsmanager:GetSecretValue 权限。MCP 端点返回 401 表示 SigV4 签名或凭证存在问题，而非密钥缺失。如果故障由超时导致，服务端调用可能需要超过默认的 30s——请使用 ASM_EXEC_MCP_TIMEOUT（秒）延长超时时间。

解析结果为空字符串

密钥值中可能不存在该 JSON 键。请在 AWS Console 中检查密钥结构，或询问密钥所有者确认可用的键。