Strumento di rilevamento autonomo basato su SIGMA per log EVTX, Auditd, Sysmon for Linux, XML, CSV o JSONL/NDJSON

Zircolite è uno strumento autonomo scritto in Python 3 che consente di utilizzare le regole SIGMA su:

• Eventi EVTX di MS Windows (formati EVTX, XML e JSONL)
• Log di Auditd
• Sysmon per Linux
• EVTXtract
• Log CSV e XML
• Log in array JSON

Caratteristiche principali

• Rilevamento automatico del tipo di log: Identifica automaticamente i formati di log e i campi timestamp utilizzando magic bytes, analisi del contenuto e fallback basato su regex -- nella maggior parte dei casi non è necessario specificare flag di formato.
• Multipli formati di input: Supporta vari formati di log, tra cui EVTX, JSON Lines, array JSON, CSV, XML e altri. Sono supportati log compressi o archivi (gzip, bzip2, ZIP, 7-Zip); usa --archive-password per ZIP/7z cifrati.
• Supporto nativo per Sigma: Zircolite può utilizzare direttamente regole Sigma native (YAML) convertendole con pySigma.
• Backend SIGMA: Si basa su un backend SIGMA (SQLite) e non utilizza conversioni interne da SIGMA a qualcos'altro.
• Manipolazione avanzata dei log: Può manipolare i log di input suddividendo i campi e applicando trasformazioni, consentendo un'analisi dei log più flessibile e potente.
• Trasformazioni dei campi: Applica trasformazioni Python personalizzate ai campi durante l'elaborazione (ad es. decodifica Base64, conversione hex-to-ASCII).
• Esportazione flessibile: Zircolite può esportare i risultati in più formati utilizzando template Jinja, tra cui JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator e altri.
• Output ricco nel terminale: Risultati di rilevamento visualizzati in tabelle ordinate per gravità con ID delle tecniche MITRE ATT&CK, mappa di calore delle tattiche ATT&CK, metriche di copertura delle regole e collegamenti cliccabili ai file di output.

Puoi usare Zircolite direttamente con Python.

La documentazione è disponibile qui (sito dedicato) o qui (directory del repository).

Requisiti / Installazione

Il progetto è stato testato con Python 3.10 e versioni successive. Installa le dipendenze con: pip3 install -r requirements.txt.

Dipendenze

• Richiesti: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr
• py7zr viene importato solo quando viene aperto un input ; ZIP, gzip e bzip2 usano la libreria standard.

⚠️ Su alcuni sistemi (Mac, ARM, ecc.), la libreria Python evtx potrebbe richiedere l'installazione di Rust e Cargo.

Avvio rapido

Dai un'occhiata ai (vecchi) tutorial realizzati da altri (EN, ES e FR) qui.

File EVTX

La guida è disponibile con:

python3 zircolite.py -h

Se i tuoi file EVTX hanno estensione ".evtx":

# python3 zircolite.py --evtx <EVTX FOLDER or EVTX FILE> --ruleset <SIGMA RULESET> [--ruleset <OTHER RULESET>]
python3 zircolite.py --evtx sysmon.evtx --ruleset rules/rules_windows_merged.json

Utilizzo di regole Sigma native (YAML)

Puoi usare direttamente regole Sigma native (YAML):

# Single YAML rule
python3 zircolite.py --evtx sample.evtx --ruleset path/to/rule.yml

# Directory of Sigma rules
python3 zircolite.py --evtx sample.evtx --ruleset ./sigma/rules/windows/process_creation

# With pySigma pipelines
python3 zircolite.py --evtx sample.evtx --ruleset rule.yml --pipeline sysmon --pipeline windows-logsources

Altri formati di log

Zircolite rileva automaticamente il formato del log nella maggior parte dei casi, quindi i flag di formato espliciti sono opzionali:

# Auto-detection (recommended) - Zircolite identifies the format automatically
python3 zircolite.py --events auditd.log --ruleset rules/rules_linux.json
python3 zircolite.py --events sysmon.log --ruleset rules/rules_linux.json
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json

# Explicit format flags (override auto-detection)
python3 zircolite.py --events auditd.log --ruleset rules/rules_linux.json --auditd
python3 zircolite.py --events sysmon.log --ruleset rules/rules_linux.json --sysmon4linux
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --jsononly
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --json-array
python3 zircolite.py --events <CSV_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --csv-input
python3 zircolite.py --events <XML_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --xml-input

• L'argomento --events può essere un file o una cartella. Se si tratta di una cartella, verranno selezionati tutti i file di log nella cartella corrente e nelle sottocartelle (usa --no-recursion per disabilitare).
• Usa --file-pattern per specificare un pattern glob personalizzato per la selezione dei file.
• Usa --no-auto-detect per disabilitare il rilevamento automatico del formato.

[!TIP] Se vuoi provare lo strumento, puoi testarlo con EVTX-ATTACK-SAMPLES (file EVTX).

Esecuzione con Docker

# Pull the Docker image
docker pull wagga40/zircolite:latest
# If your logs and rules are in a specific directory
docker run --rm --tty \
    -v $PWD:/case/input:ro \
    -v $PWD:/case/output \
    wagga40/zircolite:latest \
    -e /case/input \
    -o /case/output/detected_events.json \
    -r /case/input/a_sigma_rule.yml

