Автономный инструмент обнаружения на основе SIGMA для логов EVTX, Auditd, Sysmon for Linux, XML, CSV или JSONL/NDJSON

Zircolite — это автономный инструмент, написанный на Python 3, который позволяет использовать правила SIGMA для:

• MS Windows EVTX (форматы EVTX, XML и JSONL)
• логов Auditd
• Sysmon for Linux
• EVTXtract
• логов CSV и XML
• логов JSON Array

Ключевые возможности

• Быстрота: 452 554 события против 4 319 правил Sigma за 11,6 с — в 2,1 раза быстрее Hayabusa и в 9,8 раза быстрее Chainsaw на тех же логах, при том что оба этих инструмента написаны на Rust. См. бенчмарк.
• Автоматическое определение типа логов: автоматически распознаёт форматы логов и поля временных меток с помощью magic bytes, анализа содержимого и резервного механизма на основе регулярных выражений — в большинстве случаев указывать флаги формата не нужно.
• Множество входных форматов: поддерживает различные форматы логов, включая EVTX, JSON Lines, JSON Arrays, CSV, XML и другие. Поддерживаются сжатые и архивированные логи (gzip, bzip2, ZIP, 7-Zip); для зашифрованных ZIP/7z используйте --archive-password.
• Нативная поддержка Sigma: Zircolite может напрямую использовать нативные правила Sigma (YAML), преобразуя их с помощью pySigma.
• Бэкенд SIGMA: основан на бэкенде SIGMA (SQLite) и не использует внутреннее преобразование SIGMA во что-либо иное.
• Продвинутая обработка логов: может манипулировать входными логами, разделяя поля и применяя преобразования, что обеспечивает более гибкий и мощный анализ логов.
• Преобразования полей: применяйте пользовательские преобразования на Python к полям во время обработки (например, декодирование Base64, преобразование hex в ASCII).
• Гибкий экспорт: Zircolite может экспортировать результаты в множество форматов с помощью Jinja шаблонов, включая JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator и другие.
• Насыщенный вывод в терминал: результаты обнаружения отображаются в таблицах, отсортированных по критичности, с идентификаторами техник MITRE ATT&CK, тепловой картой тактик ATT&CK, метриками покрытия правил и кликабельными ссылками на выходные файлы.

Вы можете использовать Zircolite напрямую с Python или скачать автономный бинарный файл, не требующий установки Python.

Документация доступна здесь (отдельный сайт) или здесь (каталог репозитория).

Требования / Установка

[!NOTE] Всё в этом разделе относится только к запуску Zircolite из исходного кода. Автономные бинарные файлы и Docker-образ содержат собственный Python, все зависимости и скомпилированное ядро: им не нужны ни Python, ни менеджер пакетов, ни компилятор C.

Проект протестирован с Python 3.10 и выше. Зависимости объявлены в pyproject.toml; установите их из клонированного репозитория с помощью PDM (pdm install), uv (uv sync) или Poetry (poetry install).

Примеры ниже запускают python3 zircolite.py: активируйте окружение, созданное инструментом, или добавьте префикс pdm run, uv run или poetry run.

Зависимости

• Обязательные: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr импортируется только при открытии входного файла .7z; ZIP, gzip и bzip2 используют стандартную библиотеку.

⚠️ Сначала установите компилятор C

Установка из исходного кода компилирует ядро выравнивания Zircolite с помощью Cython — но только если компилятор C уже присутствует. Без него установка всё равно завершится успешно, и каждый запуск будет выравнивать события на Python, что медленнее. Бинарные файлы и Docker-образ собраны с уже скомпилированным ядром, поэтому их это не касается.

Поэтому установите инструментарий до pdm install:

Сам Cython устанавливать не нужно: это требование времени сборки, он загружается в изолированное окружение сборки и никогда не добавляется в ваше окружение.

Автономные бинарные файлы

Каждый релиз публикует самодостаточный пакет для каждой платформы. Каждый содержит собственный Python и все зависимости, поэтому ничего не нужно устанавливать заранее.

Для Intel Mac и дистрибутивов на musl, таких как Alpine, бинарных файлов нет; используйте там Python или Docker.

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

В примерах ниже замените python3 zircolite.py на путь к исполняемому файлу.

Бинарные файлы не подписаны кодом. macOS помещает загруженный через браузер файл в карантин, извлечённые файлы наследуют этот флаг, и затем Gatekeeper блокирует исполняемый файл и каждую библиотеку в _internal/. Снимите его со всего каталога рекурсивно перед первым запуском:

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

Быстрый старт

Ознакомьтесь с (старыми) руководствами, созданными другими (EN, ES и FR) здесь.

Файлы EVTX

Справка доступна с помощью:

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

Если ваши файлы EVTX имеют расширение ".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 можно опустить: тогда Zircolite использует rules/rules_windows_merged.json, который покрывает Sysmon и общие каналы Windows.

Использование нативных правил Sigma (YAML)

Вы можете использовать нативные правила Sigma (YAML) напрямую:

# 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 показывает установленные пайплайны. Указание не установленного пайплайна останавливает запуск с кодом выхода 2 до преобразования любого правила.

Другие форматы логов

Zircolite автоматически определяет формат логов в большинстве случаев, поэтому явные флаги формата необязательны:

# 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

• Аргумент --events может быть файлом или папкой. Если это папка, будут выбраны все файлы логов в текущей папке и подпапках (используйте --no-recursion, чтобы отключить это).
• Используйте --file-pattern, чтобы задать пользовательский glob-шаблон для выбора файлов.
• Используйте --no-auto-detect, чтобы отключить автоматическое определение формата.

