Outil de détection autonome basé sur SIGMA pour les journaux EVTX, Auditd, Sysmon pour 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 :

Les journaux MS Windows EVTX (formats EVTX, XML et JSONL)
Les journaux Auditd
Sysmon pour Linux
EVTXtract
Les journaux CSV et XML
Les journaux JSON Array

Fonctionnalités clés

Détection automatique du type de journal : identifie automatiquement les formats de journaux et les champs d'horodatage à l'aide d'octets magiques, d'une analyse de contenu et d'un mécanisme de repli basé sur des expressions régulières — nul besoin de spécifier d'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 des règles Sigma natives (YAML) en les convertissant avec pySigma.
Backend SIGMA : basé sur un backend SIGMA (SQLite) et n'utilise pas de conversion interne SIGMA-vers-autre-chose.
Manipulation avancée des journaux : peut manipuler les journaux d'entrée en découpant des champs et en appliquant des transformations, ce qui permet une analyse des journaux plus flexible et plus puissante.
Transformations de champs : applique des transformations Python personnalisées aux champs pendant le traitement (par exemple, décodage Base64, conversion hexadécimal vers ASCII).
Export flexible : Zircolite peut exporter les résultats vers plusieurs formats à l'aide de modèles Jinja, notamment JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator, et plus encore.
Sortie terminale riche : les résultats de détection sont affichés dans des tableaux triés par sévérité avec les identifiants de techniques MITRE ATT&CK, une carte de chaleur des tactiques ATT&CK, des métriques de couverture des règles et des liens cliquables vers les fichiers de sortie.

Vous pouvez utiliser Zircolite directement avec Python.

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

Prérequis / Installation

Le projet a été testé avec Python 3.10 et versions ultérieures. Installez les dépendances avec : pip3 install -r requirements.txt.

Dépendances

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

⚠️ Sur certains systèmes (Mac, ARM, etc.), la bibliothèque Python evtx peut nécessiter l'installation de Rust et Cargo.

Démarrage rapide

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

Fichiers EVTX

L'aide est disponible avec :

python3 zircolite.py -h

Si vos fichiers EVTX portent l'extension « .evtx » :

# python3 zircolite.py --evtx <DOSSIER EVTX ou FICHIER EVTX> --ruleset <RULESET SIGMA> [--ruleset <AUTRE RULESET>]
python3 zircolite.py --evtx sysmon.evtx --ruleset rules/rules_windows_merged.json

Utilisation de règles Sigma natives (YAML)

Vous pouvez utiliser directement des règles Sigma natives (YAML) :

# Règle YAML unique
python3 zircolite.py --evtx sample.evtx --ruleset path/to/rule.yml

# Répertoire de règles Sigma
python3 zircolite.py --evtx sample.evtx --ruleset ./sigma/rules/windows/process_creation

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

Autres formats de journaux

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

# Auto-détection (recommandée) - Zircolite identifie le format automatiquement
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 <DOSSIER_OU_FICHIER_JSON> --ruleset rules/rules_windows_merged.json

# Indicateurs de format explicites (remplacent l'auto-détection)
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 <DOSSIER_OU_FICHIER_JSON> --ruleset rules/rules_windows_merged.json --jsononly
python3 zircolite.py --events <DOSSIER_OU_FICHIER_JSON> --ruleset rules/rules_windows_merged.json --json-array
python3 zircolite.py --events <DOSSIER_OU_FICHIER_CSV> --ruleset rules/rules_windows_merged.json --csv-input
python3 zircolite.py --events <DOSSIER_OU_FICHIER_XML> --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 de ses sous-dossiers seront sélectionnés (utilisez --no-recursion pour désactiver).
Utilisez --file-pattern pour spécifier un modèle 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

# Récupérez l'image Docker
docker pull wagga40/zircolite:latest
# Si vos journaux et règles se trouvent dans un répertoire spécifique
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.

Optimisation automatique du traitement

Étant donné plusieurs fichiers, Zircolite les évalue 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 au fur et à mesure de l'exécution.

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

Remplacez tout cela avec --no-auto-mode, --unified-db (une base de données pour tous les fichiers, ce dont les règles de corrélation inter-fichiers ont besoin), --no-parallel ou --parallel-workers N. Consultez Optimisation automatique du traitement pour comprendre comment le choix est effectué.

Utilisation de fichiers de configuration YAML

Pour des flux d'analyse complexes ou répétés, utilisez un fichier de configuration YAML :

# Génère un fichier de configuration entièrement commenté
python3 zircolite.py --generate-config my_config.yaml

# Exécution avec ce fichier
python3 zircolite.py --yaml-config my_config.yaml

# Les arguments CLI remplacent le fichier
python3 zircolite.py --yaml-config my_config.yaml --evtx ./other_logs/

Le fichier généré documente chaque clé prise en charge ; config/zircolite_example.yaml est un exemple complet. Consultez Configuration YAML pour les règles de fusion et les options sans équivalent YAML.

Mise à jour des rulesets par défaut

python3 zircolite.py -U

Sinon, si vous utilisez Task (go-task), exécutez task update-rules à la racine du projet pour mettre à jour les règles depuis Zircolite-Rules-v2. Consultez les docs pour les autres tâches (build Docker, nettoyage, 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 bruités 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 options de configuration façonnent les événements lors 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 distincts SHA1, MD5 et SHA256, permettant aux règles de correspondre directement à un hash.
Les transformations de champs exécutent du Python sandboxé sur la valeur d'un champ — décodage de lignes de commande en 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 dans 11 catégories, désactivées par défaut, à l'exception des deux concernant auditd.

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

Consultez Découpage de champs et Transformations de champs pour la configuration complète, les transformations fournies par Zircolite et la manière de tester les vôtres.

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 des 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 de défi 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'atelier EU ATT&CK d'octobre 2021.
Zircolite a été cité et présenté lors du JSAC 2023.
Zircolite a été cité et utilisé dans plusieurs travaux de recherche :
- Équipe CIDRE :
- Universidad de la República :
  - Une méthode basée sur le process mining pour le profilage d'attaquants à l'aide de la taxonomie MITRE ATT&CK

Licence

Tout le code du projet est sous licence GNU Lesser General Public License.
evtx_dump est sous licence MIT.
Les règles sont publiées sous la Detection Rule License (DRL) 1.0.

Zircolite

Populaires