aws-cloudtrail-normalize-observations

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

1. Preserve the raw evidence separately; normalization is an analysis view, not the legal evidence record.
2. Normalize all events before building baselines or detection specs.
3. Use references/observation_schema.md when a downstream task needs exact field names.
4. 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.