[!TIP] Если вы хотите попробовать инструмент, можете протестировать его с EVTX-ATTACK-SAMPLES (файлы EVTX).

Запуск с 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

• Замените $PWD на каталог (только абсолютный путь), где хранятся ваши логи и правила/наборы правил.
• На хосте Linux добавьте --user "$(id -u):$(id -g)" и -l /case/output/zircolite.log: образ работает от непривилегированного пользователя, который не может писать в принадлежащий вам каталог. См. Docker.

Автоматическая оптимизация обработки

При наличии нескольких файлов Zircolite сопоставляет их с доступной оперативной памятью и CPU, выбирает режим базы данных (одна общая база или по одной на файл) и решает, стоит ли обрабатывать их параллельно — затем адаптирует число рабочих процессов к давлению на память во время работы.

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

Переопределите любое из этого с помощью --no-auto-mode, --unified-db (одна база данных для всех файлов, что необходимо для правил кросс-файловой корреляции), --no-parallel или --parallel-workers N. О том, как делается выбор, см. Автоматическая оптимизация обработки.

Использование конфигурационных файлов YAML

Для сложных или повторяющихся рабочих процессов анализа используйте конфигурационный файл 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/

Сгенерированный файл документирует каждый поддерживаемый ключ с его значением по умолчанию; config/zircolite_example.yaml — это тот же файл, хранящийся в репозитории. О правилах слияния и опциях, не имеющих эквивалента в YAML, см. Конфигурация YAML.

Обновление наборов правил по умолчанию

python3 zircolite.py -U

При запуске из исходного кода это перезаписывает rules/ репозитория. Автономный бинарный файл пишет в каталог rules/ рядом со своим исполняемым файлом и с предупреждением откатывается к ./rules в рабочем каталоге, когда в тот записать невозможно.

В качестве альтернативы, если вы используете Task (go-task), запустите task update-rules из корня проекта, чтобы обновить правила из Zircolite-Rules-v2. О других задачах (сборка Docker, очистка и т. д.) см. docs.

[!IMPORTANT]
Обратите внимание, что эти наборы правил предоставлены для использования Zircolite «из коробки», но вам следует генерировать собственные наборы правил, так как они могут быть шумными или медленными. Эти автоматически обновляемые наборы правил доступны в отдельном репозитории: Zircolite-Rules-v2.

Разделение полей и преобразования

Две возможности конфигурации формируют события во время их приёма, обе в config/config.yaml:

• Разделение полей превращает упакованное поле «ключ-значение» в поля, доступные для запросов. Поле Hashes в Sysmon (SHA1=abc123,MD5=def456,SHA256=789xyz) становится отдельными полями SHA1, MD5 и SHA256, так что правила могут сопоставляться с хешем напрямую.
• Преобразования полей запускают изолированный Python над значением поля — декодирование командных строк base64, извлечение IOC, пометка LOLBins — и могут записывать результат в новое поле вместо замены исходного. Zircolite поставляет 55 таких преобразований в 11 категориях, по умолчанию отключённых, кроме двух для auditd.

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

Полную конфигурацию, поставляемые Zircolite преобразования и способы тестирования собственных см. в разделах Разделение полей и Преобразования полей.

Бенчмарк

Zircolite — самый быстрый из трёх: в 2,1 раза быстрее Hayabusa и в 9,8 раза быстрее Chainsaw — и это единственный из них, написанный на Python, против двух инструментов на Rust.

Те же 4 файла Sysmon EVTX (478 МБ, 452 554 события), каждый инструмент с настройками по умолчанию и своими правилами, на 10-ядерном Apple M1 Max. Медиана из трёх запусков:

Zircolite обменивает память на эту скорость: он запускает один рабочий процесс на файл, и приведённая выше цифра — их суммарное значение. --no-parallel ограничивает его одним процессом.

Наборы правил различаются, поэтому количество обнаружений несопоставимо; о настройке, оговорках и о том, как воспроизвести это с помощью tools/tool-benchmark.py, см. Бенчмарк.

Документация

Полная документация доступна здесь.

Мини-GUI

Мини-GUI можно использовать полностью офлайн. Он позволяет отображать и искать результаты. Вы можете автоматически сгенерировать «пакет» Мини-GUI с помощью опции --package. Используйте --package-dir, чтобы указать выходной каталог. Чтобы узнать, как использовать Мини-GUI, ознакомьтесь с документацией здесь.

Обнаруженные события по техникам MITRE ATT&CK® и уровням критичности

Временная шкала обнаруженных событий

Обнаруженные события по техникам MITRE ATT&CK®, отображённые на матрице

Руководства, ссылки и связанные проекты

Руководства

• Английский: Russ McRee опубликовал подробное руководство по SIGMA и Zircolite в своём блоге.

• Испанский: César Marín опубликовал руководство на испанском здесь.

• Французский: IT-connect.fr опубликовал обширное руководство по Zircolite на французском.

• Французский: IT-connect.fr также опубликовал разбор задания Hack the Box с использованием Zircolite.

Ссылки

• Florian Roth упомянул Zircolite в своём SIGMA Hall of Fame во время своего доклада на EU ATT&CK Workshop в октябре 2021 года.
• Zircolite был упомянут и представлен на JSAC 2023.
• Zircolite упоминался и использовался в многочисленных научных работах:
  • 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

Лицензия

• Весь код проекта лицензирован под GNU Lesser General Public License.
• Разбор EVTX использует evtx (pyevtx-rs) под лицензией MIT или Apache-2.0. Пакеты релизов перечисляют каждую включённую библиотеку и её лицензию в THIRD_PARTY_LICENSES.
• Правила выпущены под Detection Rule License (DRL) 1.1.