The Complete Production SOP: How to Deploy and Run AWS Secrets Manager Automated KMS Rotation in Autonomous AI Agents

---
name: "aws-secrets-manager-rotation"
description: "Store, retrieve, and automatically rotate database credentials with AWS Secrets Manager."
metadata:
  author: "AWS"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "retrieve secret from aws secrets manager"
  - "setup automated secret rotation lambda"
  - "encrypt secret with kms"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
import { LRUCache } from 'lru-cache';

const client = new SecretsManagerClient({ region: process.env.AWS_REGION || 'us-east-1' });

// Cache secrets for 300 seconds (5 min) to prevent API spam and KMS throttling
const secretCache = new LRUCache<string, Record<string, string>>({
  max: 50,
  ttl: 1000 * 60 * 5
});

export async function getCachedDatabaseSecret(secretArnOrName: string): Promise<Record<string, string>> {
  const cached = secretCache.get(secretArnOrName);
  if (cached) return cached;

  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretArnOrName })
  );

  if (!response.SecretString) {
    throw new Error(`Secret ${secretArnOrName} does not contain valid SecretString payload.`);
  }

  const parsed = JSON.parse(response.SecretString);
  secretCache.set(secretArnOrName, parsed);
  return parsed;
}

import boto3
import json
import os

sm_client = boto3.client('secretsmanager')

def lambda_handler(event, context):
    arn = event['SecretId']
    token = event['ClientRequestToken']
    step = event['Step']
    
    metadata = sm_client.describe_secret(SecretId=arn)
    if not metadata['RotationEnabled']:
        raise ValueError(f'Secret {arn} is not enabled for rotation')
        
    versions = metadata['VersionIdsToStages']
    if token not in versions:
        raise ValueError(f'Secret version {token} has no stage for rotation of secret {arn}')
        
    if 'AWSCURRENT' in versions[token]:
        return
    elif 'AWSPENDING' not in versions[token]:
        raise ValueError(f'Secret version {token} not AWSPENDING for secret {arn}')
        
    if step == 'createSecret':
        create_secret(arn, token)
    elif step == 'setSecret':
        set_secret(arn, token)
    elif step == 'testSecret':
        test_secret(arn, token)
    elif step == 'finishSecret':
        finish_secret(arn, token)
    else:
        raise ValueError(f'Invalid step {step}')

def create_secret(arn, token):
    try:
        sm_client.get_secret_value(SecretId=arn, VersionId=token, VersionStage='AWSPENDING')
    except sm_client.exceptions.ResourceNotFoundException:
        new_password = sm_client.get_random_password(ExcludeCharacters='"/@\\', PasswordLength=32)['RandomPassword']
        current = json.loads(sm_client.get_secret_value(SecretId=arn, VersionStage='AWSCURRENT')['SecretString'])
        current['password'] = new_password
        sm_client.put_secret_value(SecretId=arn, ClientRequestToken=token, SecretString=json.dumps(current), VersionStages=['AWSPENDING'])

def set_secret(arn, token):
    # Alter database user password to AWSPENDING password via direct connection
    pass

def test_secret(arn, token):
    # Verify connection using AWSPENDING password
    pass

def finish_secret(arn, token):
    metadata = sm_client.describe_secret(SecretId=arn)
    current_version = None
    for v, stages in metadata['VersionIdsToStages'].items():
        if 'AWSCURRENT' in stages:
            current_version = v
            break
    sm_client.update_secret_version_stage(SecretId=arn, VersionStage='AWSCURRENT', MoveToVersionId=token, RemoveFromVersionId=current_version)

#!/usr/bin/env bash
set -euo pipefail

echo "Running credential leakage scan on generated files..."
if grep -rEi "(console\.log|logger\.|print).*SecretString" src/ handlers/; then
  echo "ERROR: Detected direct logging of raw SecretString. Violates skill safety rules!" >&2
  exit 1
fi
echo "Sanitization audit passed. Zero credential leaks found."