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"