How to analyse CloudTrail logs: a practical guide
CloudTrail records almost every API call made in your AWS account: who made it, from where, when, and whether it worked. When something changes unexpectedly, such as a deleted security group, a new access key or an Amazon Connect instance setting that "nobody touched", CloudTrail is where you find out what happened. Raw CloudTrail files are hard to read, though. Each file is gzipped JSON with a Records array that can hold thousands of events. This analyzer parses them in your browser and pulls out the events that matter.
Where to get the logs
- Event history (console): CloudTrail → Event history keeps 90 days of management events per region at no cost. Filter by event name, user or resource, then use Download events and choose JSON.
- A trail in S3: trails deliver files to
s3://bucket/AWSLogs/<account-id>/CloudTrail/<region>/YYYY/MM/DD/. Download one or more.json.gzfiles and drop them in. You don't need to unzip them first. - CLI:
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=DeleteBucket --max-results 50returns the same events as JSON you can paste.
What to look at first
- Failed calls. Events with an
errorCodesuch asAccessDeniedorUnauthorizedOperationshow either a permissions problem in an app, or someone probing what they can do. A burst of failures from one identity is worth investigating. - Root user activity.
userIdentity.type = Rootshould be rare. Any root sign-in or API call outside account setup or billing work needs an explanation. - IAM changes.
CreateUser,CreateAccessKey,AttachUserPolicy,PutRolePolicyandUpdateAssumeRolePolicyare the classic signs of privilege escalation. - Logging being switched off.
StopLogging,DeleteTrailandPutEventSelectorson a trail are high-severity events, because attackers try to remove the record of what they did. - Unusual source IPs or regions. Activity in a region you never use often means a leaked credential is being used to run resources.
Worked example: "who changed our Amazon Connect instance?"
Amazon Connect admin actions are management events in CloudTrail under the event source connect.amazonaws.com. If a queue, routing profile or contact flow changed overnight:
- In Event history, filter on Event source = connect.amazonaws.com for the time window, download the results as JSON and load them here.
- Look for
UpdateContactFlowContent,UpdateQueueHoursOfOperation,UpdateRoutingProfileQueuesorUpdateUserRoutingProfile. userIdentityshows the IAM role or user. For changes made in the Connect admin website, it is typically the role used by the Connect console session.sourceIPAddressandeventTimehelp you match the change to a person or a pipeline.
Event times are in UTC. Convert them to local time with the Unix Timestamp Converter when you line them up against contact records from the CTR Parser.
Reading an event
eventNameandeventSource: the API call and the service it belongs to.userIdentity: the type (IAMUser, AssumedRole, Root, AWSService) and the ARN. With assumed roles, the session name after the last/often identifies the actual person or job.requestParametersandresponseElements: what was asked for and what came back. Some services redact sensitive values.readOnly:falsemeans the call changed something. Filtering to write events cuts most of the noise.
Good practice for CloudTrail
- Use an organisation trail that covers all regions and sends logs to a separate, locked-down log archive account.
- Turn on log file validation so you can prove the files haven't been altered.
- For long-term searching, query the S3 logs with Athena or CloudTrail Lake instead of downloading files.
- When you find an over-broad permission, tighten it with the IAM Policy Generator and test it with the Policy Simulator before you deploy it.