Docs · ALFA
ALFA
Acquire Google Workspace audit logs, map them to ATT&CK and score event sequences for review.
Tool landing page: the ALFA tool overview.
On this page
- Start here
- What the tool is for
- Requirements
- Installation
- Authentication and permissions
- Configuration
- Core workflow
- Commands and operating modes
- Acquire
- Analyze
- Load
- Inputs and scope
- Outputs and structure
- Operating limits (from current source)
- Troubleshooting (documented failure modes)
- Version and source information
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:
pip install -e .or
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:
https://www.googleapis.com/auth/admin.reports.audit.readonlySetup, from CREDENTIALS.md:
- The Admin SDK Reports API requires a user with admin privileges.
- Create a Google Cloud project and an OAuth client ID of type "web application".
- Add
http://localhost:8089/as an authorized redirect URI (include the trailing slash). - Download the client credentials to
config/credentials.jsonin your project folder. - 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: therefresh_tokenis issued only on first consent. Iftoken.jsonis 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 inCREDENTIALS.mdand the Known Errors section.
Configuration
Initialize a project, which creates a directory for configuration and data:
alfa init project_xCopy your credentials.json into the project's config/ folder.
Two configuration files control analysis behavior:
alfa/config/event_to_mitre.ymlmaps individual events to MITRE ATT&CK Cloud techniques and tactics. The repository advises editingalfa/utils/mappings.ymlinstead and regeneratingevent_to_mitre.ymlwithalfa/utils/event_mitre_remap.py.alfa/config/config.ymlholds the kill-chain discovery constants, includingmin_chain_length(7),min_chain_statistic(0.6), and slack-line bounds. The repository advises analysts to review these for their workspace.
Core workflow
alfa init <projectname>to create the project.- Place
credentials.jsonintoconfig/. alfa acquireto pull the audit logs.alfa analyzeto categorize and score the data and drop into the analysis shell.- Within the shell, inspect subchains and export activity of interest.
Commands and operating modes
Acquire
Acquire all log types for all users:
alfa acquireOne 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
alfa analyzeALFA 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:
A = Alfa.load([logname])
A = Alfa.load('all')By default, benign activity is filtered out. To load unfiltered:
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
datadirectory. - 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. Addcredentials.jsonto the project'sconfig/subdirectory perCREDENTIALS.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. Removetoken.jsonfromconfig/and re-run. If it persists, removetoken.jsonandcredentials.jsonand 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.