aws-secrets-manager

Files (2)

• SKILL.md
• asm-exec · references/

SKILL.md (first lines)

# 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

```bash
# 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).

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

## Common Patterns

### Database connections

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws