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

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

• MS Windows EVTX (formati EVTX, XML e JSONL)
• Log Auditd
• Sysmon per Linux
• EVTXtract
• Log CSV e XML
• Log JSON Array

Caratteristiche principali

• Veloce: 452.554 eventi contro 4.319 regole Sigma in 11,6 s — 2,1× più veloce di Hayabusa e 9,8× più veloce di Chainsaw sugli stessi log, entrambi strumenti scritti in Rust. Vedi il benchmark.
• 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.
• Molteplici formati di input: supporta vari formati di log tra cui EVTX, JSON Lines, JSON Arrays, CSV, XML e altri. Sono supportati log compressi o archiviati (gzip, bzip2, ZIP, 7-Zip); usa --archive-password per ZIP/7z cifrati.
• Supporto nativo Sigma: Zircolite può utilizzare direttamente le 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 esempio, decodifica Base64, conversione da hex ad ASCII).
• Esportazione flessibile: Zircolite può esportare i risultati in molteplici formati utilizzando template Jinja, tra cui JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator e altri.
• Output terminale avanzato: i risultati del rilevamento vengono visualizzati in tabelle ordinate per severità con ID delle tecniche MITRE ATT&CK, heatmap delle tattiche ATT&CK, metriche di copertura delle regole e link cliccabili ai file di output.

Puoi utilizzare Zircolite direttamente con Python, oppure scaricare un binario standalone che non richiede l'installazione di Python.

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

Requisiti / Installazione

[!NOTE] Tutto ciò che è contenuto in questa sezione si applica solo quando si esegue Zircolite dal codice sorgente. I binari standalone e l'immagine Docker includono il proprio Python, tutte le dipendenze e il kernel compilato: non richiedono Python, né un package manager, né un compilatore C.

Il progetto è stato testato con Python 3.10 e versioni successive. Le dipendenze sono dichiarate in pyproject.toml; installale dal repository clonato con PDM (pdm install), uv (uv sync) o Poetry (poetry install).

Gli esempi seguenti eseguono python3 zircolite.py: attiva l'ambiente creato dallo strumento, oppure anteponi pdm run, uv run o poetry run.

Dipendenze

• Obbligatorie: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr viene importato solo quando si apre un input .7z; ZIP, gzip e bzip2 utilizzano la libreria standard.

⚠️ Installa prima un compilatore C

L'installazione dal sorgente compila il kernel di flattening di Zircolite con Cython — ma solo se è già presente un compilatore C. Senza di esso l'installazione riesce comunque e ogni esecuzione appiattisce gli eventi in Python, il che è più lento. I binari e l'immagine Docker sono costruiti con il kernel già compilato, quindi questo non li riguarda.

Quindi installa la toolchain prima di pdm install:

Cython stesso non necessita di installazione: è un requisito di build, recuperato in un ambiente di build isolato e mai aggiunto al tuo ambiente.

Binari standalone

Ogni release pubblica un pacchetto autocontenuto per piattaforma. Ognuno include il proprio Python e tutte le dipendenze, quindi non deve essere installato nulla in anticipo.

I Mac Intel e le distribuzioni basate su musl come Alpine non hanno un binario; in quei casi usa Python o Docker.

unzip Zircolite-<version>-linux-x64.zip
cd Zircolite-<version>-linux-x64
./Zircolite --events sysmon.evtx --ruleset rules/rules_windows_merged.json

Negli esempi seguenti, sostituisci python3 zircolite.py con il percorso dell'eseguibile.

I binari non sono firmati digitalmente. macOS mette in quarantena un download effettuato con un browser, i file estratti ereditano il flag, e Gatekeeper blocca quindi l'eseguibile e ogni libreria in _internal/. Rimuovilo dall'intera directory, ricorsivamente, prima della prima esecuzione:

xattr -dr com.apple.quarantine Zircolite-<version>-macos-arm64

Avvio rapido

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

File EVTX

L'aiuto è disponibile con:

# Don't forget to prefix with "pdm run" or "uv run" or "poetry run" when needed
python3 zircolite.py -h

Se i tuoi file EVTX hanno l'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

--ruleset può essere omesso: in tal caso Zircolite utilizza rules/rules_windows_merged.json, che copre Sysmon e i canali Windows generici.

