Trails, S3 Delivery & Log File Validation

A trail is what turns CloudTrail from a 90-day rolling window into durable, exportable, integrity-checked audit history.

This page covers creating an organization-wide, multi-region trail, delivering it to S3, and enabling log file validation, plus what that validation actually checks.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
trail = client.create_trail(
    Name="org-baseline-trail",
    S3BucketName="acme-org-cloudtrail-logs",
    IsMultiRegionTrail=True,
    IsOrganizationTrail=True,
    EnableLogFileValidation=True,
)
client.start_logging(Name="org-baseline-trail")

When to reach for this:

• Standing up baseline security logging for a brand-new AWS account or Organization.
• Centralizing audit logs from every member account into one security-team-owned bucket.
• Compliance frameworks (SOC 2, PCI, HIPAA) that require tamper-evident, long-retention audit logs.
• Preparing for an incident-response capability that needs history beyond the free 90-day window.

Working Example

Create the S3 destination, attach the required bucket policy, then create and start an org-wide trail.

# --- Python (boto3) ---
import json, boto3
 
s3 = boto3.client("s3")
cloudtrail = boto3.client("cloudtrail")
 
bucket_name = "acme-org-cloudtrail-logs"
account_id = "111122223333"
 
s3.create_bucket(Bucket=bucket_name)
 
bucket_policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AWSCloudTrailAclCheck",
            "Effect": "Allow",
            "Principal": {"Service": "cloudtrail.amazonaws.com"},
            "Action": "s3:GetBucketAcl",
            "Resource": f"arn:aws:s3:::{bucket_name}",
        },
        {
            "Sid": "AWSCloudTrailWrite",
            "Effect": "Allow",
            "Principal": {"Service": "cloudtrail.amazonaws.com"},
            "Action": "s3:PutObject",
            "Resource": f"arn:aws:s3:::{bucket_name}/AWSLogs/{account_id}/*",
            "Condition": {"StringEquals": {"s3:x-amz-acl": "bucket-owner-full-control"}},
        },
    ],
}
s3.put_bucket_policy(Bucket=bucket_name, Policy=json.dumps(bucket_policy))
 
trail = cloudtrail.create_trail(
    Name="org-baseline-trail",
    S3BucketName=bucket_name,
    IsMultiRegionTrail=True,
    IsOrganizationTrail=True,
    EnableLogFileValidation=True,
)
cloudtrail.start_logging(Name="org-baseline-trail")
print(trail["TrailARN"])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, CreateBucketCommand, PutBucketPolicyCommand } from "@aws-sdk/client-s3";
import { CloudTrailClient, CreateTrailCommand, StartLoggingCommand } from "@aws-sdk/client-cloudtrail";
 
const s3 = new S3Client({});
const cloudtrail = new CloudTrailClient({});
 
const bucketName = "acme-org-cloudtrail-logs";
const accountId = "111122223333";
 
await s3.send(new CreateBucketCommand({ Bucket: bucketName }));
 
const bucketPolicy = {
  Version: "2012-10-17",
  Statement: [
    {
      Sid: "AWSCloudTrailAclCheck",
      Effect: "Allow",
      Principal: { Service: "cloudtrail.amazonaws.com" },
      Action: "s3:GetBucketAcl",
      Resource: `arn:aws:s3:::${bucketName}`,
    },
    {
      Sid: "AWSCloudTrailWrite",
      Effect: "Allow",
      Principal: { Service: "cloudtrail.amazonaws.com" },
      Action: "s3:PutObject",
      Resource: `arn:aws:s3:::${bucketName}/AWSLogs/${accountId}/*`,
      Condition: { StringEquals: { "s3:x-amz-acl": "bucket-owner-full-control" } },
    },
  ],
};
await s3.send(new PutBucketPolicyCommand({ Bucket: bucketName, Policy: JSON.stringify(bucketPolicy) }));
 
