ALFA

Analisi Forense Automatica dei Log di Audit per Google Workspace

Copyright (c) 2026 Invictus Incident Response
Autori originali Greg Charitonos & BertJanCyber mantenuto da Invictus Incident Response

Prima di iniziare

Una nota sui sistemi operativi supportati: ALFA è testato su diverse distribuzioni Linux (Debian e Ubuntu).
Sebbene sia possibile utilizzarlo su Windows o macOS, i risultati possono variare, quindi procedi a tuo rischio.

Installazione

1. Scarica questo progetto
2. Naviga nella cartella nel tuo terminale ed esegui sudo pip install -e . o sudo pip3 install -e .

Installazione su macOS

1. Installa Python 3.9 usando pyenv ALFA funziona meglio con Python 3.9. Puoi usare pyenv per gestire e installare questa versione.

   • Se non hai ancora installato pyenv, puoi farlo usando Homebrew:
     root@kitploit:~

     brew install pyenv
     

   • Configura pyenv nella tua shell aggiungendo quanto segue al file di configurazione della shell (es. ~/.zshrc o ~/.bashrc):
     root@kitploit:~

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

     Dopo aver aggiornato il file, ricarica la shell:
     root@kitploit:~

     source ~/.zshrc  # o source ~/.bashrc
     

   • Installa Python 3.9 usando pyenv:
     root@kitploit:~

     pyenv install 3.9
     

   • Imposta Python 3.9 come versione corrente:
     root@kitploit:~

     pyenv global 3.9
     

     o solo per la sessione corrente:
   root@kitploit:~

    pyenv shell 3.9
   

2. (Opzionale) Crea un ambiente virtuale È buona pratica eseguire i progetti in un ambiente virtuale per mantenere isolate le dipendenze. Usando la versione 3.9 di Python che hai appena impostato, crea un ambiente virtuale:

   root@kitploit:~

   python -m venv alfa
   

   • Attiva l'ambiente virtuale:
     root@kitploit:~

     source alfa/bin/activate
     

3. Installa ALFA All'interno della cartella dove si trova il progetto ALFA, installalo usando pip:

   root@kitploit:~

   pip install -e .
   

   Se non stai usando un ambiente virtuale, potresti aver bisogno di sudo:

   root@kitploit:~

   sudo pip install -e .
   

4. Verifica l'installazione Dopo l'installazione, puoi verificare che ALFA sia installato provando a eseguire il suo strumento a riga di comando alfa.

Usare ALFA

NOTA: Per recuperare il file credentials.json, consulta CREDENTIALS.md

Configurazione

1. Il primo passo è inizializzare ALFA eseguendo alfa init nomeprogetto; questo comando creerà una nuova directory per archiviare la tua configurazione e i dati. Es. alfa init progetto_x
2. È stato ora generato un nuovo progetto chiamato 'progetto_x'. All'interno di quella cartella, copia il tuo credentials.json nella cartella config/. **(Consulta CREDENTIALS.md) per le istruzioni. **
3. Dopo aver copiato il file credentials.json, sei pronto per usare ALFA.

ALFA ha 3 opzioni come spiegato di seguito:

1. ALFA Acquisisci

Acquisisci tutti i log di audit di Google Workspace

1. Dall'interno di "progetto_x" (o qualsiasi nome tu abbia scelto prima) esegui alfa acquire
2. ALFA raccoglierà ora tutti i tipi di log per tutti gli utenti e li salverà in una sottodirectory nella cartella 'data'; verrà generato un file .json per ogni tipo di log
3. Per vedere quali altre opzioni hai, digita alfa acquire -h

Acquisizioni avanzate con ALFA

Puoi fare vari tipi di filtraggio per limitare i dati che stai acquisendo; alcuni esempi qui sotto:

• Prendere solo il tipo di log 'admin' alfa acquire --logtype=admin
• Salvare l'output in una cartella specifica alfa acquire -d /tmp/progetto_segreto
• Prendere solo i log per un utente specifico alfa acquire --user=inserisci_username
• Prendere i log in un intervallo di tempo definito alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z il formato dell'ora è (RFC3339)

Ora sai come acquisire i dati: è ora di cose più interessanti per scatenare la potenza di ALFA.

2. ALFA Analizza

