CloudTrail

AWS CloudTrail records every API call made in an AWS account: who called what, when, from where, and whether it succeeded. The platform runs one organization trail that covers every account and delivers to a bucket no workload account can alter.

What it does

Almost everything in AWS is an API call, including clicks in the console. CloudTrail writes each call as an event. Management events are control-plane actions such as creating a role or changing a bucket policy. Data events are high-volume object-level actions such as reading an S3 object. A trail is the configuration that delivers events to an S3 bucket and, optionally, to a CloudWatch log group. An organization trail is created in the management account and automatically covers every member account, including accounts created later. Log file validation writes signed digest files so that any change to a delivered log can be detected.

How BuiltForProd uses it

The cloudtrail unit (definition units/cloudtrail, module modules/cloudtrail, listed by the core/root/us-west-2 stack file) creates one organization trail:

• Multi-region, so every region's activity is captured.
• Management events, read and write, for all accounts.
• S3 data events for the audit bucket itself, so reads of the evidence are recorded.
• Log file validation on.
• Encrypted with the audit log KMS key from modules/audit-log-bucket.
• Delivered to acme-usw2-audit-logs in core-audit and to a CloudWatch log group with 365-day retention.

Three layers keep the trail honest. The acme-audit-protection SCP denies StopLogging, DeleteTrail and UpdateTrail to everyone except the root user. The audit bucket is versioned and its current objects are never deleted. Log file validation makes tampering with delivered files detectable.

The CloudWatch log group is what makes near-real-time alerting possible. The cis-metric-filters unit in core-root creates seven metric filters on it, one per CIS control: root account usage, unauthorized API calls, console sign-in failures, IAM policy changes, CloudTrail configuration changes, S3 bucket policy changes and VPC changes. The metrics are shared to core-security through CloudWatch OAM, where the cis-alarms unit evaluates them and notifies the security alerts SNS topic.

GuardDuty also reads CloudTrail: management events are one of the data sources its detector analyzes. The SecurityAuditorAccess permission set may look up events and describe the trail, so auditors can verify coverage without management-account access.

Terms you will see

Term	Meaning
Event	One recorded API call with its identity, time, source IP and parameters.
Management event	A control-plane call; recorded for every account.
Data event	An object-level call; recorded here only for the audit bucket.
Organization trail	A trail in the management account that covers all member accounts.
Log file validation	Signed digests that prove delivered logs have not been changed.
Metric filter	A pattern applied to a log group that turns matching events into a metric.
LookupEvents	The API that searches the last 90 days of events without opening the bucket.

Where to read more

• AWS Baseline overview for the audit account in context.
• S3 for the audit bucket's encryption and lifecycle.
• CloudWatch for the metric filters and alarms built on the trail.