ALFA

Automatisierte forensische Analyse von Audit-Logs für Google Workspace

Copyright (c) 2026 Invictus Incident Response
Ursprüngliche Autoren Greg Charitonos & BertJanCyber, gepflegt von Invictus Incident Response

Bevor Sie beginnen

Ein Hinweis zu unterstützten Betriebssystemen: ALFA wird auf mehreren Linux-Distributionen (Debian und Ubuntu) getestet.
Es ist zwar möglich, es unter Windows oder macOS zu verwenden, die Ergebnisse können jedoch variieren, daher erfolgt die Nutzung auf eigene Gefahr.

Installation

1. Laden Sie dieses Projekt herunter
2. Navigieren Sie im Terminal zu dem Ordner und führen Sie sudo pip install -e . oder sudo pip3 install -e . aus

Installation unter macOS

1. Python 3.9 mit pyenv installieren ALFA funktioniert am besten mit Python 3.9. Sie können pyenv verwenden, um diese Version zu verwalten und zu installieren.

   • Falls Sie pyenv noch nicht installiert haben, können Sie dies mit Homebrew tun:
     root@kitploit:~

     brew install pyenv
     

   • Richten Sie pyenv in Ihrer Shell ein, indem Sie Folgendes zu Ihrer Shell-Konfigurationsdatei (z. B. ~/.zshrc oder ~/.bashrc) hinzufügen:
     root@kitploit:~

     export PYENV_ROOT="$HOME/.pyenv"
     export PATH="$PYENV_ROOT/bin:$PATH"
     eval "$(pyenv init --path)"
     

     Nachdem Sie die Datei aktualisiert haben, laden Sie Ihre Shell neu:
     root@kitploit:~

     source ~/.zshrc  # or source ~/.bashrc
     

   • Installieren Sie Python 3.9 mit pyenv:
     root@kitploit:~

     pyenv install 3.9
     

2. (Optional) Eine virtuelle Umgebung erstellen Es ist eine gute Praxis, Projekte in einer virtuellen Umgebung auszuführen, um Abhängigkeiten zu isolieren. Erstellen Sie mit der soeben eingestellten Python 3.9-Version eine virtuelle Umgebung:

   root@kitploit:~

   python -m venv alfa
   

   • Aktivieren Sie die virtuelle Umgebung:
     root@kitploit:~

     source alfa/bin/activate
     

3. ALFA installieren Installieren Sie ALFA im Ordner, in dem sich das ALFA-Projekt befindet, mit pip:

   root@kitploit:~

   pip install -e .
   

   Wenn Sie keine virtuelle Umgebung verwenden, benötigen Sie möglicherweise sudo:

   root@kitploit:~

   sudo pip install -e .
   

4. Installation überprüfen Nach der Installation können Sie überprüfen, ob ALFA installiert ist, indem Sie versuchen, das Befehlszeilentool alfa auszuführen.

Verwendung von ALFA

HINWEIS: Informationen zum Abrufen von credentials.json finden Sie in CREDENTIALS.md

Setup

1. Der erste Schritt besteht darin, ALFA zu initialisieren. Führen Sie dazu alfa init projektname aus. Dieser Befehl erstellt ein neues Verzeichnis zur Speicherung Ihrer Konfiguration und Daten. Z.B. alfa init project_x
2. Ein neues Projekt mit dem Namen 'project_x' wurde nun erstellt. Kopieren Sie in diesem Ordner Ihre credentials.json in den Ordner config/. (Siehe CREDENTIALS.md) für Anweisungen.
3. Nachdem Sie die credentials.json-Datei kopiert haben, können Sie ALFA verwenden.

ALFA bietet 3 Optionen, wie unten erklärt:

1. ALFA Acquire

Alle Google Workspace Audit-Logs erfassen

1. Führen Sie innerhalb von "project_x" (oder einem beliebigen zuvor gewählten Namen) alfa acquire aus
2. ALFA erfasst nun alle Logtypen für alle Benutzer und speichert sie in einem Unterverzeichnis im Ordner 'data'. Pro Logtyp wird eine .json-Datei erstellt.
3. Um weitere Optionen zu sehen, geben Sie alfa acquire -h ein

Erweiterte Erfassungen mit ALFA

Sie können verschiedene Filterungen durchführen, um die erfassten Daten zu begrenzen. Nachfolgend einige Beispiele:

• Nur den Logtyp 'admin' erfassen alfa acquire --logtype=admin
• Ausgabe in einem bestimmten Ordner speichern alfa acquire -d /tmp/project_secret
• Nur Logs für einen bestimmten Benutzer erfassen alfa acquire --user=insert_username
• Logs innerhalb eines definierten Zeitraums erfassen alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z das Zeitformat ist (RFC3339)

Jetzt wissen Sie, wie Sie Daten erfassen können – Zeit für die ausgefallenen Funktionen, um die Kraft von ALFA zu entfesseln.

2. ALFA Analyze

Die Analysefunktion analysiert automatisch alle Audit-Log-Daten für einen bestimmten Google Workspace, um verdächtige Aktivitäten zu identifizieren.

