Back to Details

aws-secrets-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Secrets Safely with Agents

与Agent安全协作使用密钥

Overview

概述

When AI agents handle secrets, credentials, API keys, tokens, or passwords with shell or AWS API access, they can call 
aws secretsmanager get-secret-value
and receive plaintext values in their context window. This creates risk: secrets may leak into logs, conversation history, or downstream tool calls.
This skill teaches a safer pattern: dynamic references resolved at runtime by a wrapper script (
asm-exec
), so the agent never sees the secret value.
Best-effort defense, not a security boundary. This prevents the most common leakage path but cannot stop all evasion vectors. Combine with IAM least-privilege, CloudTrail monitoring, and VPC endpoint policies.
当AI Agent通过Shell或AWS API访问密钥、凭证、API密钥、令牌或密码时，它们可能会调用
aws secretsmanager get-secret-value
，并在其上下文窗口中接收明文值。这会带来风险：密钥可能泄露到日志、对话历史或下游工具调用中。
本技能教授一种更安全的模式：动态引用，由包装脚本(
asm-exec
)在运行时解析，因此Agent永远不会看到密钥值。
尽力而为的防御措施，而非安全边界。 这可以防止最常见的泄露路径，但无法阻止所有规避手段。请结合IAM最小权限原则、CloudTrail监控和VPC端点策略使用。

Rules

规则

You MUST follow these rules when working with secrets:
  1. MUST NOT call 
    get-secret-value
    or 
    batch-get-secret-value
     -- not via AWS CLI, SDK, MCP tools, curl, or any other mechanism.
  2. MUST NOT attempt to read secret values from the Secrets Manager Agent (SMA) daemon directly (localhost:2773 or any loopback variant).
  3. MUST use 
    {{resolve:secretsmanager:...}}
    references     -- these are resolved at runtime by 
    asm-exec
    without exposing values to you.
处理密钥时必须遵循以下规则：
  1. 严禁调用
    get-secret-value
    或
    batch-get-secret-value
    ——无论通过AWS CLI、SDK、MCP工具、curl还是其他任何机制。
  2. 严禁尝试直接从Secrets Manager Agent (SMA)守护进程读取密钥值（localhost:2773或任何回环变体）。
  3. 必须使用
    {{resolve:secretsmanager:...}}
    引用    ——这些引用由
    asm-exec
    在运行时解析，不会向你暴露值。

The 
{{resolve:...}}
Syntax

{{resolve:...}}
语法

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}
ComponentRequiredDefaultExample
secret-id
Yes--
prod/db-creds
or full ARN
field-type
No
SecretString
SecretString
json-key
No(full value)
password
version-stage
No
AWSCURRENT
AWSPENDING
{{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

Using 
asm-exec

使用
asm-exec

asm-exec
is a wrapper that resolves 
{{resolve:...}}
references in command arguments and environment variables, then 
exec
s the target command. The secret value exists only in the child process -- never in the agent's context.
asm-exec
是一个包装器，用于解析命令参数和环境变量中的
{{resolve:...}}
引用，然后
exec
目标命令。密钥值仅存在于子进程中——永远不会出现在Agent的上下文中。

Usage

使用方法

bash
undefined
bash
undefined

Pass a database password to psql without exposing it

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"
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)

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
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}"
https://api.example.com/data

Multiple secrets in one command

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"
undefined
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"
undefined

How It Works

工作原理

  1. Scans all command arguments for 
    {{resolve:...}}
    patterns
  2. Resolves each reference through the first available backend, in order:
    1. AWS Secrets Manager Agent (SMA) on localhost:2773 (zero-latency, cached)
    2. AWS MCP endpoint (
      https://aws-mcp.us-east-1.api.aws/mcp
      ), calling the 
      aws___call_aws
      tool over a SigV4-signed request
    3. Determines the secret's region from an ARN's region segment, or from 
      AWS_REGION
      / 
      AWS_DEFAULT_REGION
      , and passes it to the resolver
  3. Substitutes resolved values using 
    re.sub
    with a callable (single-pass -- prevents re-scan injection if a secret value contains 
    {{resolve:...}}
    )
  4. Runs the target command via 
    subprocess.run
    -- secret values exist only in the asm-exec process, never in the agent's context window
No local AWS CLI fallback for resolution. 
asm-exec
does not shell out to 
aws secretsmanager get-secret-value
to resolve references. Resolution happens only through SMA or the MCP endpoint, so the plaintext value is never written to a local process's stdout where it could be captured.
  1. 扫描所有命令参数，查找
    {{resolve:...}}
    模式
  2. 通过以下可用后端依次解析每个引用：
    1. 本地主机:2773上的AWS Secrets Manager Agent (SMA)（零延迟、缓存）
    2. AWS MCP端点 (
      https://aws-mcp.us-east-1.api.aws/mcp
      )，通过SigV4签名请求调用
      aws___call_aws
      工具
    3. 从ARN的区域段或
      AWS_REGION
      /
      AWS_DEFAULT_REGION
      确定密钥的区域，并将其传递给解析器
  3. 使用带可调用对象的
    re.sub
    替换解析后的值（单次替换——防止如果密钥值包含
    {{resolve:...}}
    时的重新扫描注入）
  4. 通过
    subprocess.run
    运行目标命令——密钥值仅存在于asm-exec进程中，永远不会出现在Agent的上下文窗口中
无本地AWS CLI回退解析机制。 
asm-exec
不会通过调用
aws secretsmanager get-secret-value
来解析引用。解析仅通过SMA或MCP端点进行，因此明文值永远不会写入本地进程的stdout，避免被捕获。

SigV4 signing

