本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 AI 編碼代理程式安全地使用秘密
<a name="retrieving-secrets-ai-agents"></a>

當 AI 編碼代理程式具有 shell 或AWS API 存取權時，他們可以在其內容視窗中呼叫`get-secret-value`和接收純文字秘密。這會產生多種風險：秘密值可能會洩漏到對話歷史記錄、日誌或下游工具呼叫中。

若要避免這種情況，請使用 [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws) 中的*秘密安全*技能。此技能會教導 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 AWS CLI、MCP 工具或直接存取AWS工作負載登入資料提供者協助程式的嘗試。不需進行手動組態。

## 先決條件
<a name="retrieving-secrets-ai-agents-prerequisites"></a>
+ 支援外掛程式的 AI 編碼代理程式，例如 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenAI Codex](https://openai.com/index/codex/)。
+ 安裝的 [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` 外掛程式。
+ 下列其中一個秘密解析後端：
  + 在 上執行**AWS的工作負載登入資料提供者**`localhost:2773`。請參閱 [使用AWS工作負載登入資料提供者](workload-credentials-provider.md)。
  + 可簽署AWS MCP 端點請求的**AWS憑證**。
+ IAM 許可：在您要解析的秘密`secretsmanager:GetSecretValue`上。

## 安裝外掛程式。
<a name="retrieving-secrets-ai-agents-install"></a>

安裝代理程式平台的`aws-core`外掛程式。秘密安全技能和掛鉤會自動啟用。

對於 Claude Code：

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

對於 OpenAI Codex：

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

如需其他支援的平台，請參閱 [Agent Toolkit for AWS README](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>}}
```


| 元件 | 必要 | 預設 | 說明 | 
| --- | --- | --- | --- | 
| 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. **AWS上的工作負載登入資料提供者** `localhost:2773` – 本機快取。

1. **AWS MCP 端點** – 使用可用AWS登入資料的 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
```

## 跨區域秘密
<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 呼叫
+ 直接存取AWS工作負載登入資料提供者協助程式路徑 (`localhost:2773/secretsmanager/get`)
+ `GetSecretValue` 透過 MCP 工具或結構化AWS 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` 許可。秘密名稱區分大小寫。

### AWS工作負載登入資料提供者連線遭拒
<a name="retrieving-secrets-ai-agents-ts-connection-refused"></a>

AWS工作負載登入資料提供者可能未執行。這是非嚴重 – `asm-exec`屬於 SigV4-signed MCP 端點。確保AWS憑證可用，以便後端進行身分驗證。

### 「無法解決」錯誤
<a name="retrieving-secrets-ai-agents-ts-failed-resolve"></a>

兩個後端都無法連線。檢查AWS工作負載登入資料提供者是否正在執行或AWS登入資料是否有效 (`aws sts get-caller-identity`)、秘密的區域是否正確，以及您的身分是否在秘密`secretsmanager:GetSecretValue`上。

### 解析會產生空字串
<a name="retrieving-secrets-ai-agents-ts-empty-string"></a>

JSON 金鑰可能不存在於秘密值中。在AWS主控台中驗證秘密結構，或要求秘密擁有者確認可用的金鑰。

### 勾點不會封鎖呼叫
<a name="retrieving-secrets-ai-agents-ts-hook-not-blocking"></a>

在客服人員工作階段開始時掛接負載。如果您已在工作階段中安裝外掛程式，請重新啟動要啟用掛鉤的代理程式工作階段。