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

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

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

Hauptmerkmale

• Schnell: 452.554 Ereignisse gegen 4.319 Sigma-Regeln in 11,6 s — 2,1× schneller als Hayabusa und 9,8× schneller als Chainsaw bei denselben Logs, beides Rust-Tools. Siehe den Benchmark.
• Automatische Log-Typ-Erkennung: Identifiziert Log-Formate und Zeitstempel-Felder automatisch anhand von Magic Bytes, Inhaltsanalyse und regex-basiertem Fallback -- in den meisten Fällen sind keine Format-Flags erforderlich.
• Mehrere Eingabeformate: Unterstützt verschiedene Log-Formate, darunter EVTX, JSON Lines, JSON Arrays, CSV, XML und mehr. Komprimierte oder archivierte Logs (gzip, bzip2, ZIP, 7-Zip) werden unterstützt; verwenden Sie --archive-password für verschlüsselte ZIP/7z.
• Native Sigma-Unterstützung: Zircolite kann native Sigma-Regeln (YAML) direkt verwenden, indem sie mit pySigma konvertiert werden.
• SIGMA-Backend: Es basiert auf einem SIGMA-Backend (SQLite) und verwendet keine interne SIGMA-zu-etwas-Konvertierung.
• Erweiterte Log-Manipulation: Es kann Eingabe-Logs durch Aufteilen von Feldern und Anwenden von Transformationen manipulieren, was eine flexiblere und leistungsfähigere Log-Analyse ermöglicht.
• Feldtransformationen: Wenden Sie benutzerdefinierte Python-Transformationen auf Felder während der Verarbeitung an (z. B. Base64-Dekodierung, Hex-zu-ASCII-Konvertierung).
• Flexibler Export: Zircolite kann Ergebnisse in mehrere Formate exportieren, indem es Jinja-Vorlagen verwendet, darunter JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator und mehr.
• Reichhaltige Terminal-Ausgabe: Erkennungsergebnisse werden in nach Schweregrad sortierten Tabellen mit MITRE ATT&CK-Technik-IDs, ATT&CK-Taktik-Heatmap, Regelabdeckungsmetriken und anklickbaren Links zu Ausgabedateien angezeigt.

Sie können Zircolite direkt mit Python verwenden oder eine eigenständige Binärdatei herunterladen, die keine Python-Installation erfordert.

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

Anforderungen / Installation

[!NOTE] Alles in diesem Abschnitt gilt nur beim Ausführen von Zircolite aus dem Quellcode. Die eigenständigen Binärdateien und das Docker-Image bringen ihr eigenes Python, jede Abhängigkeit und den kompilierten Kernel mit: Sie benötigen kein Python, keinen Paketmanager und keinen C-Compiler.

Das Projekt wurde mit Python 3.10 und höher getestet. Abhängigkeiten sind in pyproject.toml deklariert; installieren Sie sie aus dem geklonten Repository mit PDM (pdm install), uv (uv sync) oder Poetry (poetry install).

Die folgenden Beispiele führen python3 zircolite.py aus: Aktivieren Sie die vom Tool erstellte Umgebung, oder stellen Sie ihnen pdm run, uv run oder poetry run voran.

Abhängigkeiten

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

⚠️ Installieren Sie zuerst einen C-Compiler

Die Installation aus dem Quellcode kompiliert Zircolites Flattening-Kernel mit Cython — aber nur, wenn bereits ein C-Compiler vorhanden ist. Ohne einen solchen ist die Installation trotzdem erfolgreich, und jeder Lauf flacht Ereignisse stattdessen in Python ab, was langsamer ist. Die Binärdateien und das Docker-Image werden mit bereits kompiliertem Kernel erstellt, daher betrifft dies sie nicht.

Installieren Sie also die Toolchain vor pdm install:

Cython selbst muss nicht installiert werden: Es ist eine Build-Time-Anforderung, die in eine isolierte Build-Umgebung geholt und niemals zu Ihrer Umgebung hinzugefügt wird.

Eigenständige Binärdateien

Jede Version veröffentlicht ein eigenständiges Paket pro Plattform. Jedes bringt sein eigenes Python und jede Abhängigkeit mit, sodass nichts zuerst installiert werden muss.

