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

Zircolite é uma ferramenta autônoma escrita em Python 3 que permite usar regras SIGMA em:

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

Principais Recursos

Detecção Automática de Tipo de Log: Identifica automaticamente formatos de log e campos de timestamp usando bytes mágicos, 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 outros. Logs compactados 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: Baseia-se em um backend SIGMA (SQLite) e não usa conversão interna SIGMA-para-algo.
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 Python personalizadas aos campos durante o processamento (por exemplo, decodificação Base64, conversão hex-para-ASCII).
Exportação Flexível: O Zircolite pode exportar resultados para vários formatos usando templates Jinja, incluindo JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator e outros.
Saída de Terminal Rica: Resultados de detecção exibidos em tabelas ordenadas por severidade, com IDs de técnicas do MITRE ATT&CK, mapa de calor 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.

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

Requisitos / Instalação

O projeto foi testado com Python 3.10 e superior. Instale as dependências com: pip3 install -r requirements.txt.

Dependências

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

⚠️ Em alguns sistemas (Mac, ARM, etc.), a biblioteca Python evtx pode exigir que Rust e Cargo estejam instalados.

Início Rápido

Veja tutoriais (antigos) feitos por outras pessoas (EN, ES e FR) aqui.

Arquivos EVTX

A ajuda está disponível com:

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

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

Outros Formatos de Log

O Zircolite detecta automaticamente o formato do log na maioria dos casos, portanto 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 desativar).
Use --file-pattern para especificar um padrão glob personalizado para seleção de arquivos.
Use --no-auto-detect para desativar a detecção automática de formato.

[!TIP] Se quiser experimentar a ferramenta, você 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 (somente caminho absoluto) onde seus logs e regras/rulesets estão armazenados.

Otimização Automática de Processamento

Com vários arquivos, o Zircolite os avalia em relação à RAM e CPU disponíveis, escolhe um modo de banco de dados (um banco de dados compartilhado ou um por arquivo) e decide se vale a pena processá-los em paralelo — em seguida, ajusta o número 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 as 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 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 todas as chaves suportadas; config/zircolite_example.yaml é um exemplo prático. 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

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

[!IMPORTANT]
Observe que esses rulesets são fornecidos para usar o Zircolite de forma pronta 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, permitindo que as regras correspondam diretamente a um hash.
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 gravar 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.

Documentação

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

Mini-GUI

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

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

Linha do Tempo de Eventos Detectados

Eventos Detectados por Técnicas do 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 diversos artigos de pesquisa:
- Equipe CIDRE:
- Universidad de la República:
  - Um Método Baseado em Process Mining para Perfilamento de Atacantes Usando a Taxonomia do MITRE ATT&CK

Licença

Todo o código do projeto é licenciado sob a GNU Lesser General Public License.
evtx_dump está sob a licença MIT.
As regras são disponibilizadas sob a Detection Rule License (DRL) 1.0.

Zircolite

Mais Populares