SigV4签名

The MCP endpoint authenticates every tool call with AWS SigV4. 
asm-exec
signs requests itself using only the Python standard library (
hashlib
/
hmac
) -- it does not depend on botocore or spin up the 
mcp-proxy-for-aws
proxy, keeping the wrapper a lightweight ephemeral process. The signing service and region are inferred from the endpoint hostname (e.g. 
aws-mcp.us-east-1.api.aws
-> service 
aws-mcp
, region 
us-east-1
); this signing region is independent of the secret's own region, which is passed as 
--region
to the server-side CLI command.
Credentials for signing are resolved in order: environment variables (
AWS_ACCESS_KEY_ID
etc.), 
aws configure export-credentials
(AWS CLI v2), then 
aws configure get
(AWS CLI v1).
MCP端点使用AWS SigV4对每个工具调用进行身份验证。
asm-exec
仅使用Python标准库(
hashlib
/
hmac
)自行签署请求——它不依赖botocore或启动
mcp-proxy-for-aws
代理，使包装器成为轻量级临时进程。签名服务和区域从端点主机名推断（例如
aws-mcp.us-east-1.api.aws
-> 服务
aws-mcp
，区域
us-east-1
）；此签名区域独立于密钥自身的区域，后者作为
--region
传递给服务器端CLI命令。
签名凭证按以下顺序解析：环境变量(
AWS_ACCESS_KEY_ID
等)、
aws configure export-credentials
（AWS CLI v2），然后是
aws configure get
（AWS CLI v1）。

Prerequisites

前提条件

Either backend must be reachable, with credentials that have 
secretsmanager:GetSecretValue
permission:
  • AWS Secrets Manager Agent (SMA) running on localhost:2773, OR
  • AWS credentials resolvable for SigV4 signing of the MCP endpoint (see above). For cross-region secrets, set 
    AWS_REGION
    (or use a full ARN) so the correct region is targeted.
See SMA setup guide.
必须能够访问其中一个后端，且凭证拥有
secretsmanager:GetSecretValue
权限：
  • 本地主机:2773上运行的AWS Secrets Manager Agent (SMA)，或
  • 可解析用于对MCP端点进行SigV4签名的AWS凭证（见上文）。对于跨区域密钥，请设置
    AWS_REGION
    （或使用完整ARN）以定位正确的区域。
请参阅SMA设置指南。

Common Patterns

常见模式

Database connections

数据库连接

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

Docker with secrets

Docker与密钥

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

Configuration file templating

配置文件模板化

bash
undefined
bash
undefined

Generate config with resolved secrets, write to file

Generate config with resolved secrets, write to file

asm-exec -- sh -c 'echo "password={{resolve:secretsmanager:app/db:SecretString:password}}" > /tmp/app.conf'
undefined
asm-exec -- sh -c 'echo "password={{resolve:secretsmanager:app/db:SecretString:password}}" > /tmp/app.conf'
undefined

Structural Enforcement (Plugin Hook)

结构强制（插件钩子）

When the 
aws-core
plugin is enabled, a 
PreToolUse
hook automatically blocks any attempt to call 
get-secret-value
or 
batch-get-secret-value
-- via AWS CLI, MCP tools, or direct SMA access. No manual configuration needed.
The hook is defined at 
plugins/aws-core/hooks/hooks.json
and activates automatically when the plugin is installed.
当启用
aws-core
插件时，
PreToolUse
钩子会自动阻止任何调用
get-secret-value
或
batch-get-secret-value
的尝试——无论通过AWS CLI、MCP工具还是直接SMA访问。无需手动配置。
该钩子定义在
plugins/aws-core/hooks/hooks.json
中，安装插件后自动激活。

Troubleshooting

故障排除

"Secret not found" errors

"未找到密钥"错误

Verify the secret exists and your IAM role has 
secretsmanager:GetSecretValue
permission. Check the secret name matches exactly (case-sensitive).
验证密钥是否存在，且你的IAM角色拥有
secretsmanager:GetSecretValue
权限。检查密钥名称是否完全匹配（区分大小写）。

SMA connection refused

SMA连接被拒绝

The Secrets Manager Agent may not be running. This is non-fatal: 
asm-exec
falls through to the SigV4-signed MCP endpoint. Ensure AWS credentials are resolvable (see SigV4 signing above) so that backend can authenticate.
Secrets Manager Agent可能未运行。这是非致命的：
asm-exec
会回退到SigV4签名的MCP端点。确保AWS凭证可解析（见上文SigV4签名部分），以便后端进行身份验证。

"Failed to resolve" errors

"解析失败"错误

Both backends were unreachable or returned no value. Check that either SMA is running or AWS credentials are valid (
aws sts get-caller-identity
), that the secret's region is correct (set 
AWS_REGION
or use a full ARN), and that your identity has 
secretsmanager:GetSecretValue
on the secret. A 
401
from the MCP endpoint indicates a SigV4 signing or credential problem, not a missing secret.
两个后端均无法访问或未返回值。检查SMA是否运行，或AWS凭证是否有效（
aws sts get-caller-identity
），密钥的区域是否正确（设置
AWS_REGION
或使用完整ARN），以及你的身份是否对该密钥拥有
secretsmanager:GetSecretValue
权限。MCP端点返回的
401
表示SigV4签名或凭证问题，而非密钥缺失。

Resolution produces empty string

解析结果为空字符串

The JSON key may not exist in the secret value. Verify the secret structure in the AWS Console or ask the secret owner to confirm the available keys.
JSON密钥可能不存在于密钥值中。请在AWS控制台中验证密钥结构，或请密钥所有者确认可用的密钥。