Автономный инструмент обнаружения на основе 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

Ключевые особенности

• Автоматическое определение типа журнала: автоматически определяет форматы журналов и поля временных меток с помощью magic bytes, анализа содержимого и запасного варианта на основе регулярных выражений — в большинстве случаев не нужно указывать флаги формата.
• Несколько входных форматов: поддерживает различные форматы журналов, включая EVTX, JSON Lines, JSON Arrays, CSV, XML и другие. Поддерживаются сжатые или архивные журналы (gzip, bzip2, ZIP, 7-Zip); используйте --archive-password для зашифрованных ZIP/7z.
• Встроенная поддержка 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 3.10 и выше. Установите зависимости с помощью: pip3 install -r requirements.txt.

Зависимости

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

⚠️ На некоторых системах (Mac, ARM и т. д.) библиотека Python evtx может требовать установки Rust и Cargo.

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

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

Файлы EVTX

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

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

Использование нативных правил 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

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

В большинстве случаев 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 на каталог (только абсолютный путь), в котором хранятся ваши журналы и правила/наборы правил.

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

При наличии нескольких файлов 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

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

[!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, и способы тестирования собственных см. в разделах Разделение полей и Преобразования полей.

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

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

Мини-GUI

Мини-GUI можно использовать полностью офлайн. Он позволяет отображать и искать результаты. Вы можете автоматически сгенерировать «пакет» Mini-GUI с помощью опции --package. Используйте --package-dir, чтобы указать выходной каталог. Чтобы узнать, как использовать Mini-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 во время выступления на семинаре EU ATT&CK Workshop в октябре 2021 года.
• Zircolite цитировался и был представлен на JSAC 2023.
• Zircolite цитировался и использовался в нескольких научных работах:
  • Команда CIDRE:
    • PWNJUTSU — Веб-сайт
    • PWNJUTSU — Научная статья
    • 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_dump распространяется под лицензией MIT.
• Правила выпущены в соответствии с Detection Rule License (DRL) 1.0.