AWS Secrets Manager

Using Secrets Safely with Agents

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.

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.

The {{resolve:...}} Syntax

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

Using asm-exec

asm-exec is a wrapper that resolves {{resolve:...}} references in command arguments and environment variables, then execs the target command. The secret value exists only in the child process -- never in the agent's context.

Usage

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

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___run_script tool over a SigV4-signed request (the tool runs a short server-side Python script that fetches the secret via call_boto3)
   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.

SigV4 signing

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-cli 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 the region_name argument to the server-side call_boto3 call.

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