La funzione di analisi analizza automaticamente tutti i dati dei log di audit per un dato Google Workspace per identificare attività sospette.

Come funziona

1. Categorizzazione Ogni singolo evento viene categorizzato in base a una mappatura definita in alfa/config/event_to_mitre.yml. Se un evento corrisponde a quelle liste, viene mappato a una tecnica che fa parte del framework MITRE ATT&CK Cloud (https://attack.mitre.org/matrices/enterprise/cloud/).

2. Punteggio Successivamente ALFA analizzerà tutti gli eventi mappati in ordine cronologico per cercare di identificare kill chain o percorsi di attacco logici. Ad esempio, un evento mappato alla fase di Persistenza seguito da un evento mappato alla fase di Accesso alle Credenziali risulterà in un punteggio più alto.

3. Risultato Alla fine ALFA fornirà all'analista un elenco di 'sottocatene' identificate che possono essere ulteriormente analizzate.

Come usare ALFA analizza?

1. Prima esegui alfa analyze che automaticamente identificherà (o meno se non ne vengono trovati). Ti porterà anche in una shell dove puoi eseguire attività di follow-up.
2. Per ottenere maggiori informazioni su una data sottocatena, puoi semplicemente eseguire A.subchains() che ti mostrerà la catena usando il seguente formato (numero_del_primo_evento_nella_catena,numero_dell'ultimo_evento_nella_catena,punteggio_killchain). Dove un punteggio 1 significa che è stata identificata una catena perfetta e più si avvicina a 0 più la catena è debole.
3. Per accedere agli eventi sospetti che hanno causato questa catena, usa A.aoi(export='activities.json') per esportare tutte le sottocatene identificate in un file, che potrai poi usare per ulteriori analisi.

3. ALFA Carica

Carica dati dall'archivio locale

Dall'archivio locale

Usa A = Alfa.load([nome_log]) per caricare e analizzare i log dall'archivio locale. Usa A = Alfa.load('all') per caricare tutti i log. Alfa filtra le attività benigne per impostazione predefinita. Per caricare tutte le attività e gli eventi, senza filtri, usa Alfa.load([nome_log], filter=False).

Apportare modifiche

Aggiungere nuove mappature di eventi.

È possibile modificare direttamente il file config/event_to_mitre.yml, ma è sconsigliato. La struttura di questo file non è intuitiva. Invece, considera di apportare modifiche a utils/mappings.yml. Poi ripopola config/event_to_mitre.yml eseguendo utils/event_mitre_remap.py

Modificare i metodi di scoperta della Kill Chain

La funzione di scoperta della kill chain utilizza costanti hard-coded. Queste si trovano nel file config/config.yml. Si consiglia agli analisti forensi di rivedere i valori e apportare le modifiche necessarie per il proprio workspace. Queste costanti sono responsabili sia della statistica della kill chain (kcs) che della scoperta della kill chain (sottocatene).

FAQ

Vuoi saperne di più sulle statistiche e l'algoritmo usati da ALFA? Abbiamo scritto un post sul blog qui (https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92)

Errori noti

ValueError: missing config/credentials.json

Devi aggiungere un file credentials.json alla cartella del progetto nella sottodirectory 'config'. Istruzioni nel file 'CREDENTIALS.md'.

OSError: [Errno 98] Address already in use

Questo significa che la porta 8089 è già in uso da un'altra applicazione; questo potrebbe accadere se hai un server web in esecuzione su questa porta e anche Splunk usa la porta 8089 per impostazione predefinita. La soluzione è fermare (temporaneamente) l'uso di quella porta poiché è necessaria per il flusso di autenticazione che la porta sia disponibile.

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

A volte le informazioni di autorizzazione devono essere aggiornate; il modo più semplice per farlo è rimuovere il file 'token.json' dalla cartella nome_progetto/config. E poi rieseguire il comando. Se il problema persiste, rimuovi token.json e credentials.json e riregistra l'applicazione OAuth come descritto in CREDENTIALS.MD

Accesso bloccato: la richiesta di questa app non è valida // Errore 400: redirect_uri_mismatch

Assicurati di avere la barra finale (/) nell'URI Authorized redirect URIs http://localhost:8089 dell'applicazione nei tuoi OAuth 2.0 Client IDs.