Eigenständiges SIGMA-basiertes Erkennungstool für EVTX-, Auditd-, Sysmon-für-Linux-, XML-, CSV- oder JSONL/NDJSON-Logs

Zircolite ist ein eigenständiges, in Python 3 geschriebenes Tool, mit dem Sie SIGMA-Regeln auf Folgendes anwenden können:

• MS-Windows-EVTX (EVTX-, XML- und JSONL-Formate)
• Auditd-Logs
• Sysmon für Linux
• EVTXtract
• CSV- und XML-Logs
• JSON-Array-Logs

Hauptfunktionen

• Automatische Erkennung des Logtyps: Erkennt Logformate und Zeitstempelfelder automatisch anhand von Magic Bytes, Inhaltsanalyse und Regex-basiertem Fallback – in den meisten Fällen müssen keine Formatflags angegeben werden.
• Mehrere Eingabeformate: Unterstützt verschiedene Logformate, darunter EVTX, JSON Lines, JSON-Arrays, CSV, XML und mehr. Komprimierte oder archivierte Logs (gzip, bzip2, ZIP, 7-Zip) werden unterstützt; für verschlüsselte ZIP/7z-Dateien --archive-password verwenden.
• Native Sigma-Unterstützung: Zircolite kann native Sigma-Regeln (YAML) direkt verwenden, indem sie mit pySigma konvertiert werden.
• SIGMA-Backend: Basiert auf einem SIGMA-Backend (SQLite) und verwendet keine interne SIGMA-zu-etwas-Konvertierung.
• Erweiterte Log-Manipulation: Kann Eingabelogs manipulieren, indem Felder aufgeteilt und Transformationen angewendet werden, was eine flexiblere und leistungsfähigere Log-Analyse ermöglicht.
• Feldtransformationen: Wendet während der Verarbeitung benutzerdefinierte Python-Transformationen auf Felder an (z. B. Base64-Dekodierung, Hex-zu-ASCII-Konvertierung).
• Flexibler Export: Zircolite kann Ergebnisse mit Jinja-Vorlagen in mehrere Formate exportieren, darunter JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator und mehr.
• Umfangreiche Terminalausgabe: Erkennungsergebnisse werden in nach Schweregrad sortierten Tabellen mit MITRE-ATT&CK-Technik-IDs, ATT&CK-Taktik-Heatmap, Regelabdeckungsmetriken und klickbaren Links zu Ausgabedateien angezeigt.

Sie können Zircolite direkt mit Python verwenden.

Die Dokumentation ist hier (eigene Website) oder hier (Repository-Verzeichnis) verfügbar.

Anforderungen / Installation

Das Projekt wurde mit Python 3.10 und höher getestet. Installieren Sie die Abhängigkeiten mit: pip3 install -r requirements.txt.

Abhängigkeiten

• Erforderlich: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr
• py7zr wird nur importiert, wenn eine -Eingabedatei geöffnet wird; ZIP, gzip und bzip2 verwenden die Standardbibliothek.

⚠️ Auf einigen Systemen (Mac, ARM usw.) erfordert die Python-Bibliothek evtx möglicherweise die Installation von Rust und Cargo.

Schnellstart

Schauen Sie sich (alte) Tutorials von anderen an (EN, ES und FR) hier.

EVTX-Dateien

Hilfe ist verfügbar mit:

python3 zircolite.py -h

Wenn Ihre EVTX-Dateien die Erweiterung ".evtx" haben:

# 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

Verwenden nativer Sigma-Regeln (YAML)

Sie können native Sigma-Regeln (YAML) direkt verwenden:

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

# Verzeichnis mit Sigma-Regeln
python3 zircolite.py --evtx sample.evtx --ruleset ./sigma/rules/windows/process_creation

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

Andere Logformate

Zircolite erkennt das Logformat in den meisten Fällen automatisch, daher sind explizite Formatflags optional:

# Automatische Erkennung (empfohlen) – Zircolite identifiziert das Format automatisch
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

# Explizite Formatflags (überschreiben die automatische Erkennung)
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

• Das Argument --events kann eine Datei oder ein Ordner sein. Bei einem Ordner werden alle Logdateien im aktuellen Ordner und in Unterordnern ausgewählt (mit --no-recursion deaktivierbar).
• Mit --file-pattern kann ein benutzerdefiniertes Glob-Muster für die Dateiauswahl angegeben werden.
• Mit --no-auto-detect kann die automatische Formaterkennung deaktiviert werden.

[!TIP] Wenn Sie das Tool ausprobieren möchten, können Sie es mit EVTX-ATTACK-SAMPLES (EVTX-Dateien) testen.

Ausführen mit Docker

# Docker-Image pullen
docker pull wagga40/zircolite:latest
# Wenn sich Ihre Logs und Regeln in einem bestimmten Verzeichnis befinden
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

• Ersetzen Sie $PWD durch das Verzeichnis (nur absoluter Pfad), in dem Ihre Logs und Regeln/Rulesets gespeichert sind.

Automatische Verarbeitungsoptimierung

Bei mehreren Dateien misst Zircolite diese anhand des verfügbaren RAM und der CPU, wählt einen Datenbankmodus (eine gemeinsame Datenbank oder eine pro Datei) und entscheidet, ob die parallele Verarbeitung sich lohnt – danach passt es die Anzahl der Worker bei laufendem Betrieb an den Speicherdruck an.

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

