Anthropic-Cybersecurity-Skills/skills/detecting-aws-cloudtrail-anomalies/references/api-reference.md

API Reference: Detecting AWS CloudTrail Anomalies

boto3 CloudTrail API

import boto3

client = boto3.client("cloudtrail", region_name="us-east-1")

# Paginated event lookup
paginator = client.get_paginator("lookup_events")
pages = paginator.paginate(
    StartTime=datetime(2025, 1, 1),
    EndTime=datetime.utcnow(),
    LookupAttributes=[{"AttributeKey": "EventName", "AttributeValue": "ConsoleLogin"}],
    PaginationConfig={"MaxItems": 500, "PageSize": 50},
)
for page in pages:
    for event in page["Events"]:
        ct = json.loads(event["CloudTrailEvent"])
        print(ct["sourceIPAddress"], event["EventName"])

CloudTrail Event Fields

Field	Location	Description
EventName	Event	API action name
EventSource	Event	AWS service (e.g. iam.amazonaws.com)
Username	Event	IAM user or assumed role
sourceIPAddress	CloudTrailEvent JSON	Caller IP address
errorCode	CloudTrailEvent JSON	Error type if failed
userAgent	CloudTrailEvent JSON	Client SDK/browser
awsRegion	CloudTrailEvent JSON	Region of API call

Sensitive API Calls to Monitor

Event Name	Risk	Reason
StopLogging	Critical	Disabling CloudTrail
DeleteTrail	Critical	Removing audit trail
CreateAccessKey	High	New credentials for user
AttachUserPolicy	High	Privilege escalation
PutBucketPolicy	High	S3 access change
ConsoleLogin	Medium	Interactive access
RunInstances	Medium	Resource creation
AssumeRole	Medium	Role switching

Rate Limits

• lookup_events: 2 requests/second per account per region
• Maximum lookback: 90 days
• Max results per page: 50 events

References

• boto3 CloudTrail: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudtrail.html
• CloudTrail Insights: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-insights-events-with-cloudtrail.html
• LookupEvents API: https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_LookupEvents.html