CloudTrail & Auditing

CloudTrail Fundamentals

AWS CloudTrail logs API calls made on your account for auditing and compliance.

Create Trail

# Create a trail
aws cloudtrail create-trail \
  --name my-audit-trail \
  --s3-bucket-name my-cloudtrail-logs \
  --is-multi-region-trail \
  --enable-log-file-validation

# Start logging
aws cloudtrail start-logging --name my-audit-trail

# Describe trail
aws cloudtrail describe-trails

# Stop logging
aws cloudtrail stop-logging --name my-audit-trail

Log File Integrity Validation

# Enable log file validation
aws cloudtrail update-trail \
  --name my-audit-trail \
  --enable-log-file-validation

# Verify log file integrity
aws cloudtrail validate-logs \
  --trail-arn arn:aws:cloudtrail:us-east-1:xxx:trail/my-audit-trail \
  --start-time 2024-01-15T00:00:00Z

CloudTrail Event Types

CloudTrail Configuration

Multi-Region Trail

# Create multi-region trail
aws cloudtrail create-trail \
  --name my-multi-region-trail \
  --s3-bucket-name my-logs-bucket \
  --is-multi-region-trail

# This logs events from ALL regions
# Single-region trail only logs from one region

Data Events

# Log S3 data events
aws cloudtrail put-event-selectors \
  --trail-name my-trail \
  --event-selectors '[{
    "ReadWriteType": "All",
    "IncludeManagementEvents": true,
    "DataResources": [{
      "Type": "AWS::S3::Object",
      "Values": ["arn:aws:s3:::my-bucket/"]
    }]
  }]'

# Log Lambda data events
aws cloudtrail put-event-selectors \
  --trail-name my-trail \
  --event-selectors '[{
    "ReadWriteType": "All",
    "IncludeManagementEvents": true,
    "DataResources": [{
      "Type": "AWS::Lambda::Function",
      "Values": ["arn:aws:lambda:us-east-1:xxx:function:my-function"]
    }]
  }]'

# Log DynamoDB data events
aws cloudtrail put-event-selectors \
  --trail-name my-trail \
  --event-selectors '[{
    "DataResources": [{
      "Type": "AWS::DynamoDB::Table",
      "Values": ["arn:aws:dynamodb:us-east-1:xxx:table/my-table"]
    }]
  }]'

Log Storage in S3

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AWSCloudTrailAclCheck",
    "Effect": "Allow",
    "Principal": {"Service": "cloudtrail.amazonaws.com"},
    "Action": "s3:GetBucketAcl",
    "Resource": "arn:aws:s3:::my-cloudtrail-logs"
  }, {
    "Sid": "AWSCloudTrailWrite",
    "Effect": "Allow",
    "Principal": {"Service": "cloudtrail.amazonaws.com"},
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::my-cloudtrail-logs/AWSLogs/123456789012/*",
    "Condition": {"StringEquals": {"s3:x-amz-acl": "bucket-owner-full-control"}}
  }]
}

CloudTrail Insights

Detect unusual API activity patterns.

Enable Insights

# Enable Insights on a trail
aws cloudtrail update-trail \
  --name my-trail \
  --cloud-watch-logs-log-group-arn arn:aws:logs:us-east-1:xxx:log-group:CloudTrail \
  --cloud-watch-logs-role-arn arn:aws:iam::xxx:role/CloudTrailRole

# CloudTrail Insights automatically detects:
# - Unusual API call rates
# - Unusual error rates
# - Unusual API patterns

Query Insights Events

# List Insights events
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=InsightsEvent

# Check Insights in CloudWatch
aws logs filter-log-events \
  --log-group-name CloudTrail \
  --filter-pattern '{ $.eventType = "AwsCloudTrailInsightEvent" }'

CloudWatch Logs Integration

# Send CloudTrail to CloudWatch Logs
aws cloudtrail update-trail \
  --name my-trail \
  --cloud-watch-logs-log-group-arn arn:aws:logs:us-east-1:xxx:log-group:CloudTrail \
  --cloud-watch-logs-role-arn arn:aws:iam::xxx:role/CloudTrailRole

# Create metric filter for failed logins
aws logs put-metric-filter \
  --log-group-name CloudTrail \
  --filter-name failed-logins \
  --filter-pattern '{ $.errorCode = "*UnauthorizedAccess*" }' \
  --metric-transformations 'metricName=UnauthorizedAccess,metricNamespace=Security,metricValue=1'

Querying CloudTrail with Athena

Setup Athena Table

CREATE EXTERNAL TABLE cloudtrail_logs (
  eventVersion STRING,
  userIdentity STRUCT<
    type: STRING,
    principalId: STRING,
    arn: STRING,
    accountId: STRING,
    userName: STRING>,
  eventTime STRING,
  eventSource STRING,
  eventName STRING,
  awsRegion STRING,
  sourceIPAddress STRING,
  userAgent STRING,
  errorCode STRING,
  errorMessage STRING,
  requestParameters STRING,
  responseElements STRING,
  additionalEventData STRING,
  requestId STRING,
  eventId STRING,
  resources ARRAY<STRUCT<
    arn: STRING,
    accountId: STRING,
    type: STRING>>,
  eventType STRING,
  apiVersion STRING,
  readOnly STRING,
  recipientAccountId STRING,
  serviceEventDetails STRING,
  sharedEventId STRING,
  vpcEndpointId STRING
)
PARTITIONED BY (region STRING, year STRING, month STRING, day STRING)
ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe'
LOCATION 's3://my-cloudtrail-logs/AWSLogs/123456789012/CloudTrail/';

Common Queries

-- Find failed console logins
SELECT eventTime, userIdentity.userName, sourceIPAddress, errorCode
FROM cloudtrail_logs
WHERE eventName = 'ConsoleLogin'
  AND errorCode IS NOT NULL
  AND year = '2024' AND month = '01'
ORDER BY eventTime DESC;

-- Find API calls from unknown IPs
SELECT sourceIPAddress, eventName, eventTime
FROM cloudtrail_logs
WHERE sourceIPAddress NOT IN ('203.0.113.0/24', '198.51.100.0/24')
  AND eventSource = 'ec2.amazonaws.com'
  AND year = '2024' AND month = '01';

-- Find who modified security groups
SELECT userIdentity.arn, eventTime, requestParameters
FROM cloudtrail_logs
WHERE eventName = 'AuthorizeSecurityGroupIngress'
  AND year = '2024' AND month = '01';

CloudTrail Best Practices

Security and Compliance

1. Enable multi-region trails to log all regions
2. Enable log file validation for integrity
3. Store logs in a centralized S3 bucket
4. Enable CloudWatch Logs integration for monitoring
5. Use Organizations trail for all accounts
6. Enable Insights for anomaly detection

Organization Trail

# Create trail for entire organization
aws cloudtrail create-trail \
  --name org-audit-trail \
  --s3-bucket-name my-org-logs \
  --is-multi-region-trail \
  --is-organization-trail

S3 Bucket Security

# Enable MFA Delete on log bucket
aws s3api put-bucket-versioning \
  --bucket my-cloudtrail-logs \
  --mfa-delete Enabled

# Enable Object Lock for compliance
aws s3api put-object-lock-configuration \
  --bucket my-cloudtrail-logs \
  --object-lock-configuration '{
    "ObjectLockEnabled": "Enabled",
    "Rule": {
      "DefaultRetention": {
        "Mode": "COMPLIANCE",
        "Years": 7
      }
    }
  }'

Cost Optimization