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

# 使用 AI 编码代理安全使用机密
<a name="retrieving-secrets-ai-agents"></a>

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

为防止这种情况，请使用[代理工具包](https://github.com/aws/agent-toolkit-for-aws)中的*秘密安全*技能Amazon。该技能教导 AI 代理使用在运行时解析的动态引用，因此代理在不看到明文值的情况下编排秘密用法。

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

## 工作原理
<a name="retrieving-secrets-ai-agents-how-it-works"></a>

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

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

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

## 先决条件
<a name="retrieving-secrets-ai-agents-prerequisites"></a>
+ 支持插件的 AI 编码代理，例如 Claude C [ode 或 [OpenAI](https://openai.com/index/codex/) Cod](https://docs.anthropic.com/en/docs/claude-code) ex。
+ 已安装Amazon`aws-core`插件[的代理工具包](https://github.com/aws/agent-toolkit-for-aws)。
+ 以下秘密解析后端之一：
  + **Amazon工作负载凭证提供程序**正在运行`localhost:2773`。请参阅[使用Amazon工作负载凭证提供程序](workload-credentials-provider.md)。
  + Amazon可以@@ **对Amazon MCP 端点的请求进行签名的凭证**。
+ IAM 权限：`secretsmanager:GetSecretValue`针对您要解析的密钥。

## 安装插件
<a name="retrieving-secrets-ai-agents-install"></a>

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

对于克劳德密码：

```
claude plugin add ./plugins/aws-core
```

对于 OpenAI 手抄本：

```
codex plugin add ./plugins/aws-core
```

有关其他支持的平台，请参阅[Amazon自述文件代理工具包](https://github.com/aws/agent-toolkit-for-aws)。

## `{{resolve:...}}` 句法
<a name="retrieving-secrets-ai-agents-syntax"></a>

当代理需要将密钥传递给命令时，它会使用动态引用而不是调用`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 运行带有密`钥的命令
<a name="retrieving-secrets-ai-agents-asm-exec"></a>

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

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

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

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

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

**Example 连接到 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"
```

**Example 使用不记名令牌进行 API 调用**  

```
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data
```

**Example 使用多个密钥连接到 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"
```

**Example 将密钥作为环境变量传递给 Docker 容器**  

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

## Cross-region 秘密
<a name="retrieving-secrets-ai-agents-cross-region"></a>

对于存储在与默认区域不同的区域的密钥，请使用完整的 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
```

## 安全注意事项
<a name="retrieving-secrets-ai-agents-security"></a>
+ **子进程隔离**-目标命令通过`subprocess.run`运行。秘密值仅存在于`asm-exec`进程内存和子进程参数中。

## 挂钩如何阻止直接秘密访问
<a name="retrieving-secrets-ai-agents-hook"></a>

启用`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:...}}`引用。

## 问题排查
<a name="retrieving-secrets-ai-agents-troubleshooting"></a>

### “未找到秘密” 错误
<a name="retrieving-secrets-ai-agents-ts-not-found"></a>

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

### Amazon工作负载凭证提供程序连接被拒绝
<a name="retrieving-secrets-ai-agents-ts-connection-refused"></a>

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

### “无法解决” 错误
<a name="retrieving-secrets-ai-agents-ts-failed-resolve"></a>

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

### 分辨率生成空字符串
<a name="retrieving-secrets-ai-agents-ts-empty-string"></a>

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

### Hook 不会屏蔽通话
<a name="retrieving-secrets-ai-agents-ts-hook-not-blocking"></a>

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