• Sostituisci $PWD con la directory (solo percorso assoluto) in cui sono salvati i tuoi log e le regole/ruleset.

Ottimizzazione automatica dell'elaborazione

Dati più file, Zircolite li confronta con la RAM e la CPU disponibili, sceglie una modalità di database (un database condiviso o uno per file) e stabilisce se vale la pena elaborarli in parallelo — adattando poi il numero di worker alla pressione sulla memoria durante l'esecuzione.

python3 zircolite.py --evtx ./logs/ --ruleset rules/rules_windows_merged.json

Puoi sovrascrivere tutto con --no-auto-mode, --unified-db (un database per tutti i file, che è ciò di cui hanno bisogno le regole di correlazione tra file), --no-parallel o --parallel-workers N. Consulta Ottimizzazione automatica dell'elaborazione per capire come viene effettuata la scelta.

Utilizzo di file di configurazione YAML

Per flussi di lavoro di analisi complessi o ripetuti, usa un file di configurazione YAML:

# Generate a fully commented configuration file
python3 zircolite.py --generate-config my_config.yaml

# Run with it
python3 zircolite.py --yaml-config my_config.yaml

# CLI arguments override the file
python3 zircolite.py --yaml-config my_config.yaml --evtx ./other_logs/

Il file generato documenta ogni chiave supportata; config/zircolite_example.yaml è un esempio pratico. Consulta configurazione YAML per le regole di unione e le opzioni che non hanno un equivalente YAML.

Aggiornamento delle ruleset predefinite

python3 zircolite.py -U

In alternativa, se usi Task (go-task), esegui task update-rules dalla radice del progetto per aggiornare le regole da Zircolite-Rules-v2. Consulta docs per altre attività (build Docker, pulizia, ecc.).

[!IMPORTANT]
Tieni presente che queste ruleset sono fornite per usare Zircolite pronte all'uso, ma dovresti generare le tue ruleset poiché possono essere rumorose o lente. Queste ruleset aggiornate automaticamente sono disponibili nel repository dedicato: Zircolite-Rules-v2.

Suddivisione dei campi e trasformazioni

Due funzionalità di configurazione modellano gli eventi durante l'acquisizione, entrambe in config/config.yaml:

• Suddivisione dei campi trasforma un campo chiave-valore compatto in campi interrogabili. Il campo Hashes di Sysmon (SHA1=abc123,MD5=def456,SHA256=789xyz) diventa campi SHA1, MD5 e SHA256 separati, così le regole possono corrispondere direttamente a un hash.
• Trasformazioni dei campi eseguono Python in sandbox sul valore di un campo — decodifica di righe di comando in base64, estrazione di IOC, segnalazione di LOLBins — e possono scrivere il risultato in un nuovo campo invece di sostituire l'originale. Zircolite ne include 55 in 11 categorie, disattivate per impostazione predefinita tranne le due per auditd.

split:
  Hashes:
    separator: ","
    equal: "="

Consulta Suddivisione dei campi e Trasformazioni dei campi per la configurazione completa, le trasformazioni incluse in Zircolite e come testare le tue.

Documentazione

La documentazione completa è disponibile qui.

Mini-GUI

La Mini-GUI può essere utilizzata completamente offline. Consente di visualizzare e cercare i risultati. Puoi generare automaticamente un "pacchetto" Mini-GUI con l'opzione --package. Usa --package-dir per specificare la directory di output. Per imparare a usare la Mini-GUI, consulta la documentazione qui.

Eventi rilevati per tecniche MITRE ATT&CK® e livelli di criticità

Timeline degli eventi rilevati

Eventi rilevati per tecniche MITRE ATT&CK® visualizzati sulla matrice

Tutorial, riferimenti e progetti correlati

Tutorial

• Inglese: Russ McRee ha pubblicato un tutorial dettagliato su SIGMA e Zircolite sul suo blog.

• Spagnolo: César Marín ha pubblicato un tutorial in spagnolo qui.

• Francese: IT-connect.fr ha pubblicato un tutorial completo su Zircolite in francese.

• Francese: IT-connect.fr ha anche pubblicato un write-up della challenge Hack the Box utilizzando Zircolite.

Riferimenti

• Florian Roth ha citato Zircolite nella sua SIGMA Hall of Fame durante il suo intervento all'EU ATT&CK Workshop di ottobre 2021.
• Zircolite è stato citato e presentato durante il JSAC 2023.
• Zircolite è stato citato e utilizzato in diversi articoli di ricerca:
  • Team CIDRE:
    • PWNJUTSU - Sito web
    • PWNJUTSU - Articolo accademico
    • CERBERE: Cybersecurity Exercise for Red and Blue Team Entertainment, Reproducibility
  • Universidad de la República:
    • A Process Mining-Based Method for Attacker Profiling Using the MITRE ATT&CK Taxonomy

Licenza

• Tutto il codice del progetto è concesso in licenza sotto la GNU Lesser General Public License.
• evtx_dump è sotto licenza MIT.
• Le regole sono rilasciate sotto la Detection Rule License (DRL) 1.0.