Ferramenta de Detecção Standalone Baseada em SIGMA para Logs EVTX, Auditd, Sysmon para Linux, XML, CSV ou JSONL/NDJSON

Zircolite é uma ferramenta standalone escrita em Python 3 que permite usar regras SIGMA em:

• MS Windows EVTX (formatos EVTX, XML e JSONL)
• Logs Auditd
• Sysmon para Linux
• EVTXtract
• Logs CSV e XML
• Logs JSON Array

Principais Recursos

• Rápido: 452.554 eventos contra 4.319 regras Sigma em 11,6 s — 2,1× mais rápido que o Hayabusa e 9,8× mais rápido que o Chainsaw nos mesmos logs, ambos ferramentas escritas em Rust. Veja o benchmark.
• Detecção Automática do Tipo de Log: Identifica automaticamente formatos de log e campos de timestamp usando magic bytes, análise de conteúdo e fallback baseado em regex -- sem necessidade de especificar flags de formato na maioria dos casos.
• Múltiplos Formatos de Entrada: Suporta vários formatos de log, incluindo EVTX, JSON Lines, JSON Arrays, CSV, XML e mais. Logs comprimidos ou arquivados (gzip, bzip2, ZIP, 7-Zip) são suportados; use --archive-password para ZIP/7z criptografados.
• Suporte Nativo a Sigma: O Zircolite pode usar diretamente regras Sigma nativas (YAML) convertendo-as com pySigma.
• Backend SIGMA: É baseado em um backend SIGMA (SQLite) e não usa conversão interna de SIGMA para outra coisa.
• Manipulação Avançada de Logs: Pode manipular logs de entrada dividindo campos e aplicando transformações, permitindo uma análise de logs mais flexível e poderosa.
• Transformações de Campos: Aplica transformações personalizadas em Python aos campos durante o processamento (por exemplo, decodificação Base64, conversão hex-to-ASCII).
• Exportação Flexível: O Zircolite pode exportar resultados para múltiplos formatos usando templates Jinja, incluindo JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator e mais.
• Saída Rica no Terminal: Resultados de detecção exibidos em tabelas ordenadas por severidade com IDs de técnicas MITRE ATT&CK, heatmap de táticas ATT&CK, métricas de cobertura de regras e links clicáveis para arquivos de saída.

Você pode usar o Zircolite diretamente com Python, ou baixar um binário standalone que não precisa de instalação do Python.

A documentação está disponível aqui (site dedicado) ou aqui (diretório do repositório).

Requisitos / Instalação

[!NOTE] Tudo nesta seção se aplica apenas ao executar o Zircolite a partir do código-fonte. Os binários standalone e a imagem Docker carregam seu próprio Python, todas as dependências e o kernel compilado: eles não precisam de Python, nem gerenciador de pacotes, nem compilador C.

O projeto foi testado com Python 3.10 e superior. As dependências são declaradas em pyproject.toml; instale-as a partir do repositório clonado com PDM (pdm install), uv (uv sync) ou Poetry (poetry install).

Os exemplos abaixo executam python3 zircolite.py: ative o ambiente criado pela ferramenta, ou prefixe-os com pdm run, uv run ou poetry run.

Dependências

• Obrigatórias: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr é importado apenas quando uma entrada .7z é aberta; ZIP, gzip e bzip2 usam a biblioteca padrão.

⚠️ Instale um compilador C primeiro

Instalar a partir do código-fonte compila o kernel de flattening do Zircolite com Cython — mas apenas se um compilador C já estiver presente. Sem um, a instalação ainda é bem-sucedida e cada execução faz o flattening dos eventos em Python, o que é mais lento. Os binários e a imagem Docker são construídos com o kernel já compilado, então isso não os afeta.

Portanto, instale o toolchain antes de pdm install:

O Cython em si não precisa ser instalado: é um requisito de tempo de build, obtido em um ambiente de build isolado e nunca adicionado ao seu ambiente.

Binários Standalone

Cada release publica um pacote autocontido por plataforma. Cada um carrega seu próprio Python e todas as dependências, então nada precisa ser instalado primeiro.

Macs Intel e distribuições baseadas em musl, como Alpine, não têm binário; use Python ou Docker nesses casos.

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

Nos exemplos abaixo, substitua python3 zircolite.py pelo caminho do executável.

Os binários não são assinados digitalmente. O macOS coloca em quarentena um download feito com um navegador, os arquivos extraídos herdam a flag, e o Gatekeeper então bloqueia o executável e todas as bibliotecas em _internal/. Remova-a de todo o diretório, recursivamente, antes da primeira execução:

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

Início Rápido

Confira tutoriais (antigos) feitos por outros (EN, ES e FR) aqui.

Arquivos EVTX

A ajuda está disponível com:

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

Se seus arquivos EVTX tiverem a extensão ".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 pode ser omitido: o Zircolite então usa rules/rules_windows_merged.json, que cobre o Sysmon e os canais genéricos do Windows.

Usando Regras Sigma Nativas (YAML)

Você pode usar regras Sigma nativas (YAML) diretamente:

# 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 mostra os pipelines instalados. Nomear um que não está instalado interrompe a execução com código de saída 2, antes que qualquer regra seja convertida.

Outros Formatos de Log

O Zircolite detecta automaticamente o formato de log na maioria dos casos, então flags de formato explícitas são opcionais:

# 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

• O argumento --events pode ser um arquivo ou uma pasta. Se for uma pasta, todos os arquivos de log na pasta atual e subpastas serão selecionados (use --no-recursion para desabilitar).
• Use --file-pattern para especificar um padrão glob personalizado para seleção de arquivos.
• Use --no-auto-detect para desabilitar a detecção automática de formato.

