AWS CloudTrail Forensics API Reference
boto3 CloudTrail Client
import boto3
client = boto3.client("cloudtrail", region_name="us-east-1")
lookup_events
response = client.lookup_events(
LookupAttributes=[
{"AttributeKey": "Username", "AttributeValue": "compromised-user"},
],
StartTime=datetime(2025, 1, 1),
EndTime=datetime(2025, 1, 2),
MaxResults=50,
)
LookupAttributes Keys
| AttributeKey |
Description |
| EventId |
Unique event identifier |
| EventName |
AWS API action (e.g., CreateUser, GetObject) |
| ReadOnly |
true/false for read-only API calls |
| Username |
IAM user or role session name |
| ResourceType |
AWS resource type (e.g., AWS::S3::Object) |
| ResourceName |
Name or ARN of the resource accessed |
| EventSource |
AWS service (e.g., iam.amazonaws.com) |
| AccessKeyId |
IAM access key used for the API call |
Response Structure
{
"Events": [
{
"EventId": "abc123",
"EventName": "CreateUser",
"EventTime": "2025-01-01T12:00:00Z",
"Username": "attacker",
"CloudTrailEvent": "{\"sourceIPAddress\":\"1.2.3.4\",\"userAgent\":\"aws-cli/2.0\",...}"
}
],
"NextToken": "..."
}
Paginator Usage
paginator = client.get_paginator("lookup_events")
for page in paginator.paginate(
LookupAttributes=[{"AttributeKey": "AccessKeyId", "AttributeValue": "AKIA..."}],
StartTime=start, EndTime=end
):
for event in page["Events"]:
ct = json.loads(event["CloudTrailEvent"])
print(ct["sourceIPAddress"], ct["eventName"])
AWS CLI Equivalents
# Lookup events by username
aws cloudtrail lookup-events \
--lookup-attributes AttributeKey=Username,AttributeValue=compromised-user \
--start-time 2025-01-01T00:00:00Z \
--output json
# Search by access key
aws cloudtrail lookup-events \
--lookup-attributes AttributeKey=AccessKeyId,AttributeValue=AKIAEXAMPLE \
--max-results 50
Athena Query for S3 CloudTrail Logs
SELECT eventtime, eventname, useridentity.arn, sourceipaddress, useragent,
requestparameters, responseelements, errorcode
FROM cloudtrail_logs
WHERE eventtime BETWEEN '2025-01-01' AND '2025-01-02'
AND useridentity.accesskeyid = 'AKIAEXAMPLE'
ORDER BY eventtime;
Key Forensic Event Names
| Event Name |
Service |
Forensic Significance |
| CreateUser |
IAM |
Persistence - new user account |
| CreateAccessKey |
IAM |
Persistence - new credential |
| AssumeRole |
STS |
Lateral movement / privilege escalation |
| GetObject |
S3 |
Data exfiltration |
| StopLogging |
CloudTrail |
Anti-forensics |
| PutBucketPolicy |
S3 |
Permission modification |
| RunInstances |
EC2 |
Cryptomining / C2 infrastructure |
| GetSecretValue |
SecretsManager |
Credential theft |
Suspicious User Agents
| User Agent Pattern |
Tool |
Pacu/... |
AWS exploitation framework |
python-requests |
Custom Python scripts |
aws-cli/2.x from unusual IP |
CLI from attacker machine |
Scout Suite |
Cloud security assessment |
Prowler |
AWS security scanner |
24f816b6a3