Funktionsweise

1. Kategorisierung Jedes einzelne Ereignis wird basierend auf einer Zuordnung kategorisiert, die in alfa/config/event_to_mitre.yml festgelegt ist. Wenn ein Ereignis mit dieser Liste übereinstimmt, wird es einer Technik des MITRE ATT&CK Cloud Frameworks (https://attack.mitre.org/matrices/enterprise/cloud/) zugeordnet.

2. Bewertung Als Nächstes analysiert ALFA alle zugeordneten Ereignisse in chronologischer Reihenfolge, um Kill Chains oder logische Angriffspfade zu identifizieren. Z.B. Ein Ereignis, das der Persistenzphase zugeordnet ist, gefolgt von einem Ereignis, das der Phase des Credential Access zugeordnet ist, führt zu einer höheren Bewertung.

3. Ergebnis Letztendlich liefert ALFA dem Analysten eine Liste identifizierter 'Subchains', die weiter analysiert werden können.

Wie verwende ich ALFA Analyze?

1. Führen Sie zunächst alfa analyze aus, das automatisch Subchains identifiziert (oder nicht, falls keine gefunden wurden). Es öffnet sich auch eine Shell, in der Sie Folgeaktivitäten durchführen können.
2. Um weitere Informationen zu einer bestimmten Subchain zu erhalten, können Sie einfach A.subchains() ausführen. Dies zeigt die Kette im folgenden Format an: (number_of_first_event_in_chain,number_of_last_event_in_chain,killchain_score). Ein Score von 1 bedeutet, dass eine perfekte Kette identifiziert wurde; je näher er an 0 liegt, desto schwächer ist die Kette.
3. Um auf die verdächtigen Ereignisse zuzugreifen, die diese Kette verursacht haben, verwenden Sie A.aoi(export='activities.json'), um alle identifizierten Subchains in eine Datei zu exportieren, die Sie dann für weitere Analysen verwenden können.

3. ALFA Load

Daten aus dem lokalen Speicher laden

Aus dem lokalen Speicher

Verwenden Sie A = Alfa.load([logname]), um Logs aus dem lokalen Speicher zu laden und zu analysieren. Verwenden Sie A = Alfa.load('all'), um alle Logs zu laden. Alfa filtert standardmäßig harmlose Aktivitäten heraus. Um alle Aktivitäten und Ereignisse ungefiltert zu laden, verwenden Sie Alfa.load([logname], filter=False).

Änderungen vornehmen

Hinzufügen neuer Ereigniszuordnungen

Es ist möglich, die Datei config/event_to_mitre.yml direkt zu bearbeiten, jedoch wird davon abgeraten. Das Layout dieser Datei ist unintuitiv. Erwägen Sie stattdessen Änderungen an utils/mappings.yml. Füllen Sie dann config/event_to_mitre.yml neu auf, indem Sie utils/event_mitre_remap.py ausführen.

Ändern von Kill-Chain-Erkennungsmethoden

Die Kill-Chain-Erkennungsfunktion verwendet hartcodierte Konstanten. Diese finden Sie in der config/config.yml. Forensischen Analysten wird empfohlen, die Werte zu überprüfen und bei Bedarf für ihren Workspace anzupassen. Diese Konstanten sind sowohl für die Kill-Chain-Statistik (kcs) als auch für die Kill-Chain-Erkennung (subchains) verantwortlich.

FAQ

Möchten Sie mehr über die verwendeten Statistiken und Algorithmen für ALFA erfahren? Wir haben einen Blogbeitrag dazu hier geschrieben: (https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92)

Bekannte Fehler

ValueError: missing config/credentials.json

Sie müssen eine credentials.json-Datei zum Projektordner im Unterverzeichnis 'config' hinzufügen. Anweisungen in der Datei 'CREDENTIALS.md'.

OSError: [Errno 98] Address already in use

Dies bedeutet, dass Port 8089 bereits von einer anderen Anwendung verwendet wird. Dies kann passieren, wenn auf diesem Port ein Webserver läuft oder Splunk standardmäßig Port 8089 verwendet. Lösung: Stoppen Sie (vorübergehend) die Nutzung dieses Ports, da er für den Authentifizierungsablauf benötigt wird und verfügbar sein muss.

ValueError: Authorized user info was not in the expected format, missing fields refresh_token.

Manchmal müssen die Autorisierungsinformationen aktualisiert werden. Der einfachste Weg ist, die Datei 'token.json' aus dem Ordner project_name/config zu entfernen und den Befehl erneut auszuführen. Wenn das weiterhin Probleme bereitet, entfernen Sie token.json und credentials.json und registrieren Sie die OAuth-Anwendung erneut, wie in CREDENTIALS.MD beschrieben.

Access is blocked: This app's request is invalid // Error 400: redirect_uri_mismatch

Stellen Sie sicher, dass der nachgestellte Schrägstrich (/) in der URI http://localhost:8089 unter Authorized redirect URIs Ihrer OAuth 2.0 Client IDs vorhanden ist.