SEC02-BP03 - Store and use secrets securely

Implementation guidance

Secrets such as API keys, database passwords, and other credentials need to be stored securely and accessed only by authorized identities. Using a specialized service for secret management helps you protect sensitive information, implement automatic rotation, and maintain an audit trail of secret usage.

Key steps for implementing this best practice:

1. Identify and inventory all secrets:

   • Document all secrets used in your environment
   • Identify where secrets are currently stored
   • Classify secrets based on sensitivity and usage
   • Determine which secrets need to be migrated to a secure storage solution
   • Identify secrets that can be replaced with temporary credentials

2. Implement a secure secrets management solution:

   • Use AWS Secrets Manager for storing and managing secrets
   • Configure AWS Systems Manager Parameter Store for less sensitive configuration data
   • Implement appropriate encryption for all stored secrets
   • Set up appropriate access controls and permissions
   • Enable detailed logging and monitoring

3. Implement automatic secret rotation:

   • Configure automatic rotation for database credentials
   • Set up rotation for API keys and other application secrets
   • Implement custom rotation functions for specialized secrets
   • Test rotation procedures to ensure application continuity
   • Monitor rotation events and failures

4. Secure secret retrieval and usage:

   • Use IAM roles to control access to secrets
   • Implement the principle of least privilege for secret access
   • Use VPC endpoints to access secrets without traversing the internet
   • Cache secrets appropriately to minimize retrieval calls
   • Implement secure coding practices for handling secrets in applications

5. Monitor and audit secret access:

   • Enable AWS CloudTrail logging for secret access
   • Set up alerts for unusual access patterns
   • Regularly review access logs
   • Implement detective controls to identify unauthorized access
   • Conduct periodic access reviews

6. Eliminate hardcoded secrets:

   • Scan code repositories for hardcoded secrets
   • Implement pre-commit hooks to prevent committing secrets
   • Use tools like git-secrets or Amazon CodeGuru to detect secrets in code
   • Educate developers on secure secret handling
   • Implement CI/CD pipeline checks for secrets

7. Enable GitHub Secret Scanning:

   • Enable secret scanning to detect secrets in your repository
   • Set up push protection to block commits containing secrets
   • Review and remediate detected secrets

GitHub Push Protection - Repository Level Setup

Note: Push protection is only available for repositories owned by organizations using GitHub Team or GitHub Enterprise Cloud.

GitHub push protection blocks contributors from pushing secrets to a repository and generates an alert whenever a contributor bypasses the block.

Steps to enable push protection at repository level:

1. On GitHub, navigate to the main page of the repository

2. Under your repository name, click “Settings”

3. In the “Security” section of the sidebar, click “Advanced Security”

4. If you have not already enabled Secret Protection, to the right of “Secret Protection”, click “Enable”

5. In the “Secret Protection” section, to the right of “Push protection”, click “Enable”

Best practices:

• Enable push protection to prevent secrets from entering the repository
• Educate developers on how to respond when pushes are blocked
• Regularly review secret scanning alerts
• Revoke compromised secrets immediately

Implementation examples

Example 1: Storing and retrieving a secret with AWS Secrets Manager

# Store a new secret
aws secretsmanager create-secret \
  --name "prod/app/database-credentials" \
  --description "Database credentials for production application" \
  --secret-string '{"username":"admin","password":"t0p-S3cr3t!"}'

# Retrieve a secret
aws secretsmanager get-secret-value \
  --secret-id "prod/app/database-credentials"

Example 2: Setting up automatic rotation for database credentials

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue",
        "secretsmanager:UpdateSecretVersionStage"
      ],
      "Resource": "arn:aws:secretsmanager:region:account-id:secret:prod/app/database-credentials-*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances"
      ],
      "Resource": "*"
    }
  ]
}

# Enable rotation with a Lambda function
aws secretsmanager rotate-secret \
  --secret-id "prod/app/database-credentials" \
  --rotation-lambda-arn "arn:aws:lambda:region:account-id:function:SecretsManagerRotationFunction" \
  --rotation-rules '{"AutomaticallyAfterDays": 30}'

Example 3: Using AWS Secrets Manager with AWS SDK in an application

import boto3
import json
from botocore.exceptions import ClientError

def get_secret(secret_name):
    """
    Retrieve a secret from AWS Secrets Manager
    """
    # Create a Secrets Manager client
    session = boto3.session.Session()
    client = session.client(
        service_name='secretsmanager',
        region_name='us-west-2'
    )

    try:
        get_secret_value_response = client.get_secret_value(
            SecretId=secret_name
        )
    except ClientError as e:
        # Handle exceptions
        raise e
    else:
        # Decrypts secret using the associated KMS key
        if 'SecretString' in get_secret_value_response:
            secret = get_secret_value_response['SecretString']
            return json.loads(secret)
        else:
            # Binary secrets
            return get_secret_value_response['SecretBinary']

# Example usage
try:
    db_credentials = get_secret("prod/app/database-credentials")
    username = db_credentials['username']
    password = db_credentials['password']
    # Use the credentials to connect to the database
except Exception as e:
    # Handle error
    print(f"Error retrieving secret: {e}")

AWS services to consider

Benefits of storing and using secrets securely

• Enhanced security: Centralized management of secrets with encryption at rest and in transit
• Reduced risk of exposure: Elimination of hardcoded secrets in application code and configuration files
• Simplified secret rotation: Automatic rotation of secrets without application downtime
• Improved auditability: Detailed logs of secret access and usage
• Centralized control: Manage all secrets from a single service
• Fine-grained access control: Control who can access which secrets
• Compliance support: Meet regulatory requirements for secure credential management

Related resources