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>}}

Component	Required	Default	Example
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

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