Docs · ALFA

ALFA

Acquire Google Workspace audit logs, map them to ATT&CK and score event sequences for review.

On this page

Start here 

ALFA (Automated Audit Log Forensic Analysis for Google Workspace) acquires Google Workspace audit logs, maps events to the MITRE ATT&CK Cloud framework, and scores event sequences to surface likely attack chains. You initialize a project, add Google API credentials, acquire logs, then analyze them. ALFA can also load and re-analyze a dataset you already have.

Tool landing page: the ALFA tool overview.

What the tool is for 

ALFA works the triage problem in a Google Workspace investigation. Acquisition pulls the audit logs. Analysis categorizes each event against MITRE ATT&CK Cloud and scores mapped events in chronological order to identify subchains that resemble an attack path, so the analyst starts from a ranked short list rather than raw logs.

Requirements 

  • Python 3.12 or higher.
  • Tested on Linux (Debian and Ubuntu). macOS and Windows may work with variable results.
  • A Google Cloud project with an OAuth 2.0 client and the Admin SDK API enabled.
  • A Google Workspace user with admin privileges.

Installation 

Download the project, then from its folder install in editable mode:

Shell
pip install -e .

or

Shell
pip3 install -e .

On macOS, the README documents installing Python 3.12 with pyenv and optionally using a virtual environment before pip install -e .. After install, verify by running the alfa command.

Authentication and permissions 

ALFA authenticates to Google with OAuth 2.0 and uses the Admin SDK Reports API (activities.list). The OAuth scope requested is read-only:

Shell
https://www.googleapis.com/auth/admin.reports.audit.readonly

Setup, from CREDENTIALS.md:

  1. The Admin SDK Reports API requires a user with admin privileges.
  2. Create a Google Cloud project and an OAuth client ID of type "web application".
  3. Add http://localhost:8089/ as an authorized redirect URI (include the trailing slash).
  4. Download the client credentials to config/credentials.json in your project folder.
  5. Enable the Admin SDK API for the project.

On the first query, a browser window opens to grant consent, and a token.json is written to the config directory. The authorization flow uses a local server on port 8089, so that port must be free.


Note on the refresh token: the refresh_token is issued only on first consent. If token.json is deleted and re-created, it will not contain a refresh token unless you remove the app's permissions and re-grant consent. This is documented in CREDENTIALS.md and the Known Errors section.

Configuration 

Initialize a project, which creates a directory for configuration and data:

Shell
alfa init project_x

Copy your credentials.json into the project's config/ folder.

Two configuration files control analysis behavior:

  • alfa/config/event_to_mitre.yml maps individual events to MITRE ATT&CK Cloud techniques and tactics. The repository advises editing alfa/utils/mappings.yml instead and regenerating event_to_mitre.yml with alfa/utils/event_mitre_remap.py.
  • alfa/config/config.yml holds the kill-chain discovery constants, including min_chain_length (7), min_chain_statistic (0.6), and slack-line bounds. The repository advises analysts to review these for their workspace.

Core workflow 

  1. alfa init <projectname> to create the project.
  2. Place credentials.json into config/.
  3. alfa acquire to pull the audit logs.
  4. alfa analyze to categorize and score the data and drop into the analysis shell.
  5. Within the shell, inspect subchains and export activity of interest.

Commands and operating modes 

Acquire

Acquire all log types for all users:

Shell
alfa acquire

One JSON file is generated per log type in the data folder. Filtering examples:

  • Single log type: alfa acquire --logtype=admin
  • Output directory: alfa acquire -d /tmp/project_secret
  • Specific user: alfa acquire --user=insert_username
  • Time range (RFC3339): alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z

See alfa acquire -h for the full option list.

Analyze

Shell
alfa analyze

ALFA categorizes each event against MITRE ATT&CK Cloud, scores mapped events in chronological order to find subchains, and opens an interactive shell. In the shell:

  • A.subchains() lists identified subchains in the form (first_event_index, last_event_index, kill_chain_score). A score near 1 is a stronger chain; closer to 0 is weaker.
  • A.aoi(export='activities.json') exports identified subchains to a file for further analysis.

Load

Load previously acquired logs from local storage:

Shell
A = Alfa.load([logname])
A = Alfa.load('all')

By default, benign activity is filtered out. To load unfiltered:

Shell
Alfa.load([logname], filter=False)

A directory of JSON logs can also be loaded from the command line, for example alfa load -p data/<dataset>.

Inputs and scope 

  • Log sources. The acquired log types are defined in alfa/config/config.yml. At time of retrieval the list includes Admin, Login, Token, Drive, Calendar, Chat, Meet, Groups, Groups Enterprise, Mobile, SAML, Rules, User Accounts, Context-aware Access, Access Transparency, GCP, Chrome, Keep, Jamboard, Vault, Classroom, Meet Hardware, LDAP, Profile, Contacts, Cloud Search, Data Migration, Directory Sync, Tasks, and others.
  • Gmail. The Gmail log type is commented out in the default configuration. The repository notes it only works with an explicit start and end time and a maximum range of 30 days.
  • Scope filters. Acquisition can be filtered by log type, user, output directory, and time range.

Outputs and structure 

  • Acquisition writes one JSON file per log type into the project's data directory.
  • Analysis identifies subchains and can export activity of interest to a JSON file such as activities.json.
  • In the analysis model, each Google audit "activity" contains a list of "events," and ALFA classifies events against the MITRE ATT&CK Cloud matrix.

Operating limits (from current source) 

  • Lookback. The collector defines a maximum lookback of 180 days (MAX_LOOKBACK_DAYS = 180).
  • Gmail range. A Gmail-specific maximum range of 30 days (GMAIL_MAX_RANGE_DAYS = 30).
  • Pagination. Acquisition pages results, with a default of 1000 results per page and an optional maximum page count.
  • Retry. Requests retry up to 5 times with exponential backoff.

Troubleshooting (documented failure modes) 

  • ValueError: missing config/credentials.json. Add credentials.json to the project's config/ subdirectory per CREDENTIALS.md.
  • OSError: [Errno 98] Address already in use. Port 8089 is in use by another application (the README notes Splunk uses 8089 by default). Free the port; it is required for the authentication flow.
  • ValueError: Authorized user info was not in the expected format, missing fields refresh_token. Remove token.json from config/ and re-run. If it persists, remove token.json and credentials.json and re-register the OAuth application.
  • Error 400: redirect_uri_mismatch. Ensure the authorized redirect URI includes the trailing slash: http://localhost:8089/.

Version and source information 

  • Repository: https://github.com/invictus-ir/ALFA
  • Branch: main
  • Commit: 97ee7c2eb28c94ef1d59d4c513951c4c5a9fb91c
  • Version string in setup.py: 0.2.0
  • Retrieved: 2026-10-07
  • Releases: none published at retrieval.