aws-cloudtrail-lookup-collector

name

aws-cloudtrail-lookup-collector

description

Collect reproducible AWS CloudTrail management events through CloudTrail LookupEvents. Use when making live AWS CloudTrail calls across accounts, roles, regions, event names, and time windows, especially when the output must include exact boto3 parameters, AWS CLI equivalents, call ledgers, capped-query markers, raw CloudTrailEvent payloads, and normalized observation JSONL for later baseline or alert analysis.

AWS CloudTrail Lookup Collector

Use this skill for live CloudTrail management-event collection. It is customer-agnostic and requires explicit account/role/session configuration.

Quick Start

python3 ../../skills/aws/cloudtrail/lookup-collector/scripts/lookup_events.py \
  --accounts accounts.json \
  --event-names events.txt \
  --regions us-east-1,us-west-2 \
  --start 2026-04-01T00:00:00Z \
  --end 2026-06-12T00:00:00Z \
  --output cloudtrail_lookup_out

Account Config

accounts.json is an array:

[
  {"account_id": "123456789012", "role_arn": "arn:aws:iam::123456789012:role/ReadOnlySecurityRole", "profile": "optional-source-profile"}
]

If role_arn is omitted, the script uses the current boto3 session credentials. If profile is present, it uses that profile before assuming the role.

Rules

• Record every lookup call in lookup_calls.json.
• Include an AWS CLI equivalent for every call.
• Capture errors and capped queries; do not hide partial collection.
• Keep raw lookup responses separately from normalized observations.
• Prefer narrow event-name lookups for high-signal management events; CloudTrail LookupEvents is query-limited and not a full data-event lake.

Outputs

• raw_lookup_events.json
• raw_cloudtrail_events.json
• lookup_calls.json
• normalized_observations.jsonl
• manifest.json

Use this skill with aws-cloudtrail-normalize-observations when normalizing pre-existing CloudTrail files rather than making live AWS calls.