Herramienta de detección autónoma basada en SIGMA para registros EVTX, Auditd, Sysmon para Linux, XML, CSV o JSONL/NDJSON

Zircolite es una herramienta autónoma escrita en Python 3 que te permite usar reglas SIGMA sobre:

• MS Windows EVTX (formatos EVTX, XML y JSONL)
• Registros de Auditd
• Sysmon para Linux
• EVTXtract
• Registros CSV y XML
• Registros JSON Array

Características principales

• Rápida: 452.554 eventos contra 4.319 reglas Sigma en 11,6 s — 2,1× más rápida que Hayabusa y 9,8× más rápida que Chainsaw sobre los mismos registros, ambas herramientas escritas en Rust. Consulta el benchmark.
• Detección automática del tipo de registro: identifica automáticamente los formatos de registro y los campos de marca temporal mediante magic bytes, análisis de contenido y respaldo basado en regex -- no es necesario especificar flags de formato en la mayoría de los casos.
• Múltiples formatos de entrada: admite varios formatos de registro, incluidos EVTX, JSON Lines, JSON Arrays, CSV, XML y más. Se admiten registros comprimidos o archivados (gzip, bzip2, ZIP, 7-Zip); usa --archive-password para ZIP/7z cifrados.
• Soporte nativo de Sigma: Zircolite puede usar directamente reglas Sigma nativas (YAML) convirtiéndolas con pySigma.
• Backend SIGMA: se basa en un backend SIGMA (SQLite) y no utiliza conversión interna de SIGMA a otra cosa.
• Manipulación avanzada de registros: puede manipular los registros de entrada dividiendo campos y aplicando transformaciones, lo que permite un análisis de registros más flexible y potente.
• Transformaciones de campos: aplica transformaciones personalizadas de Python a los campos durante el procesamiento (por ejemplo, decodificación Base64, conversión de hex a ASCII).
• Exportación flexible: Zircolite puede exportar resultados a múltiples formatos usando plantillas Jinja, incluidos JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator y más.
• Salida de terminal enriquecida: los resultados de detección se muestran en tablas ordenadas por severidad con identificadores de técnicas MITRE ATT&CK, mapa de calor de tácticas ATT&CK, métricas de cobertura de reglas y enlaces clicables a los archivos de salida.

Puedes usar Zircolite directamente con Python, o descargar un binario autónomo que no necesita instalación de Python.

La documentación está disponible aquí (sitio dedicado) o aquí (directorio del repositorio).

Requisitos / Instalación

[!NOTE] Todo lo de esta sección se aplica solo cuando se ejecuta Zircolite desde el código fuente. Los binarios autónomos y la imagen Docker incluyen su propio Python, todas las dependencias y el kernel compilado: no necesitan Python, ni gestor de paquetes, ni compilador de C.

El proyecto se ha probado con Python 3.10 y superiores. Las dependencias se declaran en pyproject.toml; instálalas desde el repositorio clonado con PDM (pdm install), uv (uv sync) o Poetry (poetry install).

Los ejemplos siguientes ejecutan python3 zircolite.py: activa el entorno que haya creado la herramienta, o antepón pdm run, uv run o poetry run.

Dependencias

• Requeridas: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr solo se importa cuando se abre una entrada .7z; ZIP, gzip y bzip2 usan la biblioteca estándar.

⚠️ Instala primero un compilador de C

La instalación desde el código fuente compila el kernel de aplanamiento de Zircolite con Cython — pero solo si ya hay un compilador de C. Sin él, la instalación sigue teniendo éxito y cada ejecución aplana los eventos en Python en su lugar, lo cual es más lento. Los binarios y la imagen Docker se compilan con el kernel ya compilado, así que esto no les afecta.

Por lo tanto, instala el conjunto de herramientas antes de pdm install:

Cython en sí no necesita instalarse: es un requisito de tiempo de compilación, que se obtiene en un entorno de compilación aislado y nunca se añade a tu entorno.

