SecretsManagerBuilder

Purpose

The SecretsManagerBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create AWS Secrets Manager secrets following organizational security standards. This builder supports both database secrets with auto-generated passwords and standard application secrets with custom key-value pairs. It automatically integrates with Parameter Store for cross-stack references and handles cross-account sharing for DevOps access.

Dependencies

This builder requires the following AWS resources to be available, typically provided by MARE-foundations:

Required Foundation Resources

• Cross-Account Setup: DevOps account configuration for shareable secrets
• Environment Configuration: Account mappings for all environments
• Naming Standards: Organizational resource naming conventions
• SNC KMS Keys: Organizational KMS keys for Sensitive Non Classified (SNC) data encryption (when use_snc_key is true)

AWS Permissions Required

• Secrets Manager: Secret creation and management
• Parameter Store: Write access for storing secret references
• Resource Access Manager (RAM): Cross-account resource sharing (when is_shareable is true)
• Resource Tagging: Permissions to apply organizational tags
• KMS: Key usage permissions for Sensitive Non Classified (SNC) encryption (when use_snc_key is true)

Configuration

The builder uses the SecretConfig model for the validation of your configuration and becomes the authoritative source of all secret settings.

CDK Configuration Structure

The builder's configuration values should be sourced from the cdk.json file. The expected structure is as follows:

{
  "secret_name_1": {
    "is_db_secret": true,
    "is_shareable": false,
    "secret_data": {
      "db_username": "admin",
      "db_app_username": "app_user",
      "schema": "app_schema"
    }
  },
  "secret_name_2": {
    "is_db_secret": false,
    "is_shareable": false,
    "use_snc_key": true,
    "secret_data": {
      "username": "service_user",
      "password": "GENERATE_PASSWORD",
      "endpoint": "https://api.example.com"
    }
  }
}

Configuration Parameters

Parameter	Mandatory	Type	Default	Description
	Yes	str		The configuration key that becomes the secret base name
is_db_secret	No	bool		Whether this is a database secret requiring specific validation
secret_data	No	bool		Key-value pairs for the secret content
is_shareable	No	bool	false	Enable cross-account sharing with DevOps account
use_snc_key	No	bool	false	Enable SNC (Sensitive Non Classified) customer-managed KMS key encryption
snc_key_from_foundation	No	bool	false	Use foundation-provided SNC key instead of project-specific key

Database Secret Requirements

When is_db_secret is true, the secret_data must contain:

• Required: db_username - Primary database username
• Optional: db_app_username - Application-specific database user
• Optional: db_app_user_is_iam_role - Specifies if the application-specific database user is to be mapped to IAM authentication
• Optional: schema - Application-specific database schema

If db_app_username is specified, a password will be automatically generated only if db_app_user_is_iam_role is false.

Password Generation

Use GENERATE_PASSWORD as a value to auto-generate secure passwords:

• Database secrets: Passwords auto-generated with character exclusions for compatibility
• Standard secrets: 20-character passwords generated for marked fields

SNC Key Configuration

The SNC (Sensitive Non Classified) key functionality provides enhanced encryption control for sensitive data:

• use_snc_key: When true, uses a customer-managed KMS key instead of AWS-managed encryption
• snc_key_from_foundation: When true (requires use_snc_key to be true), uses the foundation-provided key instead of a project-specific key

SNC Key Naming Convention:

• Project-specific: alias/{domain}-{project}-{environment}-secret-snc-key
• Foundation-provided: alias/{domain}-foundation-{project}-{environment}-secret-snc-key

Usage

Here’s an example of how to use the SecretsManagerBuilder to build a secret in a CDK stack:

secret_config = app_helper.get_from_env("secret_name")

secrets_builder = SecretsManagerBuilder()
secret = secrets_builder.set_application_helper(app_helper) \
                        .set_builder_config(secret_config) \
                        .set_secret_base_name("secret_name") \
                        .build(scope_from_stack)

Behaviour and Features

Automatic Secret Structure

Database Secrets (is_db_secret: true):

• Always includes username and auto-generated password
• Optionally includes db_app_username and db_app_user_password
• Uses SecretStringGenerator for AWS-managed password rotation compatibility
• Excludes problematic characters: "@/

Standard Secrets (is_db_secret: false):

• Contains exactly the key-value pairs from secret_data
• Supports mixed content (some generated, some static)
• Uses 20-character generated passwords for GENERATE_PASSWORD values

Naming Convention

Secret names follow the pattern: {secret_base_name}-secret

The builder automatically:

• Converts base names to lowercase
• Truncates names to respect AWS limits
• Applies organizational naming standards

Parameter Store Integration

Each secret automatically creates two Parameter Store entries:

• Secret Name: SECRET_{SECRET_BASE_NAME_UPPER}
• Secret ARN: SECRET_ARN_{SECRET_BASE_NAME_UPPER}

Cross-Account Sharing

When is_shareable is true:

• Secret ARN parameter uses Advanced tier for cross-account access
• Automatically shares parameter with DevOps account via RAM
• Creates resource share named: rds-ram-{environment}
• Standard secrets use Standard tier (no sharing)

Encryption Options

The builder supports two encryption modes:

AWS-Managed Encryption (default)

• Uses AWS-managed keys for Secrets Manager
• No additional KMS permissions required
• Suitable for most use cases

SNC Customer-Managed Encryption

When use_snc_key is true:

• Uses organizational customer-managed KMS keys for Sensitive Non Classified data
• Provides enhanced encryption control and audit capabilities for sensitive information
• Requires proper KMS key permissions
• Supports both project-specific and foundation-provided keys

Security Features

All secrets are created with security best practices:

• Removal Policy: Set to DESTROY for development environments
• Encryption: Uses AWS-managed keys for Secrets Manager
• Access Control: Follows least-privilege principles
• Rotation Ready: Database secrets compatible with RDS rotation

Notes

• The set_usage method from the abstract class should not be used in this builder.
• The secret_name parameter of the set_secret_base_name method should be extracted from the cdk.json config key.
• Database secrets must include db_username in secret_data
• Cross-account sharing requires DevOps account configuration in environment settings
• When using SNC keys, ensure the appropriate KMS key exists and proper permissions are granted
• snc_key_from_foundation can only be true when use_snc_key is also true
• SNC (Sensitive Non Classified) encryption should be used for sensitive data requiring enhanced security controls