const trail = await cloudtrail.send(new CreateTrailCommand({
  Name: "org-baseline-trail",
  S3BucketName: bucketName,
  IsMultiRegionTrail: true,
  IsOrganizationTrail: true,
  EnableLogFileValidation: true,
}));
await cloudtrail.send(new StartLoggingCommand({ Name: "org-baseline-trail" }));
console.log(trail.TrailARN);

What this demonstrates:

• The bucket policy is required before CreateTrail will succeed - CloudTrail needs explicit permission to write into the bucket.
• IsOrganizationTrail: true only works when called from the Organization's management account (or a delegated admin account).
• CreateTrail defines the trail's configuration; StartLogging is what actually begins delivery.
• EnableLogFileValidation doesn't change what's logged - it adds periodic digest files alongside the log files.

Deep Dive

How It Works

• IsMultiRegionTrail makes one trail capture management events from every AWS region into the same S3 destination, instead of requiring one trail per region.
• IsOrganizationTrail extends that further: one trail in the management account captures events from every member account in the Organization, each delivered under its own account-ID prefix in the shared bucket.
• Log files land under a predictable key structure: AWSLogs/<account-id>/CloudTrail/<region>/<year>/<month>/<day>/, which is what makes Athena and manual S3 queries practical.
• With EnableLogFileValidation, CloudTrail periodically writes a digest file referencing the log files delivered since the last digest, along with a hash of each. Digest files are themselves signed, forming a chain back to the trail's creation.
• Verifying integrity means walking that chain: recomputing hashes of the actual log files and comparing them to what the digest recorded, then confirming the digest signatures themselves are unbroken. This is typically done with the AWS CLI's validate-logs helper or a custom script, not a single SDK call.

Log File Validation Is a Mechanism, Not an API Call

There's no ValidateLogFile operation in @aws-sdk/client-cloudtrail that returns a simple pass/fail. What CloudTrail gives you is the raw material - the digest files - and verification is a client-side process:

# Conceptual shape of validation - not a single boto3 call.
# 1. Locate the digest file covering the log files in question.
# 2. Verify the digest file's own signature against its published public key.
# 3. Recompute a hash of each referenced log file and compare to the digest's record.
# 4. Confirm digest files chain back-to-back with no gaps.

The AWS CLI's aws cloudtrail validate-logs --trail-arn ... --start-time ... command implements this for you and is the practical entry point most teams use, even in an otherwise SDK-driven pipeline.

Trail Configuration Options at a Glance

Gotchas

• Skipping StartLogging - CreateTrail alone configures but does not activate delivery; a trail that's never started logs nothing. Fix: always follow CreateTrail with StartLogging and confirm via GetTrailStatus.
• Missing or incorrect S3 bucket policy - CreateTrail fails outright, or silently stops delivering, if CloudTrail lacks s3:GetBucketAcl/s3:PutObject on the destination. Fix: attach the CloudTrail service-principal bucket policy shown above before creating the trail.
• Treating log file validation as an API you call to "check" a log - there is no such call; validation is a hash-chain you verify against digest files. Fix: use aws cloudtrail validate-logs or a script that walks the digest chain, not an SDK method search.
• Assuming IsOrganizationTrail works from any account - it only succeeds from the Organization's management account or a delegated CloudTrail admin account. Fix: run trail creation from the correct account, or delegate admin first.
• Forgetting S3 lifecycle policies on the destination bucket - without one, log files accumulate indefinitely and storage cost grows unchecked. Fix: add a lifecycle rule to transition or expire objects per your retention requirements.

Alternatives

FAQs

Related

• CloudTrail as the API-Call Audit Log - the conceptual model behind trails.
• CloudTrail Basics - simpler create-trail and status-check examples.
• Event History Queries via SDK - querying without needing the trail's S3 files.
• CloudTrail Lake for SQL-Based Audit Queries - SQL queries beyond the 90-day window.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).