Binarios autónomos

Cada release publica un paquete autocontenido por plataforma. Cada uno incluye su propio Python y todas las dependencias, por lo que no hay que instalar nada primero.

Los Mac con Intel y las distribuciones basadas en musl como Alpine no tienen binario; usa Python o Docker en esos casos.

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

En los ejemplos siguientes, sustituye python3 zircolite.py por la ruta al ejecutable.

Los binarios no están firmados digitalmente. macOS pone en cuarentena una descarga hecha con un navegador, los archivos extraídos heredan el flag, y Gatekeeper entonces bloquea el ejecutable y todas las bibliotecas en _internal/. Elimínalo de todo el directorio, de forma recursiva, antes de la primera ejecución:

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

Inicio rápido

Consulta los tutoriales (antiguos) hechos por otros (EN, ES y FR) aquí.

Archivos EVTX

La ayuda está disponible con:

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

Si tus archivos EVTX tienen la extensión ".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

Se puede omitir --ruleset: Zircolite entonces usa rules/rules_windows_merged.json, que cubre Sysmon y los canales genéricos de Windows.

Uso de reglas Sigma nativas (YAML)

Puedes usar reglas Sigma nativas (YAML) directamente:

# 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 muestra las pipelines instaladas. Indicar una que no está instalada detiene la ejecución con el código de salida 2, antes de que se convierta ninguna regla.

Otros formatos de registro

Zircolite autodetecta el formato de registro en la mayoría de los casos, por lo que los flags de formato explícitos son opcionales:

# 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

• El argumento --events puede ser un archivo o una carpeta. Si es una carpeta, se seleccionarán todos los archivos de registro de la carpeta actual y las subcarpetas (usa --no-recursion para desactivarlo).
• Usa --file-pattern para especificar un patrón glob personalizado para la selección de archivos.
• Usa --no-auto-detect para desactivar la detección automática de formato.

[!TIP] Si quieres probar la herramienta, puedes hacerlo con EVTX-ATTACK-SAMPLES (archivos EVTX).

Ejecución 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

• Sustituye $PWD por el directorio (solo ruta absoluta) donde se almacenan tus registros y reglas/conjuntos de reglas.
• En un host Linux, añade --user "$(id -u):$(id -g)" y -l /case/output/zircolite.log: la imagen se ejecuta como un usuario sin privilegios que no puede escribir en un directorio de tu propiedad. Consulta Docker.

Optimización automática del procesamiento

Dados varios archivos, Zircolite los mide frente a la RAM y CPU disponibles, elige un modo de base de datos (una base de datos compartida, o una por archivo) y decide si merece la pena procesarlos en paralelo — luego adapta el número de workers a la presión de memoria mientras se ejecuta.

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

Anula cualquiera de estos comportamientos con --no-auto-mode, --unified-db (una base de datos para todos los archivos, que es lo que necesitan las reglas de correlación entre archivos), --no-parallel o --parallel-workers N. Consulta Automatic Processing Optimization para saber cómo se toma la decisión.

Uso de archivos de configuración YAML

Para flujos de trabajo de análisis complejos o repetidos, usa un archivo de configuración 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/

El archivo generado documenta cada clave admitida con su valor predeterminado; config/zircolite_example.yaml es el mismo archivo, conservado en el repositorio. Consulta YAML configuration para conocer las reglas de fusión y las opciones que no tienen equivalente en YAML.

Actualización de los conjuntos de reglas predeterminados

python3 zircolite.py -U

Desde el código fuente, esto reescribe el directorio rules/ del repositorio. Un binario autónomo escribe en el directorio rules/ junto a su ejecutable, y recurre a ./rules en el directorio de trabajo, con una advertencia, cuando no se puede escribir en aquel.

Alternativamente, si usas Task (go-task), ejecuta task update-rules desde la raíz del proyecto para actualizar las reglas desde Zircolite-Rules-v2. Consulta docs para otras tareas (compilación de Docker, limpieza, etc.).

