Skip to content

README.md

Latest commit

 

History

History
73 lines (53 loc) · 1.96 KB

README.md

File metadata and controls

73 lines (53 loc) · 1.96 KB
Raw

cloudtrail-quickscan

A small Python tool for checking AWS CloudTrail JSON logs.

It loads CloudTrail events, finds a few suspicious patterns, and prints a short report that is easy to read.

This is not a full SIEM or a cloud security platform. It is meant to be a small helper for quick log review and cloud security labs.

What it checks

  • failed console logins
  • root account activity
  • IAM policy and access key changes
  • security group changes
  • CloudTrail logging changes, such as DeleteTrail or StopLogging
  • S3 bucket exposure changes, such as public ACLs or public access block removal
  • denied AWS API calls, such as AccessDenied or UnauthorizedOperation
  • successful console logins without MFA
  • events from unusual AWS regions

Quick start

PYTHONPATH=src python3 -m cloudtrail_quickscan samples/cloudtrail_sample.json

JSON output for scripts:

PYTHONPATH=src python3 -m cloudtrail_quickscan samples/cloudtrail_sample.json --json

Run tests:

PYTHONPATH=src python3 -m unittest discover -s tests

The same test command runs in GitHub Actions.

Example output

CloudTrail Quickscan
Events checked: 8
Findings: 9
Severity: HIGH=3, MED=5, LOW=1

MED   Failed console login
MED   IAM change: CreateAccessKey
MED   Security group change: AuthorizeSecurityGroupIngress
LOW   Event from uncommon region: ap-south-1
HIGH  Root account activity
HIGH  CloudTrail logging change: DeleteTrail
HIGH  S3 bucket exposure change: PutBucketAcl
MED   API call denied: ListUsers
MED   Console login without MFA

Project plan

  • keep the parser small and readable
  • add more detection rules slowly
  • add tests for every rule
  • keep JSON output useful for small scripts
  • add short notes about how to investigate each finding

Notes

The sample data is fake and only used for testing.

Short triage notes are in docs/investigation-notes.md. Basic contribution notes are in CONTRIBUTING.md.