/aws-secrets-manager

name: aws-secrets-manager
description: >
  Secret safety for AWS Secrets Manager, secret management, credentials, API keys,
  tokens, and passwords. Prevents AI agents from directly fetching secret values
  and teaches runtime dynamic references with asm-exec so plaintext never enters
  the LLM context window.
metadata:
  version: "2"

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 `exec`s 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.

**Prefer SMA for repeated or automated use.** The [AWS Secrets Manager Agent](https://docs.aws.amazon.com/secretsmanager/latest/userguide/secrets-manager-agent.html) serves secrets from a local in-memory cache on `localhost`, so lookups return in milliseconds, repeated runs make fewer Secrets Manager API calls, and cached values refresh automatically. Agents and scripts that call asm-exec often should run SMA locally; asm-exec uses it automatically when it is reachable.

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

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](https://docs.aws.amazon.com/secretsmanager/latest/userguide/secrets-manager-agent.html).