[!IMPORTANT]
Ten en cuenta que estos conjuntos de reglas se proporcionan para usar Zircolite directamente, pero deberías generar tus propios conjuntos de reglas ya que pueden ser ruidosos o lentos. Estos conjuntos de reglas autoactualizados están disponibles en el repositorio dedicado: Zircolite-Rules-v2.

División de campos y transformaciones

Dos características de configuración dan forma a los eventos a medida que se ingieren, ambas en config/config.yaml:

• La división de campos convierte un campo empaquetado de clave-valor en campos consultables. El campo Hashes de Sysmon (SHA1=abc123,MD5=def456,SHA256=789xyz) se convierte en campos separados SHA1, MD5 y SHA256, de modo que las reglas pueden coincidir directamente con un hash.
• Las transformaciones de campos ejecutan Python en sandbox sobre el valor de un campo — decodificando líneas de comandos en base64, extrayendo IOCs, marcando LOLBins — y pueden escribir el resultado en un campo nuevo en lugar de reemplazar el original. Zircolite incluye 55 de ellas en 11 categorías, desactivadas por defecto salvo las dos de auditd.

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

Consulta Field Splitting y Field Transforms para ver la configuración completa, las transformaciones que incluye Zircolite y cómo probar las tuyas propias.

Benchmark

Zircolite es la más rápida de las tres: 2,1× más rápida que Hayabusa y 9,8× más rápida que Chainsaw — y es la única de ellas escrita en Python, frente a dos herramientas escritas en Rust.

Los mismos 4 archivos EVTX de Sysmon (478 MB, 452.554 eventos), cada herramienta con sus valores predeterminados y sus propias reglas, en un Apple M1 Max de 10 núcleos. Mediana de tres ejecuciones:

Zircolite cambia memoria por esa velocidad: ejecuta un proceso worker por archivo, y la cifra anterior es su total. --no-parallel lo mantiene en un solo proceso.

Los conjuntos de reglas difieren, por lo que los recuentos de detección no son comparables; consulta Benchmark para ver la configuración, las advertencias y cómo reproducirlo con tools/tool-benchmark.py.

Documentación

La documentación completa está disponible aquí.

Mini-GUI

La Mini-GUI se puede usar completamente sin conexión. Te permite mostrar y buscar resultados. Puedes generar automáticamente un "paquete" Mini-GUI con la opción --package. Usa --package-dir para especificar el directorio de salida. Para aprender a usar la Mini-GUI, consulta la documentación aquí.

Eventos detectados por técnicas y niveles de criticidad de MITRE ATT&CK®

Cronología de eventos detectados

Eventos detectados por técnicas de MITRE ATT&CK® mostrados en la matriz

Tutoriales, referencias y proyectos relacionados

Tutoriales

• Inglés: Russ McRee ha publicado un tutorial detallado sobre SIGMA y Zircolite en su blog.

• Español: César Marín ha publicado un tutorial en español aquí.

• Francés: IT-connect.fr ha publicado un extenso tutorial sobre Zircolite en francés.

• Francés: IT-connect.fr también ha publicado un write-up del reto Hack the Box usando Zircolite.

Referencias

• Florian Roth citó Zircolite en su SIGMA Hall of Fame durante su charla en el EU ATT&CK Workshop de octubre de 2021.
• Zircolite ha sido citado y presentado durante JSAC 2023.
• Zircolite ha sido citado y usado en múltiples artículos de investigación:
  • 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

Licencia

• Todo el código del proyecto está licenciado bajo la GNU Lesser General Public License.
• El análisis de EVTX usa evtx (pyevtx-rs), bajo la licencia MIT o Apache-2.0. Los paquetes de las releases enumeran cada biblioteca incluida y su licencia en THIRD_PARTY_LICENSES.
• Las reglas se publican bajo la Detection Rule License (DRL) 1.1.