Open source · Python
ALFA
Pull Google Workspace audit logs, map each event to MITRE ATT&CK and score event sequences, so you start with a short list of activity worth investigating.
# Install, then create a project
pip install -e .
alfa init projectname
# Acquire a time range, then analyse it
alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z
alfa analyze
✓ one JSON file per log type in ./dataWhat it does
Audit logs in, a short list out
Read-only, through the Admin SDK Reports API. Mapping and scoring are heuristics: they point at sequences worth reviewing.
How it works
Three modes
Acquire once, then analyse and reload offline as often as you need.
- 01
Acquire
Pulls audit logs through the Admin SDK Reports API, one JSON file per log type. Filter by log type, user, folder or time range.
- 02
Analyse
Maps each event to the MITRE ATT&CK Cloud matrix, then scores mapped events in order to find sequences that look like an attack path.
- 03
Load
Reloads acquired logs from disk for analysis, with benign activity filtered out by default.
What you get
From a full log pull to a short list
| Mode | Output | Command |
|---|---|---|
| Acquire | Audit logs, one JSON file per log type | alfa acquire |
| Analyse | Ranked sequences: first event, last event, kill-chain score | alfa analyze |
| Export | Identified activity, saved for further analysis | activities.json |
| Load | Saved logs back into a session, without re-acquiring | Alfa.load('all') |
Before you run it
Permissions, scope and clean-up
Read-only access
Uses the admin.reports.audit.readonly OAuth scope. The Reports API needs a user with admin privileges.
Setup
A Google Cloud project with an OAuth 2.0 client and the Admin SDK API enabled. Sign-in runs a local server on port 8089, which must be free.
Gmail logs
Not acquired by default. They need an explicit start and end time, over 30 days at most.
Platforms
Tested on Debian and Ubuntu. macOS and Windows may work; results can vary.
Where it’s used
Where it fits
Investigating a Google Workspace tenant.
OpenAcquiring Workspace logs with ALFA is a lab in the course.
Releases
No tagged releases yet
The repository has no published releases. Install from the main branch, and check the commit history for recent changes.
More tools
The rest of the toolkit
ALFA
Have a ranked list and need a second read?
A responder can review the sequences with you.

