Outil de détection autonome basé sur SIGMA pour les journaux EVTX, Auditd, Sysmon for Linux, XML, CSV ou JSONL/NDJSON

Zircolite est un outil autonome écrit en Python 3 qui vous permet d'utiliser des règles SIGMA sur :

• MS Windows EVTX (formats EVTX, XML et JSONL)
• Journaux Auditd
• Sysmon for Linux
• EVTXtract
• Journaux CSV et XML
• Journaux JSON Array

Fonctionnalités clés

• Rapide : 452 554 événements contre 4 319 règles Sigma en 11,6 s — 2,1× plus rapide que Hayabusa et 9,8× plus rapide que Chainsaw sur les mêmes journaux, tous deux des outils Rust. Voir le benchmark.
• Détection automatique du type de journal : identifie automatiquement les formats de journaux et les champs d'horodatage à l'aide des magic bytes, de l'analyse du contenu et d'un repli basé sur des expressions régulières — plus besoin de spécifier des indicateurs de format dans la plupart des cas.
• Formats d'entrée multiples : prend en charge divers formats de journaux, notamment EVTX, JSON Lines, JSON Arrays, CSV, XML, etc. Les journaux compressés ou archivés (gzip, bzip2, ZIP, 7-Zip) sont pris en charge ; utilisez --archive-password pour les ZIP/7z chiffrés.
• Prise en charge native de Sigma : Zircolite peut utiliser directement les règles Sigma natives (YAML) en les convertissant avec pySigma.
• Backend SIGMA : il est basé sur un backend SIGMA (SQLite) et n'utilise pas de conversion interne SIGMA-vers-quelque-chose.
• Manipulation avancée des journaux : il peut manipuler les journaux d'entrée en divisant les champs et en appliquant des transformations, permettant une analyse de journaux plus flexible et plus puissante.
• Transformations de champs : appliquez des transformations Python personnalisées aux champs pendant le traitement (par exemple, décodage Base64, conversion hex-vers-ASCII).
• Export flexible : Zircolite peut exporter les résultats vers plusieurs formats à l'aide de templates Jinja, notamment JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator, et plus encore.
• Sortie terminal enrichie : résultats de détection affichés dans des tableaux triés par sévérité avec les identifiants de techniques MITRE ATT&CK, heatmap des tactiques ATT&CK, métriques de couverture des règles et liens cliquables vers les fichiers de sortie.

Vous pouvez utiliser Zircolite directement avec Python, ou télécharger un binaire autonome qui ne nécessite aucune installation de Python.

La documentation est disponible ici (site dédié) ou ici (répertoire du dépôt).

Prérequis / Installation

[!NOTE] Tout ce qui figure dans cette section s'applique uniquement lors de l'exécution de Zircolite depuis les sources. Les binaires autonomes et l'image Docker embarquent leur propre Python, toutes les dépendances et le noyau compilé : ils ne nécessitent ni Python, ni gestionnaire de paquets, ni compilateur C.

Le projet a été testé avec Python 3.10 et versions supérieures. Les dépendances sont déclarées dans pyproject.toml ; installez-les depuis le dépôt cloné avec PDM (pdm install), uv (uv sync) ou Poetry (poetry install).

Les exemples ci-dessous exécutent python3 zircolite.py : activez l'environnement créé par l'outil, ou préfixez-les avec pdm run, uv run ou poetry run.

Dépendances

• Requises : orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr n'est importé que lorsqu'une entrée .7z est ouverte ; ZIP, gzip et bzip2 utilisent la bibliothèque standard.

⚠️ Installez d'abord un compilateur C

L'installation depuis les sources compile le noyau d'aplatissement de Zircolite avec Cython — mais uniquement si un compilateur C est déjà présent. Sans celui-ci, l'installation réussit quand même et chaque exécution aplatit les événements en Python à la place, ce qui est plus lent. Les binaires et l'image Docker sont construits avec le noyau déjà compilé, donc cela ne les concerne pas.

Installez donc la chaîne d'outils avant pdm install :

