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.

License
MIT
Releases
None published · runs from main
Runs on
Python 3.12+ · tested on Linux
Cost
Free
SetupShell
# 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 ./data
Works withGoogle Workspace

What 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.

SourcesOutputsALFAPython
Workspace
Login
Drive · AdminAdmin SDK Reports APIJSON per log typeEvents mapped to ATT&CKRanked attack sequences

How it works

Three modes

Acquire once, then analyse and reload offline as often as you need.

  1. 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.

  2. 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.

  3. 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

Read the docs
ModeOutputCommand
AcquireAudit logs, one JSON file per log typealfa acquire
AnalyseRanked sequences: first event, last event, kill-chain scorealfa analyze
ExportIdentified activity, saved for further analysisactivities.json
LoadSaved logs back into a session, without re-acquiringAlfa.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

ServiceIncident response

Investigating a Google Workspace tenant.

Open
AcademyIncident response in the Google cloud

Acquiring Workspace logs with ALFA is a lab in the course.

Releases

No tagged releases yet

Recent commits

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.