Intel-Macs und musl-basierte Distributionen wie Alpine haben keine Binärdatei; verwenden Sie dort Python oder Docker.

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

Ersetzen Sie in den folgenden Beispielen python3 zircolite.py durch den Pfad zur ausführbaren Datei.

Die Binärdateien sind nicht codesigniert. macOS unter Quarantäne stellt einen mit einem Browser heruntergeladenen Download unter Quarantäne, die entpackten Dateien erben das Flag, und Gatekeeper blockiert dann die ausführbare Datei und jede Bibliothek in _internal/. Entfernen Sie es aus dem gesamten Verzeichnis, rekursiv, vor dem ersten Lauf:

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

Schnellstart

Sehen Sie sich (alte) Tutorials an, die von anderen erstellt wurden (EN, ES und FR) hier.

EVTX-Dateien

Hilfe ist verfügbar mit:

# Don't forget to prefix with "pdm run" or "uv run" or "poetry run" when needed
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

--ruleset kann weggelassen werden: Zircolite verwendet dann rules/rules_windows_merged.json, was Sysmon und die generischen Windows-Kanäle abdeckt.

Verwenden nativer Sigma-Regeln (YAML)

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

# 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 zeigt die installierten Pipelines. Die Angabe einer nicht installierten beendet den Lauf mit Exit-Code 2, bevor eine Regel konvertiert wird.

Andere Log-Formate

Zircolite erkennt das Log-Format in den meisten Fällen automatisch, daher sind explizite Format-Flags optional:

# 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

• Das Argument --events kann eine Datei oder ein Ordner sein. Wenn es ein Ordner ist, werden alle Log-Dateien im aktuellen Ordner und in Unterordnern ausgewählt (verwenden Sie --no-recursion, um dies zu deaktivieren).
• Verwenden Sie --file-pattern, um ein benutzerdefiniertes Glob-Muster für die Dateiauswahl anzugeben.
• Verwenden Sie --no-auto-detect, um die automatische Formaterkennung zu deaktivieren.

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

Ausführen mit 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

• Ersetzen Sie $PWD durch das Verzeichnis (nur absoluter Pfad), in dem Ihre Logs und Regeln/Rulesets gespeichert sind.
• Fügen Sie auf einem Linux-Host --user "$(id -u):$(id -g)" und -l /case/output/zircolite.log hinzu: Das Image läuft als unprivilegierter Benutzer, der nicht in ein Verzeichnis schreiben kann, das Ihnen gehört. Siehe Docker.

Automatische Verarbeitungsoptimierung

Bei mehreren Dateien misst Zircolite sie gegen verfügbaren RAM und CPU, wählt einen Datenbankmodus (eine gemeinsame Datenbank oder eine pro Datei) und entscheidet, ob sich eine parallele Verarbeitung lohnt — und passt dann die Worker-Anzahl während der Ausführung an den Speicherdruck an.

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

Überschreiben Sie dies mit --no-auto-mode, --unified-db (eine Datenbank für alle Dateien, was dateiübergreifende Korrelationsregeln benötigen), --no-parallel oder --parallel-workers N. Siehe Automatische Verarbeitungsoptimierung für die Art und Weise, wie die Wahl getroffen wird.

Verwenden von YAML-Konfigurationsdateien

Verwenden Sie für komplexe oder wiederholte Analyse-Workflows eine YAML-Konfigurationsdatei:

# 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/

Die generierte Datei dokumentiert jeden unterstützten Schlüssel mit seinem Standardwert; config/zircolite_example.yaml ist dieselbe Datei, die im Repository gepflegt wird. Siehe YAML-Konfiguration für die Merge- Regeln und die Optionen, die kein YAML-Äquivalent haben.

Aktualisieren der Standard-Rulesets

python3 zircolite.py -U

Aus dem Quellcode schreibt dies das rules/-Verzeichnis des Repositorys neu. Eine eigenständige Binärdatei schreibt in das rules/-Verzeichnis neben ihrer ausführbaren Datei und fällt auf ./rules im Arbeitsverzeichnis zurück, mit einer Warnung, wenn in dieses nicht geschrieben werden kann.

