ALFA

Analyse Forensique Automatisée des Journaux d'Audit pour Google Workspace

Copyright (c) 2026 Invictus Incident Response
Auteurs originaux Greg Charitonos & BertJanCyber maintenu par Invictus Incident Response

Avant de commencer

Note sur les systèmes d'exploitation pris en charge : ALFA est testé sur plusieurs distributions Linux (Debian et Ubuntu).
Bien qu'il soit possible de l'utiliser sur Windows ou macOS, les résultats peuvent varier, alors utilisez-le à vos risques et périls.

Installation

1. Téléchargez ce projet
2. Accédez au dossier dans votre terminal et exécutez sudo pip install -e . ou sudo pip3 install -e .

Installation sur macOS

1. Installer Python 3.9 avec pyenv ALFA fonctionne mieux avec Python 3.9. Vous pouvez utiliser pyenv pour gérer et installer cette version.

   • Si vous n'avez pas encore installé pyenv, vous pouvez le faire avec Homebrew :
     root@kitploit:~

     brew install pyenv
     

   • Configurez pyenv dans votre shell en ajoutant ce qui suit à votre fichier de configuration du shell (par ex., ~/.zshrc ou ~/.bashrc) :
     root@kitploit:~

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

     Après avoir mis à jour le fichier, rechargez votre shell :
     root@kitploit:~

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

   • Installez Python 3.9 avec pyenv :
     root@kitploit:~

     pyenv install 3.9
     

   • Définissez Python 3.9 comme version actuelle :
     root@kitploit:~

     pyenv global 3.9
     

     ou seulement pour la session en cours :
   root@kitploit:~

    pyenv shell 3.9
   

2. (Optionnel) Créer un environnement virtuel C'est une bonne pratique d'exécuter les projets dans un environnement virtuel pour isoler les dépendances. En utilisant la version 3.9 de Python que vous venez de définir, créez un environnement virtuel :

   root@kitploit:~

   python -m venv alfa
   

   • Activez l'environnement virtuel :
     root@kitploit:~

     source alfa/bin/activate
     

3. Installer ALFA Dans le dossier où se trouve le projet ALFA, installez-le avec pip :

   root@kitploit:~

   pip install -e .
   

   Si vous n'utilisez pas d'environnement virtuel, vous aurez peut-être besoin de sudo :

   root@kitploit:~

   sudo pip install -e .
   

4. Vérifier l'installation Après l'installation, vous pouvez vérifier qu'ALFA est installé en essayant d'exécuter son outil en ligne de commande alfa.

Utilisation d'ALFA

NOTE : Pour récupérer credentials.json, veuillez consulter CREDENTIALS.md

Configuration

1. La première étape consiste à initialiser ALFA en exécutant alfa init nomduprojet cette commande créera un nouveau dossier pour stocker votre configuration et vos données. Par ex. alfa init project_x
2. Un nouveau projet nommé 'project_x' a maintenant été généré. Dans ce dossier, copiez votre credentials.json dans le dossier config/. (Voir CREDENTIALS.md) pour les instructions.
3. Après avoir copié le fichier credentials.json, vous êtes prêt à utiliser ALFA.

ALFA propose 3 options comme expliqué ci-dessous :

1. ALFA Acquire

Acquérir tous les journaux d'audit Google Workspace

1. Depuis l'intérieur de "project_x" (ou tout autre nom que vous avez choisi auparavant), exécutez alfa acquire
2. ALFA va maintenant récupérer tous les types de journaux pour tous les utilisateurs et les enregistrer dans un sous-dossier du dossier 'data' ; un fichier .json sera généré par type de journal.
3. Pour voir les autres options disponibles, tapez alfa acquire -h

Acquisitions avancées avec ALFA

Vous pouvez effectuer toutes sortes de filtrages pour limiter les données que vous acquérez, voici quelques exemples :

• Récupérer uniquement le type de journal 'admin' : alfa acquire --logtype=admin
• Sauvegarder la sortie dans un dossier spécifique : alfa acquire -d /tmp/project_secret
• Récupérer uniquement les journaux d'un utilisateur spécifique : alfa acquire --user=inserer_nom_utilisateur
• Récupérer les journaux dans une période définie : alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z le format de l'heure est (RFC3339)

Maintenant que vous savez comment acquérir des données, il est temps pour des choses plus avancées pour libérer la puissance d'ALFA.

2. ALFA Analyze

