Skip to main content
Latest Documentation
This is the latest documentation for the Cloud Posse Reference Architecture. To determine which version you're currently using, please see Version Identification.
Version: Latest
Sponsor @cloudposse

AWS CloudTrail

AWS CloudTrail records API activity across your AWS Organization, providing an audit trail for security analysis, compliance auditing, and operational troubleshooting.

Overview​

AWS CloudTrail provides:

  • API Activity Logging: Records all API calls made in your AWS accounts
  • Organization Trail: Single trail that logs activity from all accounts automatically
  • Log File Validation: Cryptographic signatures to verify log integrity
  • CloudWatch Integration: Real-time analysis and alerting on API activity
  • Centralized Storage: All logs stored in the audit account S3 bucket

Architecture​

Deployment​

CloudTrail uses a simple deployment model - deploy the organization trail once, and it covers all accounts.

Prerequisites​

  • Deploy cloudtrail-bucket component in the audit account
  • Enable cloudtrail.amazonaws.com service access principal in AWS Organizations

Stack Configuration​

# stacks/catalog/cloudtrail.yaml
components:
  terraform:
    cloudtrail:
      vars:
        enabled: true
        cloudtrail_bucket_environment_name: ue1
        cloudtrail_bucket_stage_name: audit
        cloudwatch_logs_retention_in_days: 730
        is_organization_trail: true
        is_multi_region_trail: true
        include_global_service_events: true
        enable_log_file_validation: true
        enable_logging: true

Provisioning​

Deploy the organization trail from the audit account:

atmos terraform apply aws-cloudtrail-s core-gbl-audit

For per-account trails (not recommended for most use cases):

components:
  terraform:
    cloudtrail:
      vars:
        enabled: true
        is_organization_trail: false
        # ... other configuration

Key Variables​

VariableDescriptionDefault
is_organization_trailCreate trail for all accounts in organizationfalse
is_multi_region_trailCreate trail in all regionstrue
include_global_service_eventsInclude global services (IAM, STS)true
enable_log_file_validationEnable log integrity validationtrue
cloudwatch_logs_retention_in_daysLog retention period (CIS recommends 365)365
cloudtrail_bucket_environment_nameEnvironment where bucket is deployed-
cloudtrail_bucket_stage_nameStage where bucket is deployed-

CloudWatch Logs Integration​

CloudTrail can send logs to CloudWatch for real-time analysis:

components:
  terraform:
    cloudtrail:
      vars:
        enabled: true
        cloudwatch_logs_retention_in_days: 730
        cloudwatch_log_group_class: STANDARD

This enables:

  • Real-time metric filters for specific API activities
  • CloudWatch Alarms for security events
  • Integration with SIEM systems

KMS Encryption​

For additional security, enable KMS encryption for CloudTrail logs:

components:
  terraform:
    cloudtrail:
      vars:
        enabled: true
        kms_key_enabled: true
        kms_key_alias: "alias/cloudtrail"

CIS Benchmark Compliance​

CloudTrail configuration supports CIS AWS Foundations Benchmark requirements:

  • CIS 3.1-3.14: CloudWatch Log Metric Filters and Alarms
  • CIS 3.x: Log file validation enabled
  • CIS 3.x: Multi-region trail enabled
  • CIS 3.x: CloudTrail enabled in all regions

See Also​

References​