Utilizzo delle regole Sigma native (YAML)

Puoi utilizzare direttamente le 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

--pipeline-list mostra le pipeline installate. Indicarne una non installata interrompe l'esecuzione con codice di uscita 2, prima che qualsiasi regola venga convertita.

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 è 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 archiviati i tuoi log e le regole/ruleset.
• Su un host Linux, aggiungi --user "$(id -u):$(id -g)" e -l /case/output/zircolite.log: l'immagine viene eseguita come utente non privilegiato che non può scrivere in una directory di tua proprietà. Vedi Docker.

Ottimizzazione automatica dell'elaborazione

Dati diversi file, Zircolite li valuta rispetto alla RAM e alla CPU disponibili, sceglie una modalità database (un database condiviso, o uno per file) e decide se vale la pena elaborarli in parallelo — poi adatta il numero di worker alla pressione di memoria durante l'esecuzione.

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

Sovrascrivi qualsiasi impostazione con --no-auto-mode, --unified-db (un database per tutti i file, necessario per le regole di correlazione cross-file), --no-parallel o --parallel-workers N. Vedi Automatic Processing Optimization per come viene effettuata la scelta.

Utilizzo dei 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 al suo valore predefinito; config/zircolite_example.yaml è lo stesso file, mantenuto nel repository. Vedi YAML configuration per le regole di merge e le opzioni che non hanno un equivalente YAML.

Aggiornamento dei ruleset predefiniti

python3 zircolite.py -U

Dal sorgente questo riscrive la directory rules/ del repository. Un binario standalone scrive nella directory rules/ accanto al suo eseguibile, e ripiega su ./rules nella directory di lavoro, con un avviso, quando non è possibile scrivervi.

In alternativa, se usi Task (go-task), esegui task update-rules dalla radice del progetto per aggiornare le regole da Zircolite-Rules-v2. Vedi docs per altri task (build Docker, clean, ecc.).

[!IMPORTANT]
Tieni presente che questi ruleset sono forniti per utilizzare Zircolite out of the box, ma dovresti generare i tuoi ruleset poiché possono essere rumorosi o lenti. Questi ruleset aggiornati 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:

• La 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 separati SHA1, MD5 e SHA256, così le regole possono corrispondere direttamente a un hash.
• Le trasformazioni dei campi eseguono Python in sandbox sul valore di un campo — decodificando command line in base64, estraendo IOC, segnalando LOLBin — 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: "="

Vedi Field Splitting e Field Transforms per la configurazione completa, le trasformazioni incluse in Zircolite e come testare le tue.

Benchmark

Zircolite è il più veloce dei tre: 2,1× più veloce di Hayabusa e 9,8× più veloce di Chainsaw — ed è l'unico dei tre scritto in Python, contro due strumenti scritti in Rust.

Gli stessi 4 file Sysmon EVTX (478 MB, 452.554 eventi), ogni strumento con le impostazioni predefinite e le proprie regole, su un Apple M1 Max a 10 core. Mediana di tre esecuzioni:

Zircolite scambia memoria per quella velocità: esegue un processo worker per file, e la cifra sopra è il loro totale. --no-parallel lo mantiene a un singolo processo.

I set di regole differiscono, quindi i conteggi dei rilevamenti non sono comparabili; vedi Benchmark per la configurazione, le avvertenze e come riprodurlo con tools/tool-benchmark.py.

Documentazione

La documentazione completa è disponibile qui.

Mini-GUI

La Mini-GUI può essere utilizzata completamente offline. Ti permette 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 come 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 dettagliato tutorial 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 ampio tutorial 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 JSAC 2023.
• Zircolite è stato citato e utilizzato in molteplici paper di ricerca:
  • CIDRE Team:
    • PWNJUTSU - Website
    • PWNJUTSU - Academic Paper
    • 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 è rilasciato sotto la GNU Lesser General Public License.
• Il parsing EVTX utilizza evtx (pyevtx-rs), sotto licenza MIT o Apache-2.0. I pacchetti di release elencano ogni libreria inclusa e la sua licenza in THIRD_PARTY_LICENSES.
• Le regole sono rilasciate sotto la Detection Rule License (DRL) 1.1.