Herramienta de Detección Autónoma Basada en SIGMA para Logs 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:

EVTX de MS Windows (formatos EVTX, XML y JSONL)
Logs de Auditd
Sysmon para Linux
EVTXtract
Logs CSV y XML
Logs de arrays JSON

Características Principales

Detección Automática del Tipo de Log: Identifica automáticamente los formatos de log y los campos de marca de tiempo mediante bytes mágicos, análisis de contenido y un respaldo basado en expresiones regulares — en la mayoría de los casos no es necesario especificar indicadores de formato.
Múltiples Formatos de Entrada: Admite varios formatos de log, incluidos EVTX, JSON Lines, JSON Arrays, CSV, XML y más. Se admiten logs comprimidos o archivados (gzip, bzip2, ZIP, 7-Zip); usa --archive-password para ZIP/7z cifrados.
Soporte Sigma Nativo: Zircolite puede usar directamente reglas Sigma nativas (YAML) convirtiéndolas con pySigma.
Backend SIGMA: Está basado en un backend SIGMA (SQLite) y no utiliza conversiones internas de SIGMA a otro formato.
Manipulación Avanzada de Logs: Puede manipular los logs de entrada dividiendo campos y aplicando transformaciones, lo que permite un análisis de logs más flexible y potente.
Transformaciones de Campos: Aplica transformaciones personalizadas en Python a los campos durante el procesamiento (p. ej., decodificación Base64, conversión de hexadecimal 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 Enriquecida en Terminal: Los resultados de detección se muestran en tablas ordenadas por severidad con IDs 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.

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

Requisitos / Instalación

El proyecto ha sido probado con Python 3.10 y versiones posteriores. Instala las dependencias con: pip3 install -r requirements.txt.

Dependencias

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

⚠️ En algunos sistemas (Mac, ARM, etc.), la biblioteca Python evtx puede requerir que Rust y Cargo estén instalados.

Inicio Rápido

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

Archivos EVTX

La ayuda está disponible con:

python3 zircolite.py -h

Si tus archivos EVTX tienen la extensión ".evtx":

# python3 zircolite.py --evtx <CARPETA EVTX o ARCHIVO EVTX> --ruleset <RULESET SIGMA> [--ruleset <OTRO RULESET>]
python3 zircolite.py --evtx sysmon.evtx --ruleset rules/rules_windows_merged.json

Uso de Reglas Sigma Nativas (YAML)

Puedes usar reglas Sigma nativas (YAML) directamente:

# Regla YAML única
python3 zircolite.py --evtx sample.evtx --ruleset path/to/rule.yml

# Directorio de reglas Sigma
python3 zircolite.py --evtx sample.evtx --ruleset ./sigma/rules/windows/process_creation

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

Otros Formatos de Log

Zircolite detecta automáticamente el formato de log en la mayoría de los casos, por lo que los indicadores de formato explícitos son opcionales:

# Autodetección (recomendada) - Zircolite identifica el formato automáticamente
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 <CARPETA_O_ARCHIVO_JSON> --ruleset rules/rules_windows_merged.json

# Indicadores de formato explícitos (anulan la autodetección)
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 <CARPETA_O_ARCHIVO_JSON> --ruleset rules/rules_windows_merged.json --jsononly
python3 zircolite.py --events <CARPETA_O_ARCHIVO_JSON> --ruleset rules/rules_windows_merged.json --json-array
python3 zircolite.py --events <CARPETA_O_ARCHIVO_CSV> --ruleset rules/rules_windows_merged.json --csv-input
python3 zircolite.py --events <CARPETA_O_ARCHIVO_XML> --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 log de la carpeta actual y sus subcarpetas (usa --no-recursion para deshabilitarlo).
Usa --file-pattern para especificar un patrón glob personalizado para la selección de archivos.
Usa --no-auto-detect para deshabilitar la detección automática de formato.

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

Ejecución con Docker

# Descargar la imagen Docker
docker pull wagga40/zircolite:latest
# Si tus logs y reglas están en un directorio específico
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

Reemplaza $PWD con el directorio (solo ruta absoluta) donde se almacenan tus logs y reglas/rulesets.

Optimización Automática del Procesamiento

Dados varios archivos, Zircolite los mide contra la RAM y la CPU disponibles, elige un modo de base de datos (una base de datos compartida, o una por archivo) y decide si vale la pena procesarlos en paralelo — luego adapta el número de trabajadores a la presión de memoria durante la ejecución.

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

Anula cualquiera de estas opciones 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 Optimización Automática del Procesamiento 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:

# Genera un archivo de configuración completamente comentado
python3 zircolite.py --generate-config my_config.yaml

# Ejecutar con él
python3 zircolite.py --yaml-config my_config.yaml

# Los argumentos de la CLI anulan el archivo
python3 zircolite.py --yaml-config my_config.yaml --evtx ./other_logs/

El archivo generado documenta cada clave admitida; config/zircolite_example.yaml es un ejemplo práctico. Consulta Configuración YAML para conocer las reglas de fusión y las opciones que no tienen equivalente YAML.

Actualización de los Rulesets Predeterminados

python3 zircolite.py -U

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

[!IMPORTANT]
Ten en cuenta que estos rulesets se proporcionan para usar Zircolite sin configuración adicional, pero deberías generar tus propios rulesets ya que pueden ser ruidosos o lentos. Estos rulesets 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:

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 puedan coincidir directamente con un hash.
Transformaciones de campos ejecutan Python en entorno aislado sobre el valor de un campo — decodificando líneas de comandos en base64, extrayendo IOC, 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 excepto las dos de auditd.

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

Consulta División de Campos y Transformaciones de Campos para ver la configuración completa, las transformaciones que incluye Zircolite y cómo probar las tuyas propias.

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" de la 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 MITRE ATT&CK® y Niveles de Criticalidad

Cronología de Eventos Detectados

Eventos Detectados por Técnicas 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ó a 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 utilizado en múltiples trabajos de investigación:
- Equipo CIDRE:
- 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.
evtx_dump está bajo la licencia MIT.
Las reglas se publican bajo la Detection Rule License (DRL) 1.0.

Zircolite

Más Populares