CloudTrail

# ===== What it is =====
# Records every API call in your AWS account (console, CLI, SDK, internal services).
# Stores in S3 + optionally streams to CloudWatch Logs + EventBridge.
# Mandatory for compliance (PCI, ISO 27001, SOC 2, HIPAA).

# ===== Event types =====
# Management events: control-plane actions (CreateBucket, IAM changes, RunInstances)
# Data events:       data-plane actions (S3 GetObject, Lambda Invoke, DynamoDB queries)
# Insight events:    anomaly detection on management events

# Default: management events ON. Data events OFF (cost / volume).

# ===== Create a trail (best-practice baseline) =====
aws cloudtrail create-trail \
  --name organization-trail \
  --s3-bucket-name acme-cloudtrail-logs \
  --is-multi-region-trail \
  --is-organization-trail \
  --enable-log-file-validation

aws cloudtrail start-logging --name organization-trail

# Multi-region + organisation trail captures EVERY account + region in one place.
# Log file validation: SHA-256 signed manifests detect tampering.

# ===== Stream to CloudWatch Logs =====
aws cloudtrail update-trail \
  --name organization-trail \
  --cloud-watch-logs-log-group-arn arn:aws:logs:ap-southeast-2:123:log-group:cloudtrail \
  --cloud-watch-logs-role-arn arn:aws:iam::123:role/CloudTrail-CloudWatch

# Enables real-time alerting via CloudWatch Logs Insights + metric filters.

# ===== Query with Athena =====
# CloudTrail logs are gzipped JSON in S3. Athena can query directly:
CREATE EXTERNAL TABLE cloudtrail_logs (
  eventVersion STRING,
  userIdentity STRUCT<type:STRING, principalId:STRING, arn:STRING, ...>,
  eventTime STRING,
  eventSource STRING,
  eventName STRING,
  ...
)
ROW FORMAT SERDE 'com.amazon.emr.hive.serde.CloudTrailSerde'
STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat'
OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION 's3://acme-cloudtrail-logs/AWSLogs/123/CloudTrail/';

SELECT eventTime, userIdentity.arn, eventName
FROM cloudtrail_logs
WHERE eventTime > '2024-04-10T00:00:00Z'
  AND eventName = 'ConsoleLogin'
ORDER BY eventTime DESC
LIMIT 100;

# ===== Common detection queries =====
# Root account usage:
WHERE userIdentity.type = 'Root'

# IAM policy changes:
WHERE eventName IN ('AttachUserPolicy', 'PutUserPolicy', 'CreatePolicy', 'CreateRole')

# Failed console logins:
WHERE eventName = 'ConsoleLogin' AND responseElements.ConsoleLogin = 'Failure'

# S3 bucket policy changes:
WHERE eventName IN ('PutBucketPolicy', 'DeleteBucketPolicy', 'PutBucketAcl')

# Disabled MFA:
WHERE eventName = 'DeactivateMFADevice'

# ===== Alerting (real-time) =====
# CloudWatch Logs metric filter:
{
  $.eventName = "ConsoleLogin" &&
  $.userIdentity.type = "Root" &&
  $.responseElements.ConsoleLogin = "Success"
}
# -> SNS topic -> Email / PagerDuty / Slack

# Or EventBridge rule:
{
  "detail-type": ["AWS API Call via CloudTrail"],
  "detail": {
    "eventName": ["DeleteBucket", "PutBucketPolicy"]
  }
}

# ===== Storage + retention =====
# - S3 lifecycle: keep 1 year hot, then archive to Glacier
# - Compliance: typically 7 years retention
# - Object Lock + KMS encryption + cross-region replication

# ===== Patterns =====
# - Multi-region + organisation trail in a SEPARATE management account
# - Log file validation enabled
# - Stream to CloudWatch + Athena
# - Alerts on root usage, IAM changes, security group changes
# - S3 bucket policy denies deletes / modifications

# ===== Pitfalls =====
# - Trail in same account as workloads (compromised account can disable)
# - Data events too aggressive -> enormous bill
# - No alerting -> 'we have logs but never read them'
# - S3 bucket allowing public read of CloudTrail data

# Audit log — every API call recorded.
# Turn on org-wide trail to S3.