AWS CloudTrail Connection

Connects your agent to AWS CloudTrail for cloud audit and activity logging. Query management events, data events, and CloudTrail Insights. Read-only access — no write operations.

Authentication

AWS IAM credentials. Supports:

• access_key_id + secret_access_key — IAM user credentials
• role_arn — Cross-account role to assume (recommended for production)
• region — Primary AWS region (default: us-east-1)

Minimum IAM policy: cloudtrail:LookupEvents, cloudtrail:DescribeTrails, cloudtrail:GetTrailStatus, s3:GetObject for S3-based event history.

Endpoints

Event Lookup

• POST /LookupEvents — Search events by attribute (username, resource, event name, source IP)
• POST /GetQueryResults — Run CloudTrail Lake SQL queries (if Lake configured)

Trails

• POST /DescribeTrails — List configured trails with S3 bucket and status
• POST /GetTrailStatus — Check trail delivery status and latest event time

Insights

• POST /ListInsights — List CloudTrail Insights (unusual API activity)

Rules

• Event lookback limited to 90 days via LookupEvents API (CloudTrail Lake extends this)
• Rate limit: 2 requests/second for LookupEvents
• The agent adds time-range filters by default to prevent scanning the full 90-day window
• Large result sets are paginated and summarized — the agent dispatches task agents for bulk analysis
• Cross-account queries use STS AssumeRole automatically