Alternativ können Sie, wenn Sie Task (go-task) verwenden, task update-rules vom Projektstamm aus ausführen, um Regeln von Zircolite-Rules-v2 zu aktualisieren. Siehe docs für andere Tasks (Docker-Build, Clean usw.).

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

Feldaufteilung und Transformationen

Zwei Konfigurationsfunktionen formen Ereignisse während ihrer Erfassung, beide in config/config.yaml:

• Feldaufteilung verwandelt ein gepacktes Schlüssel-Wert-Feld in abfragbare Felder. Sysmons Hashes-Feld (SHA1=abc123,MD5=def456,SHA256=789xyz) wird zu separaten SHA1-, MD5- und SHA256-Feldern, sodass Regeln direkt auf einen Hash passen können.
• Feldtransformationen führen sandboxed Python über den Wert eines Feldes aus — Dekodieren von Base64-Kommandozeilen, Extrahieren von IOCs, Markieren von LOLBins — und können das Ergebnis in ein neues Feld schreiben, anstatt das Original zu ersetzen. Zircolite liefert 55 davon in 11 Kategorien, standardmäßig deaktiviert außer den beiden auditd-Transformationen.

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

Siehe Feldaufteilung und Feldtransformationen für die vollständige Konfiguration, die von Zircolite mitgelieferten Transformationen und wie Sie Ihre eigenen testen.

Benchmark

Zircolite ist das schnellste der drei: 2,1× schneller als Hayabusa und 9,8× schneller als Chainsaw — und es ist das einzige von ihnen, das in Python geschrieben ist, gegen zwei in Rust geschriebene Tools.

Dieselben 4 Sysmon-EVTX-Dateien (478 MB, 452.554 Ereignisse), jedes Tool mit seinen Standardeinstellungen und eigenen Regeln, auf einem 10-Kern-Apple M1 Max. Median aus drei Läufen:

Zircolite tauscht Speicher gegen diese Geschwindigkeit: Es läuft ein Worker-Prozess pro Datei, und die obige Zahl ist deren Gesamtsumme. --no-parallel beschränkt es auf einen einzigen Prozess.

Die Regelsätze unterscheiden sich, daher sind die Erkennungszahlen nicht vergleichbar; siehe Benchmark für das Setup, die Einschränkungen und wie Sie es mit tools/tool-benchmark.py reproduzieren 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 es Ihnen, Ergebnisse anzuzeigen und zu durchsuchen. Sie können automatisch ein Mini-GUI-"Paket" mit der Option --package generieren. Verwenden Sie --package-dir, um das Ausgabeverzeichnis anzugeben. Um zu erfahren, wie Sie die Mini-GUI verwenden, lesen Sie die Dokumentation hier.

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

Zeitachse der erkannten Ereignisse

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

Tutorials, Referenzen und verwandte Projekte

Tutorials

• Englisch: Russ McRee hat ein detailliertes Tutorial über SIGMA und Zircolite in seinem Blog veröffentlicht.

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

• Französisch: IT-connect.fr hat ein umfangreiches Tutorial über Zircolite auf Französisch veröffentlicht.

• Französisch: IT-connect.fr hat auch einen Hack the Box Challenge Write-up unter Verwendung von Zircolite veröffentlicht.

Referenzen

• Florian Roth zitierte Zircolite in seiner SIGMA Hall of Fame während seines Vortrags beim EU ATT&CK Workshop im Oktober 2021.
• Zircolite wurde während der JSAC 2023 zitiert und vorgestellt.
• Zircolite wurde in mehreren Forschungsarbeiten zitiert und verwendet:
  • 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

Lizenz

• Der gesamte Code des Projekts ist unter der GNU Lesser General Public License lizenziert.
• Die EVTX-Analyse verwendet evtx (pyevtx-rs), unter der MIT- oder Apache-2.0-Lizenz. Release-Pakete listen jede gebündelte Bibliothek und ihre Lizenz in THIRD_PARTY_LICENSES auf.
• Die Regeln sind unter der Detection Rule License (DRL) 1.1 veröffentlicht.