Überschreiben Sie all dies mit --no-auto-mode, --unified-db (eine Datenbank für alle Dateien, was für dateiübergreifende Korrelationsregeln erforderlich ist), --no-parallel oder --parallel-workers N. Siehe Automatische Verarbeitungsoptimierung, um zu erfahren, wie die Wahl getroffen wird.

Verwenden von YAML-Konfigurationsdateien

Für komplexe oder wiederholte Analyse-Workflows verwenden Sie eine YAML-Konfigurationsdatei:

# Eine vollständig kommentierte Konfigurationsdatei erzeugen
python3 zircolite.py --generate-config my_config.yaml

# Damit ausführen
python3 zircolite.py --yaml-config my_config.yaml

# CLI-Argumente überschreiben die Datei
python3 zircolite.py --yaml-config my_config.yaml --evtx ./other_logs/

Die generierte Datei dokumentiert jeden unterstützten Schlüssel; config/zircolite_example.yaml ist ein ausführliches Beispiel. Siehe YAML-Konfiguration für die Zusammenführungsregeln und die Optionen, die keine YAML-Entsprechung haben.

Aktualisieren der Standard-Rulesets

python3 zircolite.py -U

Alternativ, wenn Sie Task (go-task) verwenden, führen Sie task update-rules aus dem Projektstammverzeichnis aus, um die Rulesets aus Zircolite-Rules-v2 zu aktualisieren. Siehe Dokumentation für andere Aufgaben (Docker-Build, Bereinigung usw.).

[!IMPORTANT]
Bitte beachten Sie, dass diese Rulesets bereitgestellt werden, um Zircolite sofort nutzen zu können, aber Sie sollten Ihre eigenen Rulesets erstellen, da diese laut oder langsam sein können. Diese automatisch aktualisierten Rulesets sind im eigenen Repository verfügbar: Zircolite-Rules-v2.

Feldaufteilung und Transformationen

Zwei Konfigurationsfunktionen formen Ereignisse bei der Aufnahme, beide in config/config.yaml:

• Feldaufteilung wandelt ein gepacktes Schlüssel-Wert-Feld in abfragbare Felder um. Sysmons Hashes-Feld (SHA1=abc123,MD5=def456,SHA256=789xyz) wird zu separaten SHA1-, MD5- und SHA256-Feldern, sodass Regeln direkt einen Hash abgleichen können.
• Feldtransformationen führen sandboxiertes Python über den Wert eines Feldes aus – Base64-Befehlszeilen dekodieren, IOCs extrahieren, LOLBins markieren – und können das Ergebnis in ein neues Feld schreiben, statt das Original zu ersetzen. Zircolite enthält 55 solcher Transformationen in 11 Kategorien, standardmäßig deaktiviert, abgesehen von den beiden auditd-Transformationen.

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

Siehe Feldaufteilung und Feldtransformationen für die vollständige Konfiguration, die mitgelieferten Transformationen und wie Sie eigene testen können.

Dokumentation

Die vollständige Dokumentation ist hier verfügbar.

Mini-GUI

Die Mini-GUI kann vollständig offline verwendet werden. Sie ermöglicht die Anzeige und Suche in Ergebnissen. Sie können automatisch ein Mini-GUI-„Paket“ mit der Option --package erzeugen. Verwenden Sie --package-dir, um das Ausgabeverzeichnis anzugeben. Wie Sie die Mini-GUI verwenden, erfahren Sie in der Dokumentation hier.

Erkannte Ereignisse nach MITRE-ATT&CK®-Techniken und Kritikalitätsstufen

Zeitachse erkannter Ereignisse

Erkannte Ereignisse nach MITRE-ATT&CK®-Techniken, dargestellt auf der Matrix

Tutorials, Referenzen und verwandte Projekte

Tutorials

• Englisch: Russ McRee hat auf seinem Blog ein ausführliches Tutorial zu SIGMA und Zircolite veröffentlicht.

• Spanisch: César Marín hat ein Tutorial auf Spanisch hier veröffentlicht.

• Französisch: IT-connect.fr hat ein ausführliches Tutorial zu Zircolite auf Französisch veröffentlicht.

• Französisch: IT-connect.fr hat ebenfalls einen Hack-the-Box-Challenge-Write-up mit Zircolite veröffentlicht.

Referenzen

• Florian Roth hat Zircolite in seiner SIGMA Hall of Fame während seines Vortrags beim EU ATT&CK Workshop im Oktober 2021 erwähnt.
• Zircolite wurde während des JSAC 2023 zitiert und vorgestellt.
• Zircolite wurde in mehreren wissenschaftlichen Arbeiten zitiert und verwendet:
  • CIDRE-Team:
    • PWNJUTSU - Website
    • PWNJUTSU - wissenschaftliche Arbeit
    • 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

Lizenz

• Der gesamte Code des Projekts ist unter der GNU Lesser General Public License lizenziert.
• evtx_dump steht unter der MIT-Lizenz.
• Die Regeln sind unter der Detection Rule License (DRL) 1.0 veröffentlicht.