La fonction d'analyse analyse automatiquement toutes les données des journaux d'audit pour un Google Workspace donné afin d'identifier une activité suspecte.

Comment cela fonctionne

1. Catégorisation Chaque événement individuel est catégorisé en fonction d'un mappage défini dans alfa/config/event_to_mitre.yml. Si un événement correspond à cette liste, il est mappé à une technique qui fait partie du cadre MITRE ATT&CK Cloud (https://attack.mitre.org/matrices/enterprise/cloud/).

2. Score Ensuite, ALFA analysera tous les événements mappés dans l'ordre chronologique pour tenter d'identifier des chaînes de destruction ou des chemins d'attaque logiques. Par ex. Un événement mappé à la phase Persistance suivi d'un événement mappé à la phase Accès aux identifiants entraînera un score plus élevé.

3. Résultat Finalement, ALFA fournira à l'analyste une liste de 'sous-chaînes' identifiées qui peuvent être analysées plus en détail.

Comment utiliser ALFA analyse ?

1. Exécutez d'abord alfa analyze qui identifiera automatiquement (ou non si aucune n'a été trouvée). Il vous placera également dans un shell où vous pourrez effectuer des activités de suivi.
2. Pour obtenir plus d'informations sur une sous-chaîne donnée, vous pouvez simplement exécuter A.subchains() qui vous montrera la chaîne en utilisant le format suivant (numero_du_premier_evenement_dans_la_chaine,numero_du_dernier_evenement_dans_la_chaine,score_de_chaine_de_destruction). Où un score de 1 signifie qu'une chaîne parfaite a été identifiée et plus il se rapproche de 0, plus la chaîne est faible.
3. Pour accéder aux événements suspects qui ont causé cette chaîne, utilisez A.aoi(export='activities.json') pour exporter toutes les sous-chaînes identifiées vers un fichier, que vous pourrez ensuite utiliser pour une analyse plus approfondie.

3. ALFA Load

Charger les données depuis le stockage local

Depuis le stockage local

Utilisez A = Alfa.load([nom_du_journal]) pour charger et analyser les journaux depuis le stockage local. Utilisez A = Alfa.load('all') pour charger tous les journaux. Par défaut, Alfa filtre les activités bénignes. Pour charger toutes les activités et événements, sans filtre, utilisez Alfa.load([nom_du_journal], filter=False).

Apporter des modifications

Ajouter de nouveaux mappages d'événements.

Il est possible de modifier directement le fichier config/event_to_mitre.yml, mais cela est déconseillé. La mise en page de ce fichier n'est pas intuitive. Au lieu de cela, envisagez d'apporter des modifications à utils/mappings.yml. Puis repeuplez config/event_to_mitre.yml en exécutant utils/event_mitre_remap.py

Modifier les méthodes de découverte de chaîne de destruction

La fonction de découverte de chaîne de destruction utilise des constantes codées en dur. Celles-ci se trouvent dans le fichier config/config.yml. Les analystes judiciaires sont invités à examiner les valeurs et à apporter des modifications pour leur espace de travail si nécessaire. Ces constantes sont responsables à la fois de la statistique de chaîne de destruction (kcs) et de la découverte de chaîne de destruction (sous-chaînes).

FAQ

Vous voulez en savoir plus sur les statistiques et l'algorithme utilisés pour ALFA ? Nous avons écrit un article de blog à ce sujet ici (https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92)

Erreurs connues

ValueError: missing config/credentials.json

Vous devez ajouter un fichier credentials.json au dossier du projet dans le sous-dossier 'config'. Instructions dans le fichier 'CREDENTIALS.md'.

OSError: [Errno 98] Address already in use

Cela signifie que le port 8089 est déjà utilisé par une autre application. Cela peut se produire si vous avez un serveur Web en cours d'exécution sur ce port et Splunk utilise également le port 8089 par défaut. La solution est d'arrêter (temporairement) l'utilisation de ce port car il est nécessaire pour le flux d'authentification que le port soit disponible.

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

Parfois, les informations d'autorisation doivent être mises à jour. Le moyen le plus simple est de supprimer le fichier 'token.json' du dossier project_name/config, puis de réexécuter la commande. Si cela pose toujours des problèmes, supprimez token.json et credentials.json et réenregistrez l'application OAuth comme décrit dans CREDENTIALS.MD

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

Assurez-vous d'avoir la barre oblique inversée (/) dans l'URI Authorized redirect URIs http://localhost:8089 de vos OAuth 2.0 Client IDs de l'application.