Update to AWS Core

{
  "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.\n",
  "included_files": [
    {
      "relative_path": "references/asm-exec",
      "size_in_bytes": 14904
    }
  ],
  "skill_md_contents": "---\nname: aws-secrets-manager\ndescription: >\n  Secret safety for AWS Secrets Manager, secret management, credentials, API keys,\n  tokens, and passwords. Prevents AI agents from directly fetching secret values\n  and teaches runtime dynamic references with asm-exec so plaintext never enters\n  the LLM context window.\nversion: 1\n---\n\n# Using Secrets Safely with Agents\n\n## Overview\n\nWhen AI agents handle secrets, credentials, API keys, tokens, or passwords with\nshell or AWS API access, they can call `aws secretsmanager get-secret-value`\nand receive plaintext values in their context window. This creates risk:\nsecrets may leak into logs, conversation history, or downstream tool calls.\n\nThis skill teaches a safer pattern: **dynamic references** resolved at runtime\nby a wrapper script (`asm-exec`), so the agent never sees the secret value.\n\n> **Best-effort defense, not a security boundary.** This prevents the most common\n> leakage path but cannot stop all evasion vectors. Combine with IAM\n> least-privilege, CloudTrail monitoring, and VPC endpoint policies.\n\n## Rules\n\nYou MUST follow these rules when working with secrets:\n\n1. **MUST NOT call `get-secret-value` or `batch-get-secret-value`** -- not via AWS\n   CLI, SDK, MCP tools, curl, or any other mechanism.\n2. **MUST NOT attempt to read secret values** from the Secrets Manager Agent (SMA)\n   daemon directly (localhost:2773 or any loopback variant).\n3. **MUST use `{{resolve:secretsmanager:...}}` references** -- these are\n   resolved at runtime by `asm-exec` without exposing values to you.\n\n## The `{{resolve:...}}` Syntax\n\n```\n{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}\n```\n\n| Component | Required | Default | Example |\n|-----------|----------|---------|---------|\n| `secret-id` | Yes | -- | `prod/db-creds` or full ARN |\n| `field-type` | No | `SecretString` | `SecretString` |\n| `json-key` | No | (full value) | `password` |\n| `version-stage` | No | `AWSCURRENT` | `AWSPENDING` |\n\n## Using `asm-exec`\n\n`asm-exec` is a wrapper that resolves `{{resolve:...}}` references in command\narguments and environment variables, then `exec`s the target command. The secret\nvalue exists only in the child process -- never in the agent's context.\n\n### Usage\n\n```bash\n# Pass a database password to psql without exposing it\nasm-exec -- psql \\\n  \"host=mydb.example.com \\\n   user={{resolve:secretsmanager:prod/db-creds:SecretString:username}} \\\n   password={{resolve:secretsmanager:prod/db-creds:SecretString:password}}\" \\\n  -c \"SELECT * FROM users LIMIT 10\"\n\n# Use default field-type (SecretString) and full value (no json-key)\nasm-exec -- curl -H \"Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}\" \\\n  https://api.example.com/data\n\n# Multiple secrets in one command\nasm-exec -- mysql \\\n  -h {{resolve:secretsmanager:prod/mysql:SecretString:host}} \\\n  -u {{resolve:secretsmanager:prod/mysql:SecretString:username}} \\\n  -p{{resolve:secretsmanager:prod/mysql:SecretString:password}} \\\n  -e \"SHOW TABLES\"\n```\n\n### How It Works\n\n1. Scans all command arguments for `{{resolve:...}}` patterns\n2. Resolves each reference through the first available backend, in order:\n   1. **AWS Secrets Manager Agent (SMA)** on localhost:2773 (zero-latency, cached)\n   2. **AWS MCP endpoint** (`https://aws-mcp.us-east-1.api.aws/mcp`), calling the\n      `aws___call_aws` tool over a SigV4-signed request\n   3. Determines the secret's region from an ARN's region segment, or from\n      `AWS_REGION` / `AWS_DEFAULT_REGION`, and passes it to the resolver\n3. Substitutes resolved values using `re.sub` with a callable (single-pass --\n   prevents re-scan injection if a secret value contains `{{resolve:...}}`)\n4. Runs the target command via `subprocess.run` -- secret values exist only in the\n   asm-exec process, never in the agent's context window\n\n> **No local AWS CLI fallback for resolution.** `asm-exec` does not shell out to\n> `aws secretsmanager get-secret-value` to resolve references. Resolution happens\n> only through SMA or the MCP endpoint, so the plaintext value is never written to\n> a local process's stdout where it could be captured.\n\n### SigV4 signing\n\nThe MCP endpoint authenticates every tool call with AWS SigV4. `asm-exec` signs\nrequests itself using only the Python standard library (`hashlib`/`hmac`) -- it\ndoes **not** depend on botocore or spin up the `mcp-proxy-for-aws` proxy, keeping\nthe wrapper a lightweight ephemeral process. The signing service and region are\ninferred from the endpoint hostname (e.g. `aws-mcp.us-east-1.api.aws` ->\nservice `aws-mcp`, region `us-east-1`); this signing region is independent of the\nsecret's own region, which is passed as `--region` to the server-side CLI command.\n\nCredentials for signing are resolved in order: environment variables\n(`AWS_ACCESS_KEY_ID` etc.), `aws configure export-credentials` (AWS CLI v2), then\n`aws configure get` (AWS CLI v1).\n\n### Prerequisites\n\nEither backend must be reachable, with credentials that have\n`secretsmanager:GetSecretValue` permission:\n\n- **AWS Secrets Manager Agent (SMA)** running on localhost:2773, OR\n- **AWS credentials** resolvable for SigV4 signing of the MCP endpoint (see above).\n  For cross-region secrets, set `AWS_REGION` (or use a full ARN) so the correct\n  region is targeted.\n\nSee [SMA setup guide](https://docs.aws.amazon.com/secretsmanager/latest/userguide/secrets-manager-agent.html).\n\n## Common Patterns\n\n### Database connections\n\n```bash\nasm-exec -- psql \"postgresql://{{resolve:secretsmanager:prod/db:SecretString:username}}:{{resolve:secretsmanager:prod/db:SecretString:password}}@db.example.com:5432/mydb\"\n```\n\n### Docker with secrets\n\n```bash\nasm-exec -- docker run -e \"DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}\" myapp:latest\n```\n\n### Configuration file templating\n\n```bash\n# Generate config with resolved secrets, write to file\nasm-exec -- sh -c 'echo \"password={{resolve:secretsmanager:app/db:SecretString:password}}\" > /tmp/app.conf'\n```\n\n## Structural Enforcement (Plugin Hook)\n\nWhen the `aws-core` plugin is enabled, a `PreToolUse` hook automatically blocks\nany attempt to call `get-secret-value` or `batch-get-secret-value` -- via AWS CLI,\nMCP tools, or direct SMA access. No manual configuration needed.\n\nThe hook is defined at `plugins/aws-core/hooks/hooks.json` and activates\nautomatically when the plugin is installed.\n\n## Troubleshooting\n\n### \"Secret not found\" errors\n\nVerify the secret exists and your IAM role has `secretsmanager:GetSecretValue`\npermission. Check the secret name matches exactly (case-sensitive).\n\n### SMA connection refused\n\nThe Secrets Manager Agent may not be running. This is non-fatal: `asm-exec`\nfalls through to the SigV4-signed MCP endpoint. Ensure AWS credentials are\nresolvable (see SigV4 signing above) so that backend can authenticate.\n\n### \"Failed to resolve\" errors\n\nBoth backends were unreachable or returned no value. Check that either SMA is\nrunning or AWS credentials are valid (`aws sts get-caller-identity`), that the\nsecret's region is correct (set `AWS_REGION` or use a full ARN), and that your\nidentity has `secretsmanager:GetSecretValue` on the secret. A `401` from the MCP\nendpoint indicates a SigV4 signing or credential problem, not a missing secret.\n\n### Resolution produces empty string\n\nThe JSON key may not exist in the secret value. Verify the secret structure\nin the AWS Console or ask the secret owner to confirm the available keys.\n"
}