| name | aws-cloudtrail-normalize-observations |
| description | Normalize AWS CloudTrail records into a stable business-analysis observation schema. Use when working with CloudTrail LookupEvents output, raw CloudTrail JSON, CloudTrail JSONL, QRadar decoded_payload records, evidence-pack wrappers, actor/source-IP/event baselining, or when another AWS CloudTrail skill needs normalized observations before baseline, detection, triage, or reporting. |
AWS CloudTrail Normalize Observations
Use this skill to convert raw CloudTrail-shaped records into one normalized JSONL stream that downstream baseline, alerting, and reporting skills can consume.
Quick Start
Run the bundled normalizer when the input is file-based:
python3 ../../skills/aws/cloudtrail/normalize-observations/scripts/normalize_cloudtrail.py \
--input path/to/cloudtrail.json path/to/events.jsonl \
--output normalized_observations.jsonl
The script accepts:
- CloudTrail
LookupEvents responses with CloudTrailEvent
- raw CloudTrail event objects with
eventVersion
- JSON arrays or JSONL streams
- evidence-pack wrappers with
cloudtrail_event
- SIEM wrappers with
decoded_payload
Workflow
- Preserve the raw evidence separately; normalization is an analysis view, not the legal evidence record.
- Normalize all events before building baselines or detection specs.
- Use
references/observation_schema.md when a downstream task needs exact field names.
- Treat
actor, actor_type, business_risk_category, and pattern_category as explainability fields; do not use them as the only source of truth for enforcement.
Rules
- Extract actor in this order: SSO/session issuer role name, IAM user name, CloudTrail
Username, assumed-role ARN role name, root, full ARN, unknown.
- Classify root as critical regardless of event name.
- Mark static IAM users and named users separately from service roles and SSO/admin roles.
- Keep
source_ip exactly as CloudTrail reports it; classify AWS service sources separately rather than rewriting them.
- Include
resources from CloudTrail Resources, request parameters, or event resources when available.
- Do not discard malformed records silently when running manually; report invalid counts in the manifest or console output.
Output
The script writes one JSON object per line with the stable observation schema. Downstream skills expect these fields:
event_id, event_time, account_id, region, event_name, event_source, actor, actor_type, source_ip, user_agent, resources, error_code, risk, business_risk_category, pattern_category.
