CloudTrail as the API-Call Audit Log
Every action taken against an AWS account leaves a trace. Someone (or something) calls an API, and CloudTrail writes down who called it, when, from where, and what happened.
//
Busque em todas as páginas da documentação
Every action taken against an AWS account leaves a trace. Someone (or something) calls an API, and CloudTrail writes down who called it, when, from where, and what happened.
That single idea, an audit log of API activity, is the whole point of CloudTrail. This page builds the mental model before the rest of this section gets into trails, queries, and Lake.
An event in CloudTrail is a JSON record of a single API call: the caller's identity, the source IP, the request parameters, the response, and a timestamp.
CloudTrail splits events into two broad categories. Management events are control-plane calls - creating a bucket, launching an instance, changing an IAM policy. Data events are higher-volume data-plane calls - reading an S3 object, invoking a Lambda function - and are opt-in because of their volume.
Every AWS account has management-event logging active from the moment the account exists, with zero configuration. That's why you can query recent activity via SDK before ever creating a trail.
# --- Python (boto3) ---
import boto3
client = boto3.client("cloudtrail", region_name="us-east-1")
response = client.lookup_events(MaxResults=5)
for event in response["Events"]:
print(event["EventName"], event["EventTime"])// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, LookupEventsCommand } from "@aws-sdk/client-cloudtrail";
const client = new CloudTrailClient({ region: "us-east-1" });
const response = await client.send(new LookupEventsCommand({ MaxResults: 5 }));
for (const event of response.Events ?? []) {
console.log(event.EventName, event.EventTime);
}No trail exists in this example. LookupEvents reads directly from the account's built-in 90-day event history.
The 90-day event history is convenient but limited: it isn't durable past 90 days, isn't exportable in bulk, and isn't designed for high-volume analytical queries.
A trail solves that. Creating a trail tells CloudTrail to continuously deliver events as log files to an S3 bucket (and optionally CloudWatch Logs), for as long as you keep the bucket around.
A trail can also be multi-region (captures events from every region, not just the one it's created in) and organization-wide (captures every member account under AWS Organizations into one central bucket).
Trails add one more capability: log file validation. When enabled, CloudTrail delivers a periodic digest file alongside your logs, containing hashes that let you cryptographically verify no log file was altered or deleted after delivery. This is a file-integrity mechanism you verify, not a single API call that returns "valid" or "invalid" - the digest chain is the actual evidence.
| Capability | Without a Trail | With a Trail |
|---|---|---|
| Retention | 90 days | Indefinite (S3 lifecycle-managed) |
| Query method | LookupEvents | S3 object reads, Athena, or CloudTrail Lake |
| Data events (S3 object reads, Lambda invokes) | Not captured | Captured if explicitly enabled |
| Tamper-evidence | None | Log file validation (digest hash chain) |
| Cost | Free | S3 storage + optional CloudWatch Logs ingestion |
Because management-event history exists by default, incident responders can often reconstruct the last 90 days of account activity even in an account that was never deliberately configured for logging. That's a useful fallback, but it should never be the plan.
The baseline security posture for any AWS account is at least one organization-wide, multi-region trail with log file validation enabled, delivering to a dedicated, access-restricted S3 bucket. This guarantees retention beyond 90 days, coverage across every region and member account, and cryptographic evidence the logs weren't tampered with after the fact.
From there, teams layer on CloudTrail Lake for SQL-style queries across long retention windows, and EventBridge rules on top of CloudTrail events for near-real-time alerting on sensitive actions. Neither replaces the trail; both build on top of it.
ValidateLogFile API that hands you a boolean.LookupEvents query away.No. LookupEvents reads the last 90 days of management events without any trail configured, out of the box.
Management events are control-plane operations (creating, deleting, configuring resources). Data events are higher-volume data-plane operations like S3 object reads or Lambda invocations, and must be explicitly enabled.
No single call validates a log file. CloudTrail delivers digest files containing hashes; you (or a tool) walk that hash chain against the actual log files to detect tampering.
Retention, durability, and scale. Event history isn't exportable in bulk and expires at 90 days; a trail delivers to S3 indefinitely and supports large-scale querying via Athena or CloudTrail Lake.
You pay for the S3 storage and any optional CloudWatch Logs ingestion of the events delivered, not a per-region trail fee - a multi-region trail just means more regions' events land in the same bucket.
LookupEvents and trail examples.Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última atualização: 25 de jul. de 2026