How AWS CloudTrail Logs Capture API Executions

Introduction

Every action in AWS — creating an EC2 instance, assuming an IAM role, deleting an S3 object — is an API call. AWS CloudTrail captures a record of every one of these API calls across your entire AWS account and delivers them as structured JSON log files to an S3 bucket. This provides a complete, tamper-evident audit trail: who did what, from where, and when. CloudTrail is foundational for compliance frameworks like SOC 2, PCI DSS, and HIPAA, and is the primary data source for AWS security analytics tools like GuardDuty and Security Hub.

Step-by-Step: How CloudTrail Captures and Delivers Events

flowchart TD
    A["1. API Call Interception"]
    B["2. Event Types"]
    C["3. Event Structure"]
    D["4. S3 Delivery and Integrity"]
    E["5. Querying with Athena"]
    A --> B
    B --> C
    C --> D
    D --> E

Step 1: API Call Interception

When any AWS principal (user, role, service) makes an API call, the AWS control plane intercepts it before execution and generates a CloudTrail event record. This happens at the API endpoint level — there is no agent to install, and it cannot be disabled by the calling principal (only the account owner can disable a trail).

Step 2: Event Types

Management Events: Control-plane operations
  → CreateBucket, RunInstances, AssumeRole, AttachRolePolicy
  → Captured by default, low volume

Data Events: Data-plane operations on resources  
  → S3 GetObject/PutObject, Lambda Invoke, DynamoDB GetItem
  → High volume, disabled by default, additional cost
  → Must be explicitly enabled per resource or resource type

Insights Events: Anomaly detection
  → Unusual API call volumes detected by CloudTrail ML

Step 3: Event Structure

{
  "eventVersion": "1.08",
  "userIdentity": {
    "type": "IAMUser",
    "principalId": "AIDAXXXXXXXXXXXXXXXXX",
    "arn": "arn:aws:iam::123456789012:user/alice",
    "accountId": "123456789012"
  },
  "eventTime": "2024-03-15T14:23:11Z",
  "eventSource": "s3.amazonaws.com",
  "eventName": "DeleteObject",
  "sourceIPAddress": "203.0.113.42",
  "requestParameters": {
    "bucketName": "prod-data-lake",
    "key": "sensitive/records.csv"
  },
  "responseElements": null,
  "errorCode": null
}

Step 4: S3 Delivery and Integrity

CloudTrail delivers log files to S3 every ~5 minutes, compressed with gzip, using a path structure:

s3://my-audit-bucket/AWSLogs/{AccountID}/CloudTrail/{Region}/{YYYY}/{MM}/{DD}/
  {AccountID}_CloudTrail_{Region}_{timestamp}_{UniqueString}.json.gz

Each delivery includes a digest file with SHA-256 hashes of log files and a chain-hash linking to the previous digest — enabling cryptographic validation that logs haven’t been tampered with.

# Validate log integrity
aws cloudtrail validate-logs   --trail-arn arn:aws:cloudtrail:us-east-1:123456789012:trail/MyTrail   --start-time 2024-03-15T00:00:00Z

Step 5: Querying with Athena

-- Find all DeleteObject calls in the last 7 days
SELECT eventtime, useridentity.arn, requestparameters, sourceipaddress
FROM cloudtrail_logs
WHERE eventname = 'DeleteObject'
  AND eventtime > DATE_FORMAT(DATE_ADD('day', -7, NOW()), '%Y-%m-%dT%H:%i:%sZ')
ORDER BY eventtime DESC;

-- Find all API calls by a specific IP address
SELECT eventtime, eventsource, eventname, errorcode
FROM cloudtrail_logs  
WHERE sourceipaddress = '203.0.113.42'
ORDER BY eventtime DESC;

Key Takeaways

• CloudTrail captures every AWS API call at the control plane level — no agent required, cannot be bypassed by the calling principal.
• Management events are free and captured by default; data events (S3 object-level, Lambda invocations) must be explicitly enabled and incur additional cost.
• CloudTrail delivers logs every ~5 minutes to S3 with cryptographic digest chaining for tamper detection.
• Use Athena with a partitioned Glue table on CloudTrail’s S3 path to query billions of events cost-effectively.
• Enable CloudTrail Lake for real-time SQL querying without S3/Athena setup, at the cost of higher per-event pricing.