How the Agent Toolkit for AWS Handles Secrets Management: Architecture and Best Practices

The Agent Toolkit for AWS centralizes secrets management in AWS Secrets Manager, enforcing least-privilege IAM policies, runtime SDK retrieval, and automated rotation while prohibiting hard-coded credentials through guardrail rules.

The aws/agent-toolkit-for-aws repository provides a security-first framework for AI coding agents that eliminates hard-coded credentials by integrating deeply with AWS native services. Its approach to secrets management spans specialized skills, IAM guardrails, and runtime retrieval patterns to ensure sensitive data never appears in source code or static configuration files.

AWS Secrets Manager as the Central Store

The toolkit designates AWS Secrets Manager as the default location for all credentials, API keys, and sensitive configuration values. In skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/SKILL.md, the creating-secrets-using-best-practices skill defines a complete workflow for provisioning secrets with dedicated KMS keys and automatic rotation enabled.

Best-Practice Defaults for Secret Creation

According to skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md, the toolkit enforces encryption at rest using customer-managed KMS keys, configures rotation schedules via Lambda functions, and applies lifecycle tags for cost tracking.

aws secretsmanager create-secret \
    --name "my-app/db-credentials" \
    --secret-string '{"username":"admin","password":"<generated>"}' \
    --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:SecretsRotation \
    --rotate-immediately

Runtime Secret Retrieval Patterns

Skills retrieve secret values at execution time using the AWS SDK, ensuring credentials never persist in code repositories. The documentation in skills/specialized-skills/serverless-skills/aws-lambda-microvms/references/snapshots-and-uniqueness.md shows that secrets are fetched from Secrets Manager on each VM resume, preventing snapshot contamination.

import boto3

def get_secret(secret_arn: str) -> str:
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId=secret_arn)
    return response['SecretString']

# Usage in Lambda-managed instances

DB_PASSWORD = get_secret("arn:aws:secretsmanager:us-east-1:123456789012:secret:rds-db-credentials/cluster-ABCDEF")

IAM Policies and Least-Privilege Enforcement

Execution roles attach granular IAM policies that scope permissions to specific secret ARNs. The reference documentation in creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md specifies exact actions: secretsmanager:GetSecretValue, DescribeSecret, and PutSecretValue.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-app/db-credentials*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/<kms-key-id>"
    }
  ]
}

Parameter Store Fallback for Amplify Workflows

For Amplify-generated applications, the toolkit acknowledges that secret() references map to AWS Systems Manager Parameter Store SecureString parameters. The documentation in skills/specialized-skills/web-and-mobile-development/aws-amplify/references/deployment.md advises reviewing /amplify/ parameter path permissions while noting that sandbox secrets set via npx ampx sandbox secret set do not propagate to production environments.

Enforcement and Developer Tooling

The toolkit combines automated policy enforcement with helper utilities to maintain secrets management standards across all skills.

Guardrail Rules Against Hard-Coded Secrets

The rules/aws-agent-rules.md file contains guardrail policies that flag any attempt to embed raw credentials in skill code, forcing agents to adopt the secret-retrieval pattern instead.

Helper Scripts and CLI Workflows

Reusable shell functions in skills/specialized-skills/database-skills/rds-db2/scripts/functions.sh wrap aws secretsmanager get-secret-value for common workflows like DB2 credential injection, abstracting the SDK calls behind simple command-line interfaces.

Summary

• AWS Secrets Manager serves as the central repository for all sensitive values, with mandatory KMS encryption and rotation support.
• Runtime retrieval via the AWS SDK (boto3, @aws-sdk/client-secrets-manager) ensures secrets never appear in source code or snapshots.
• Least-privilege IAM policies restrict access to specific secret ARNs and require KMS decryption permissions.
• Amplify integration maps secrets to Parameter Store SecureString parameters while maintaining environment separation.
• Guardrail rules automatically reject hard-coded credentials, enforcing compliance across the aws/agent-toolkit-for-aws repository.

Frequently Asked Questions

Does the Agent Toolkit for AWS support secret rotation?

Yes. The creating-secrets-using-best-practices skill configures automatic rotation using Lambda functions when provisioning new secrets. The rotation configuration includes immediate rotation on creation and scheduled updates to minimize credential lifespan, as documented in skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md.

Can skills use environment variables instead of Secrets Manager?

No. The toolkit explicitly discourages environment variables for sensitive values. The rules/aws-agent-rules.md guardrails flag hard-coded secrets, and specialized skills like RDS DB2 and Lambda Managed Instances document strict Secrets Manager requirements in their migration patterns.

How does the toolkit handle secrets in local development environments?

For local Amplify development, the toolkit provides npx ampx sandbox secret set to inject secrets into the sandbox environment. However, these values remain isolated and do not propagate to production deployments, preventing accidental credential leakage.

What permissions does a skill need to access secrets?

According to creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md, execution roles require secretsmanager:GetSecretValue and secretsmanager:DescribeSecret actions scoped to the specific secret ARN, plus kms:Decrypt permissions for the associated customer-managed key.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}