View a markdown version of this page

使用 AI 編碼代理程式安全地使用秘密 - AWS Secrets Manager
運作方式先決條件安裝外掛程式。{{resolve:...}} 語法使用 asm-exec執行具有秘密的命令跨區域秘密安全考量勾點如何封鎖直接私密存取疑難排解

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

使用 AI 編碼代理程式安全地使用秘密

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

若要避免這種情況，請使用 Agent Toolkit for AWS 中的秘密安全技能。此技能會教導 AI 代理器使用在執行時間解析的動態參考，因此代理程式會協調秘密用量，而不會看到純文字值。

重要

這是最佳防禦，而不是安全界限。它可防止最常見的洩漏路徑，但無法停止所有逃生向量。結合 IAM 最低權限、CloudTrail 監控和 VPC 端點政策。

運作方式

秘密安全技能提供兩層保護：

  1. 技能指引 – 教導代理程式搭配 使用{{resolve:secretsmanager:...}}動態參考asm-exec，這是在執行時間解析參考的包裝函式指令碼。純文字值僅存在於子程序中，絕不會進入客服人員的內容視窗。

  2. 結構強制執行 （勾點） – PreToolUse勾點會自動封鎖任何呼叫get-secret-valuebatch-get-secret-value或透過 SDK AWS CLI、MCP 工具或直接存取AWS工作負載登入資料提供者協助程式的嘗試。不需進行手動組態。

先決條件

安裝外掛程式。

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

對於 Claude Code：

claude plugin add ./plugins/aws-core

對於 OpenAI Codex：

codex plugin add ./plugins/aws-core

如需其他支援的平台，請參閱 Agent Toolkit for AWS README。

{{resolve:...}} 語法

當客服人員需要將秘密傳遞至命令時，會使用動態參考，而不是呼叫 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執行具有秘密的命令

asm-exec 是包裝函式指令碼，可解析命令引數中的{{resolve:...}}參考，然後執行目標命令。秘密值僅存在於子程序中。

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

asm-exec 透過第一個可用的後端解析參考：

  1. AWS上的工作負載登入資料提供者 localhost:2773 – 本機快取。

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

跨區域秘密

對於存放在與預設區域不同的區域中的秘密，請使用完整的 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 呼叫

  • 直接存取AWS工作負載登入資料提供者協助程式路徑 (localhost:2773/secretsmanager/get)

  • GetSecretValue 透過 MCP 工具或結構化AWS API 呼叫進行 操作

當通話遭到封鎖時，客服人員會收到拒絕訊息，指示其asm-exec改用 {{resolve:...}} 參考。

疑難排解

「找不到秘密」錯誤

驗證秘密是否存在，且您的 IAM 角色具有 secretsmanager:GetSecretValue 許可。秘密名稱區分大小寫。

AWS工作負載登入資料提供者連線遭拒

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

「無法解決」錯誤

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

解析會產生空字串

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

勾點不會封鎖呼叫

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