cloudtrail-quickscan
An explainable first pass over AWS audit logs: IAM changes, logging disruption, public exposure and unusual activity.
- Input
- Local CloudTrail JSON; no AWS credentials.
- Checks
- IAM changes, logging disruption and public exposure.
- Output
- Severity, event context and text or JSON reports.
- Evidence
- Synthetic fixtures, unit tests and investigation notes.
Local input, readable findings and JSON output; no cloud credentials required.
The problem
Before a full investigation, a reviewer needs to know which events deserve attention and why. A small scanner makes that first pass inspectable without introducing a service, a database or a live AWS connection.
How it works
The CLI reads CloudTrail JSON, applies explicit rule functions, and produces findings with severity and event context. Text output is for a person; JSON output is for a script. Summary controls limit the busiest users or source addresses without removing the underlying findings.
PYTHONPATH=src python3 -m cloudtrail_quickscan samples/cloudtrail_sample.json
PYTHONPATH=src python3 -m cloudtrail_quickscan samples/cloudtrail_sample.json --jsonSecurity questions covered
The current checks cover failed logins, root activity, MFA removal, administrator policy attachments, IAM permissions-boundary removal, GuardDuty, Security Hub and Config being turned off, logging changes, S3 exposure changes, denied API calls, and public SSH/RDP ingress.
A boundary-removal event is worth attention because it changes the ceiling on an identity’s effective permissions. That is a different question from whether an access key was created or a policy was attached. Monitoring-disable and boundary-removal findings skip calls that carry an errorCode, because a denied attempt did not change anything; it still shows up as a denied call.
Verification and investigation
Rules have synthetic events and unit tests. The repository includes investigation notes, so a finding leads to a review question rather than just an alarming label.
PYTHONPATH=src python3 -m unittest discover -s testsBoundaries
A flagged event is a reason to investigate, not proof of compromise. Rules are heuristic; expected administrative work can trigger them. The tool does not correlate sessions, establish attribution or replace a SIEM.
Engineering choice
Keep the detection logic small enough that someone can read the rule, examine the sample and disagree with its severity. Explainability matters more here than a long list of opaque detections.