[!TIP] Se você quiser experimentar a ferramenta, pode testar com EVTX-ATTACK-SAMPLES (arquivos EVTX).

Executando com 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

• Substitua $PWD pelo diretório (apenas caminho absoluto) onde seus logs e regras/rulesets estão armazenados.
• Em um host Linux, adicione --user "$(id -u):$(id -g)" e -l /case/output/zircolite.log: a imagem é executada como um usuário sem privilégios que não pode escrever em um diretório que você possui. Veja Docker.

Otimização Automática de Processamento

Dado vários arquivos, o Zircolite os compara com a RAM e CPU disponíveis, escolhe um modo de banco de dados (um banco compartilhado, ou um por arquivo) e decide se processá-los em paralelo vale a pena — então adapta a contagem de workers à pressão de memória durante a execução.

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

Substitua qualquer parte disso com --no-auto-mode, --unified-db (um banco de dados para todos os arquivos, que é o que regras de correlação entre arquivos precisam), --no-parallel ou --parallel-workers N. Veja Otimização Automática de Processamento para saber como a escolha é feita.

Usando Arquivos de Configuração YAML

Para fluxos de trabalho de análise complexos ou repetidos, use um arquivo de configuração 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/

O arquivo gerado documenta cada chave suportada em seu valor padrão; config/zircolite_example.yaml é o mesmo arquivo, mantido no repositório. Veja Configuração YAML para as regras de mesclagem e as opções que não têm equivalente em YAML.

Atualizando Rulesets Padrão

python3 zircolite.py -U

A partir do código-fonte, isso reescreve o rules/ do repositório. Um binário standalone escreve no diretório rules/ ao lado de seu executável, e recorre a ./rules no diretório de trabalho, com um aviso, quando não é possível escrever nele.

Alternativamente, se você usa Task (go-task), execute task update-rules a partir da raiz do projeto para atualizar as regras de Zircolite-Rules-v2. Veja docs para outras tarefas (build Docker, clean, etc.).

[!IMPORTANT]
Observe que esses rulesets são fornecidos para usar o Zircolite pronto para uso, mas você deve gerar seus próprios rulesets, pois eles podem ser ruidosos ou lentos. Esses rulesets atualizados automaticamente estão disponíveis no repositório dedicado: Zircolite-Rules-v2.

Divisão de Campos e Transformações

Dois recursos de configuração moldam os eventos conforme são ingeridos, ambos em config/config.yaml:

• Divisão de campos transforma um campo compactado de chave-valor em campos consultáveis. O campo Hashes do Sysmon (SHA1=abc123,MD5=def456,SHA256=789xyz) torna-se campos separados SHA1, MD5 e SHA256, para que as regras possam corresponder a um hash diretamente.
• Transformações de campos executam Python em sandbox sobre o valor de um campo — decodificando linhas de comando em base64, extraindo IOCs, sinalizando LOLBins — e podem escrever o resultado em um novo campo em vez de substituir o original. O Zircolite inclui 55 delas em 11 categorias, desativadas por padrão, exceto as duas de auditd.

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

Veja Divisão de Campos e Transformações de Campos para a configuração completa, as transformações que o Zircolite inclui e como testar as suas próprias.

Benchmark

O Zircolite é o mais rápido dos três: 2,1× mais rápido que o Hayabusa e 9,8× mais rápido que o Chainsaw — e é o único deles escrito em Python, contra duas ferramentas escritas em Rust.

Os mesmos 4 arquivos Sysmon EVTX (478 MB, 452.554 eventos), cada ferramenta com seus padrões e suas próprias regras, em um Apple M1 Max de 10 núcleos. Mediana de três execuções:

O Zircolite troca memória por essa velocidade: ele executa um processo worker por arquivo, e o número acima é o total deles. --no-parallel mantém em um único processo.

Os conjuntos de regras diferem, então as contagens de detecção não são comparáveis; veja Benchmark para a configuração, as ressalvas e como reproduzi-lo com tools/tool-benchmark.py.

Documentação

A documentação completa está disponível aqui.

Mini-GUI

A Mini-GUI pode ser usada completamente offline. Ela permite exibir e pesquisar resultados. Você pode gerar automaticamente um "pacote" Mini-GUI com a opção --package. Use --package-dir para especificar o diretório de saída. Para aprender como usar a Mini-GUI, confira a documentação aqui.

Eventos Detectados por Técnicas MITRE ATT&CK® e Níveis de Criticidade

Linha do Tempo de Eventos Detectados

Eventos Detectados por Técnicas MITRE ATT&CK® Exibidos na Matriz

Tutoriais, Referências e Projetos Relacionados

Tutoriais

• Inglês: Russ McRee publicou um tutorial detalhado sobre SIGMA e Zircolite em seu blog.

• Espanhol: César Marín publicou um tutorial em espanhol aqui.

• Francês: IT-connect.fr publicou um tutorial extenso sobre o Zircolite em francês.

• Francês: IT-connect.fr também publicou um write-up do desafio Hack the Box usando o Zircolite.

Referências

• Florian Roth citou o Zircolite em seu SIGMA Hall of Fame durante sua palestra no EU ATT&CK Workshop de outubro de 2021.
• O Zircolite foi citado e apresentado durante o JSAC 2023.
• O Zircolite foi citado e usado em múltiplos artigos de pesquisa:
  • 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

Licença

• Todo o código do projeto está licenciado sob a GNU Lesser General Public License.
• A análise de EVTX usa evtx (pyevtx-rs), sob a licença MIT ou Apache-2.0. Os pacotes de release listam cada biblioteca incluída e sua licença em THIRD_PARTY_LICENSES.
• As regras são publicadas sob a Detection Rule License (DRL) 1.1.