Cython lui-même n'a pas besoin d'être installé : c'est une dépendance de compilation, récupérée dans un environnement de build isolé et jamais ajoutée à votre environnement.

Binaires autonomes

Chaque release publie un paquet autonome par plateforme. Chacun embarque son propre Python et toutes les dépendances, donc rien n'a besoin d'être installé au préalable.

Les Mac Intel et les distributions basées sur musl telles qu'Alpine n'ont pas de binaire ; utilisez Python ou Docker dans ce cas.

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

Dans les exemples ci-dessous, remplacez python3 zircolite.py par le chemin vers l'exécutable.

Les binaires ne sont pas signés numériquement. macOS met en quarantaine un téléchargement effectué avec un navigateur, les fichiers extraits héritent de l'indicateur, et Gatekeeper bloque alors l'exécutable et chaque bibliothèque dans _internal/. Supprimez-le de tout le répertoire, récursivement, avant la première exécution :

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

Démarrage rapide

Consultez les (anciens) tutoriels réalisés par d'autres (EN, ES et FR) ici.

Fichiers EVTX

L'aide est disponible avec :

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

Si vos fichiers EVTX ont l'extension ".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 peut être omis : Zircolite utilise alors rules/rules_windows_merged.json, qui couvre Sysmon et les canaux Windows génériques.

Utilisation des règles Sigma natives (YAML)

