AWS CloudTrail Configuration

10 min read Beginner

CloudTrail records API activity across an AWS account, providing audit trails for security analysis, compliance, and operational troubleshooting. This guide covers trail configuration, log validation, encryption, and integration with monitoring services.

Quick Start

Create a multi-region trail with default settings:

bash 
aws cloudtrail create-trail \
  --name organization-trail \
  --s3-bucket-name my-cloudtrail-logs \
  --is-multi-region-trail \
  --include-global-service-events \
  --enable-log-file-validation

# Start logging
aws cloudtrail start-logging --name organization-trail

CloudTrail begins recording API activity immediately. An S3 bucket with appropriate permissions is required before creating the trail. See the AWS CloudTrail documentation for complete setup details.

Trail Types

CloudTrail supports different trail configurations:

Trail Type Scope Use Case
Single-Region Trail One region Region-specific compliance requirements
Multi-Region Trail All regions Comprehensive audit logging (recommended)
Organization Trail All accounts in organization Centralized logging for AWS Organizations
Recommendation: Multi-region trails capture API activity from all regions, including regions without active workloads. Attackers often operate in unused regions to avoid detection.

Configuration Options

Standard Multi-Region Trail

Recommended configuration for single-account environments:

hcl 
resource "aws_cloudtrail" "main" {
  name           = "organization-trail"
  s3_bucket_name = aws_s3_bucket.cloudtrail_logs.id

  is_multi_region_trail         = true
  include_global_service_events = true
  enable_log_file_validation    = true

  kms_key_id = aws_kms_key.cloudtrail.arn

  cloud_watch_logs_group_arn = "${aws_cloudwatch_log_group.cloudtrail.arn}:*"
  cloud_watch_logs_role_arn  = aws_iam_role.cloudtrail_cloudwatch.arn

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

Organization Trail

Centralized logging for AWS Organizations:

hcl 
resource "aws_cloudtrail" "organization" {
  name           = "organization-trail"
  s3_bucket_name = aws_s3_bucket.cloudtrail_logs.id

  is_organization_trail         = true
  is_multi_region_trail         = true
  include_global_service_events = true
  enable_log_file_validation    = true

  kms_key_id = aws_kms_key.cloudtrail.arn

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

Key Configuration Options

Option Description Recommendation
is_multi_region_trail Record events from all regions Enable (required for CIS compliance)
include_global_service_events Include IAM, STS, CloudFront events Enable
enable_log_file_validation Create digest files for integrity verification Enable (required for CIS compliance)
is_organization_trail Apply trail to all organization accounts Enable for multi-account environments

Event Types

CloudTrail captures different categories of events:

Management Events Control plane operations (create, delete, modify resources)
Data Events Data plane operations (S3 object access, Lambda invocations)
Insights Events Unusual API activity patterns detected by CloudTrail Insights

Data Event Configuration

Data events require explicit configuration and incur additional costs:

hcl 
resource "aws_cloudtrail" "main" {
  # ... base configuration ...

  event_selector {
    read_write_type           = "All"
    include_management_events = true

    data_resource {
      type   = "AWS::S3::Object"
      values = ["arn:aws:s3:::sensitive-bucket/"]
    }
  }

  event_selector {
    read_write_type           = "All"
    include_management_events = true

    data_resource {
      type   = "AWS::Lambda::Function"
      values = ["arn:aws:lambda"]
    }
  }
}
Cost Impact: Data events generate high volumes of log entries. Enable selectively for sensitive resources only. S3 data events for high-traffic buckets can significantly increase costs.

Log File Validation

Log file validation ensures log integrity through digest files:

  • Digest files: Created hourly with SHA-256 hashes of log files
  • Chain of custody: Each digest references the previous digest
  • Tamper detection: Validates logs have not been modified or deleted
bash 
# Validate log file integrity
aws cloudtrail validate-logs \
  --trail-arn arn:aws:cloudtrail:us-east-1:123456789012:trail/organization-trail \
  --start-time 2024-01-01T00:00:00Z \
  --end-time 2024-01-31T23:59:59Z
Compliance Requirement: CIS AWS Foundations Benchmark requires log file validation to be enabled (CIS 2.2). This ensures audit logs maintain evidentiary integrity.

Encryption

CloudTrail supports encryption with AWS KMS:

Encryption Type Description Use Case
SSE-S3 S3-managed keys (default) Basic encryption requirements
SSE-KMS Customer-managed KMS keys Compliance requirements, key rotation control

KMS Key Policy Requirements

The KMS key policy must grant CloudTrail permission to encrypt logs:

  • kms:GenerateDataKey* - Generate data keys for encryption
  • kms:Decrypt - Decrypt logs when accessed
  • kms:DescribeKey - Describe key metadata
Compliance Requirement: CIS AWS Foundations Benchmark requires CloudTrail logs to be encrypted with KMS (CIS 2.7). Enable key rotation for additional security.

CloudWatch Integration

Stream CloudTrail logs to CloudWatch Logs for real-time monitoring:

Metric Filters Create CloudWatch metrics from log patterns
CloudWatch Alarms Alert on security-relevant API activity
Log Insights Query and analyze API activity patterns

Common Metric Filters

Event Filter Pattern
Root account usage {$.userIdentity.type = "Root"}
Console login without MFA {$.eventName = "ConsoleLogin" && $.additionalEventData.MFAUsed != "Yes"}
IAM policy changes {$.eventName = "Put*Policy" || $.eventName = "Delete*Policy"}
Security group changes {$.eventName = "AuthorizeSecurityGroup*" || $.eventName = "RevokeSecurityGroup*"}
Network ACL changes {$.eventName = "*NetworkAcl*"}
Compliance Requirement: CIS AWS Foundations Benchmark requires CloudWatch log integration (CIS 2.4) and specific metric filters for security monitoring (CIS 3.x controls).

Multi-Account Setup

For AWS Organizations, create an organization trail in the management account:

bash 
# Create organization trail (from management account)
aws cloudtrail create-trail \
  --name organization-trail \
  --s3-bucket-name central-cloudtrail-logs \
  --is-organization-trail \
  --is-multi-region-trail

Recommended Architecture

  • Management Account: Creates and manages the organization trail
  • Log Archive Account: Hosts the S3 bucket for centralized log storage
  • Member Accounts: Automatically included in organization trail logging
S3 Bucket Policy: The log archive bucket requires a policy allowing CloudTrail from all organization accounts to write logs. Use organization ID conditions for security.

Cost Considerations

CloudTrail pricing components:

Component Pricing Notes
First management trail Free One free copy of management events per region
Additional management trails $2.00 per 100,000 events Additional copies of management events
Data events $0.10 per 100,000 events S3 object, Lambda invocation logging
CloudTrail Insights $0.35 per 100,000 events analyzed Anomaly detection
S3 storage Standard S3 pricing Log storage and retrieval costs
Cost Optimization: The first management trail per region is free. Use one multi-region organization trail instead of separate trails per account. Enable data events selectively for sensitive resources only.

Integration Points

CloudTrail provides foundational logging for other AWS security services:

GuardDuty Analyzes CloudTrail events for threat detection
Security Hub Uses CloudTrail for CIS compliance checks and audit trail verification
AWS Config Logs Config API calls and provides context for configuration changes
EventBridge Routes CloudTrail events to targets for real-time processing and alerting
Architecture Pattern: CloudTrail provides the audit foundation. GuardDuty analyzes CloudTrail for threats. Security Hub validates CloudTrail configuration for compliance. EventBridge routes CloudTrail events for real-time alerting via SNS.

Next Steps

  1. Enable GuardDuty to analyze CloudTrail events for threats
  2. Configure Security Hub CIS standards requiring CloudTrail
  3. Set up CloudWatch metric filters for security-relevant events
  4. Configure EventBridge rules for real-time alerting