Skip to content

CloudTrail Trails

Note: This documentation is also available in a rendered format here.

Deploys CloudTrail trails for S3 data events with KMS-encrypted log delivery to an existing audit bucket. Optionally includes management events. Use this module when you need to track who accessed or modified objects in your S3 buckets for security auditing and compliance requirements.

Deployed Resources

This module deploys and integrates the following resources:

CloudTrail Audit Trail - CloudTrail containing S3 Data Events configured to write to an audit bucket.

AuditTrail

  • Audit — Deploy the audit S3 bucket and KMS key that this trail writes to
  • Data Lake — Enable S3 data event logging for data lake bucket access auditing
  • Lake Formation Settings — Configure Lake Formation admin roles whose actions are captured by CloudTrail

Security/Compliance Details

This module is designed in alignment with MDAA security/compliance principles and CDK nag rulesets. Additional review is recommended prior to production deployment, ensuring organization-specific compliance requirements are met.

  • Encryption at Rest:
    • Trail logs encrypted with existing audit KMS key referenced via SSM parameter

Configuration

MDAA Config

Add the following snippet to your mdaa.yaml under the modules: section of a domain/env in order to use this module:

audit-trail: # Module Name can be customized
  module_path: '@aws-mdaa/audit-trail' # Must match module NPM package name
  module_configs:
    - ./audit-trail.yaml # Filename/path can be customized

Module Config Samples and Variants

Copy the contents of the relevant sample config below into the ./audit-trail.yaml file referenced in the MDAA config snippet above.

Minimal Configuration

Required properties only — a CloudTrail trail with audit bucket and KMS key references. Start here for a basic S3 data event trail writing to an existing audit bucket.

sample-config-minimal.yaml

# Contents available via above link
# Minimal Audit Trail module configuration.
# Contains only required properties for a CloudTrail trail.

trail:
  # S3 bucket name where CloudTrail audit logs are stored
  cloudTrailAuditBucketName: ssm:/sample-org/shared/audit/bucket/name
  # KMS key ARN for encrypting CloudTrail logs written to S3
  cloudTrailAuditKmsKeyArn: ssm:/sample-org/shared/audit/kms/cmk/arn

Comprehensive Configuration

Covers all available options including management events, scoped event selectors targeting specific buckets and prefixes, and multiple named trails via the trails property. Demonstrates both the legacy single trail and additional named trails coexisting in one config.

sample-config-comprehensive.yaml

# Contents available via above link
# Comprehensive sample config for the Audit Trail module.
# Covers EVERY non-excluded property from config-schema.json at full depth.
# Deploys multiple CloudTrail trails: one via the legacy 'trail' property and
# additional named trails via 'trails'. Both can coexist in the same config.

# Legacy single-trail configuration (backward-compatible).
# Produces a trail named '{org}-{env}-{domain}-{module}-s3-audit'.
trail:
  # (Required) S3 bucket name where CloudTrail audit logs are stored.
  # Accepts bucket names or SSM parameter references.
  cloudTrailAuditBucketName: ssm:/sample-org/shared/audit/bucket/name
  # (Required) KMS key ARN for encrypting CloudTrail logs written to S3.
  # Accepts key ARNs or SSM parameter references.
  # Direct ARN example: arn:{{partition}}:kms:{{region}}:{{account}}:key/audit-key-id
  cloudTrailAuditKmsKeyArn: ssm:/sample-org/shared/audit/kms/cmk/arn
  # (Optional, boolean) If true, management/control plane events will be
  # included in trail. Otherwise, only S3 Data Events will be included.
  includeManagementEvents: true
  # (Optional) Scoped S3 event selectors. If omitted, all S3 data events
  # in the account are captured. Each entry targets a specific bucket and
  # optional key prefix.
  eventSelectors:
    # Selector targeting a specific bucket and prefix
    - bucketName: ssm:/sample-org/datalake/raw-bucket/name
      # (Optional) S3 key prefix to narrow event capture
      objectPrefix: sensitive-data/
    # Selector targeting an entire bucket (no prefix)
    - bucketName: ssm:/sample-org/datalake/curated-bucket/name

# Named trail configurations for deploying multiple independent trails.
# Each key becomes the trail's resource name segment
# (e.g., '{org}-{env}-{domain}-{module}-analytics-audit').
trails:
  # Trail scoped to analytics workloads
  analytics-audit:
    cloudTrailAuditBucketName: ssm:/sample-org/analytics/audit/bucket/name
    cloudTrailAuditKmsKeyArn: ssm:/sample-org/analytics/audit/kms/cmk/arn
    includeManagementEvents: false
    eventSelectors:
      - bucketName: ssm:/sample-org/analytics/reports-bucket/name
        objectPrefix: daily/

Trails Only

Uses only the trails property without the legacy trail — for deployments that exclusively use named trails without needing the default s3-audit trail.

sample-config-trails-only.yaml

# Contents available via above link
# Trails-only sample config for the Audit Trail module.
# Demonstrates using only the 'trails' property without the legacy 'trail' property.
# Use this pattern when deploying multiple named trails without a default 's3-audit' trail.

trails:
  # Trail scoped to datalake buckets
  datalake-audit:
    # (Required) S3 bucket name where CloudTrail audit logs are stored.
    cloudTrailAuditBucketName: ssm:/sample-org/shared/audit/bucket/name
    # (Required) KMS key ARN for encrypting CloudTrail logs written to S3.
    cloudTrailAuditKmsKeyArn: ssm:/sample-org/shared/audit/kms/cmk/arn
    includeManagementEvents: false
    eventSelectors:
      - bucketName: ssm:/sample-org/datalake/raw-bucket/name
        objectPrefix: sensitive-data/

Config Schema Docs