Vous pouvez utiliser directement les règles Sigma natives (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 affiche les pipelines installés. En nommer un qui n'est pas installé arrête l'exécution avec le code de sortie 2, avant toute conversion de règle.

Autres formats de journaux

Zircolite détecte automatiquement le format de journal dans la plupart des cas, donc les indicateurs de format explicites sont facultatifs :

# 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'argument --events peut être un fichier ou un dossier. S'il s'agit d'un dossier, tous les fichiers journaux du dossier courant et des sous-dossiers seront sélectionnés (utilisez --no-recursion pour désactiver).
• Utilisez --file-pattern pour spécifier un motif glob personnalisé pour la sélection des fichiers.
• Utilisez --no-auto-detect pour désactiver la détection automatique du format.

[!TIP] Si vous souhaitez essayer l'outil, vous pouvez tester avec EVTX-ATTACK-SAMPLES (fichiers EVTX).

Exécution avec 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

• Remplacez $PWD par le répertoire (chemin absolu uniquement) où sont stockés vos journaux et règles/rulesets.
• Sur un hôte Linux, ajoutez --user "$(id -u):$(id -g)" et -l /case/output/zircolite.log : l'image s'exécute en tant qu'utilisateur non privilégié qui ne peut pas écrire dans un répertoire que vous possédez. Voir Docker.

Optimisation automatique du traitement

Face à plusieurs fichiers, Zircolite les mesure par rapport à la RAM et au CPU disponibles, choisit un mode de base de données (une base partagée, ou une par fichier) et décide si leur traitement en parallèle en vaut la peine — puis adapte le nombre de workers à la pression mémoire pendant l'exécution.

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

Remplacez n'importe lequel de ces choix avec --no-auto-mode, --unified-db (une base de données pour tous les fichiers, ce dont ont besoin les règles de corrélation inter-fichiers), --no-parallel ou --parallel-workers N. Voir Automatic Processing Optimization pour savoir comment le choix est effectué.

Utilisation des fichiers de configuration YAML

Pour les workflows d'analyse complexes ou répétés, utilisez un fichier de configuration 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/

Le fichier généré documente chaque clé prise en charge à sa valeur par défaut ; config/zircolite_example.yaml est le même fichier, conservé dans le dépôt. Voir YAML configuration pour les règles de fusion et les options qui n'ont pas d'équivalent YAML.

Mise à jour des rulesets par défaut

python3 zircolite.py -U

Depuis les sources, cela réécrit le rules/ du dépôt. Un binaire autonome écrit dans le répertoire rules/ à côté de son exécutable, et se rabat sur ./rules dans le répertoire de travail, avec un avertissement, lorsque celui-ci ne peut pas être écrit.

Alternativement, si vous utilisez Task (go-task), exécutez task update-rules depuis la racine du projet pour mettre à jour les règles depuis Zircolite-Rules-v2. Voir docs pour les autres tâches (build Docker, clean, etc.).

[!IMPORTANT]
Veuillez noter que ces rulesets sont fournis pour utiliser Zircolite immédiatement, mais vous devriez générer vos propres rulesets car ils peuvent être bruyants ou lents. Ces rulesets mis à jour automatiquement sont disponibles dans le dépôt dédié : Zircolite-Rules-v2.

Découpage de champs et transformations

Deux fonctionnalités de configuration façonnent les événements au moment de leur ingestion, toutes deux dans config/config.yaml :

• Le découpage de champs transforme un champ clé-valeur compact en champs interrogeables. Le champ Hashes de Sysmon (SHA1=abc123,MD5=def456,SHA256=789xyz) devient des champs SHA1, MD5 et SHA256 distincts, afin que les règles puissent correspondre directement à un hash.
• Les transformations de champs exécutent du Python en sandbox sur la valeur d'un champ — décodage de lignes de commande base64, extraction d'IOC, signalement de LOLBins — et peuvent écrire le résultat dans un nouveau champ plutôt que de remplacer l'original. Zircolite en fournit 55 réparties en 11 catégories, désactivées par défaut à l'exception des deux pour auditd.

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

Voir Field Splitting et Field Transforms pour la configuration complète, les transformations fournies par Zircolite, et comment tester les vôtres.

Benchmark

Zircolite est le plus rapide des trois : 2,1× plus rapide que Hayabusa et 9,8× plus rapide que Chainsaw — et c'est le seul des trois écrit en Python, face à deux outils écrits en Rust.

Mêmes 4 fichiers Sysmon EVTX (478 Mo, 452 554 événements), chaque outil avec ses valeurs par défaut et ses propres règles, sur un Apple M1 Max à 10 cœurs. Médiane de trois exécutions :

Zircolite échange de la mémoire contre cette vitesse : il exécute un processus worker par fichier, et le chiffre ci-dessus est leur total. --no-parallel le limite à un seul processus.

Les ensembles de règles diffèrent, donc les comptages de détection ne sont pas comparables ; voir Benchmark pour la configuration, les réserves et comment le reproduire avec tools/tool-benchmark.py.

Documentation

La documentation complète est disponible ici.

Mini-GUI

La Mini-GUI peut être utilisée entièrement hors ligne. Elle vous permet d'afficher et de rechercher les résultats. Vous pouvez générer automatiquement un « package » Mini-GUI avec l'option --package. Utilisez --package-dir pour spécifier le répertoire de sortie. Pour apprendre à utiliser la Mini-GUI, consultez la documentation ici.

Événements détectés par techniques MITRE ATT&CK® et niveaux de criticité

Chronologie des événements détectés

Événements détectés par techniques MITRE ATT&CK® affichés sur la matrice

Tutoriels, références et projets connexes

Tutoriels

• Anglais : Russ McRee a publié un tutoriel détaillé sur SIGMA et Zircolite sur son blog.

• Espagnol : César Marín a publié un tutoriel en espagnol ici.

• Français : IT-connect.fr a publié un tutoriel complet sur Zircolite en français.

• Français : IT-connect.fr a également publié un write-up du challenge Hack the Box utilisant Zircolite.

Références

• Florian Roth a cité Zircolite dans son SIGMA Hall of Fame lors de sa présentation à l'EU ATT&CK Workshop d'octobre 2021.
• Zircolite a été cité et présenté lors de JSAC 2023.
• Zircolite a été cité et utilisé dans plusieurs articles de recherche :
  • 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

Licence

• Tout le code du projet est sous licence GNU Lesser General Public License.
• L'analyse EVTX utilise evtx (pyevtx-rs), sous licence MIT ou Apache-2.0. Les paquets de release listent chaque bibliothèque embarquée et sa licence dans THIRD_PARTY_LICENSES.
• Les règles sont publiées sous la Detection Rule License (DRL) 1.1.