用于 EVTX、Auditd、Sysmon for Linux、XML、CSV 或 JSONL/NDJSON 日志的独立 SIGMA 检测工具

Zircolite 是一个用 Python 3 编写的独立工具，允许你在以下日志上使用 SIGMA 规则：

• MS Windows EVTX（EVTX、XML 和 JSONL 格式）
• Auditd 日志
• Sysmon for Linux
• EVTXtract
• CSV 和 XML 日志
• JSON 数组日志

主要特性

• 快速：452,554 个事件对 4,319 条 Sigma 规则仅需 11.6 秒——在相同日志上比 Hayabusa 快 2.1 倍，比 Chainsaw 快 9.8 倍，而后两者均为 Rust 工具。参见基准测试。
• 自动日志类型检测：使用魔数字节、内容分析和基于正则表达式的回退机制自动识别日志格式和时间戳字段——大多数情况下无需指定格式标志。
• 多种输入格式：支持多种日志格式，包括 EVTX、JSON Lines、JSON 数组、CSV、XML 等。支持压缩或归档日志（gzip、bzip2、ZIP、7-Zip）；对加密的 ZIP/7z 使用 --archive-password。
• 原生 Sigma 支持：Zircolite 可以通过 pySigma 转换后直接使用原生 Sigma 规则（YAML）。
• SIGMA 后端：它基于 SIGMA 后端（SQLite），不使用内部的 SIGMA 到其他格式的转换。
• 高级日志操作：它可以通过拆分字段和应用转换来操作输入日志，从而实现更灵活、更强大的日志分析。
• 字段转换：在处理过程中对字段应用自定义 Python 转换（例如 Base64 解码、十六进制转 ASCII）。
• 灵活导出：Zircolite 可以使用 Jinja 模板将结果导出为多种格式，包括 JSON、CSV、JSONL、Splunk、Elastic、OpenSearch、Timesketch、SARIF、ATT&CK Navigator 等。
• 丰富的终端输出：检测结果以按严重性排序的表格显示，包含 MITRE ATT&CK 技术 ID、ATT&CK 战术热力图、规则覆盖率指标以及可点击的输出文件链接。

你可以直接使用 Python 运行 Zircolite，也可以下载无需安装 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 编译器

从源代码安装会使用 Cython 编译 Zircolite 的扁平化内核——但仅在已存在 C 编译器的情况下。如果没有 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

快速开始

查看其他人制作的（旧）教程（英语、西班牙语和法语）此处。

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 会根据可用 RAM 和 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 构建、清理等），参见文档。

[!IMPORTANT]
请注意，这些规则集是为了开箱即用地使用 Zircolite 而提供的，但你应该生成自己的规则集，因为它们可能产生噪音或运行缓慢。这些自动更新的规则集可在专用仓库中获取：Zircolite-Rules-v2。

字段拆分与转换

两个配置特性会在事件被摄取时塑造它们，二者都在 config/config.yaml 中：

• 字段拆分将打包的键值字段转换为可查询的字段。Sysmon 的 Hashes 字段（SHA1=abc123,MD5=def456,SHA256=789xyz）会变成单独的 SHA1、MD5 和 SHA256 字段，因此规则可以直接匹配哈希值。
• 字段转换在字段值上运行沙箱化的 Python——解码 base64 命令行、提取 IOC、标记 LOLBin——并且可以将结果写入新字段，而不是替换原始字段。Zircolite 附带 11 个类别共 55 个转换，除两个 auditd 转换外默认关闭。

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

有关完整配置、Zircolite 附带的转换以及如何测试你自己的转换，参见字段拆分和字段转换。

基准测试

Zircolite 是三者中最快的：比 Hayabusa 快 2.1 倍，比 Chainsaw 快 9.8 倍——而且它是三者中唯一用 Python 编写的，对手是两个用 Rust 编写的工具。

相同的 4 个 Sysmon EVTX 文件（478 MB，452,554 个事件），每个工具使用其默认设置和各自的规则，在 10 核 Apple M1 Max 上运行。三次运行的中位数：

Zircolite 用内存换取这一速度：它为每个文件运行一个工作进程，上述数字是它们的总和。--no-parallel 会将其限制为单个进程。

规则集不同，因此检测数量不可比较；有关设置、注意事项以及如何使用 tools/tool-benchmark.py 复现，参见基准测试。

文档

完整文档可在此处获取。

迷你 GUI

迷你 GUI 可以完全离线使用。它允许你显示和搜索结果。你可以使用 --package 选项自动生成迷你 GUI“包”。使用 --package-dir 指定输出目录。要了解如何使用迷你 GUI，请查看此处的文档。

按 MITRE ATT&CK® 技术和严重性级别检测到的事件

检测到的事件时间线

在矩阵上显示的按 MITRE ATT&CK® 技术检测到的事件

教程、参考资料和相关项目

教程

• 英语：Russ McRee 在其博客上发布了一篇关于 SIGMA 和 Zircolite 的详细教程。

• 西班牙语：César Marín 在此处发布了一篇西班牙语教程。

• 法语：IT-connect.fr 发布了一篇关于 Zircolite 的详尽法语教程。

• 法语：IT-connect.fr 还发布了一篇使用 Zircolite 的 Hack the Box 挑战解题报告。

参考资料

• Florian Roth 在 2021 年 10 月 EU ATT&CK 研讨会上的演讲中，在其 SIGMA 名人堂中提到了 Zircolite。
• 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 宽通用公共许可证授权。
• EVTX 解析使用 evtx（pyevtx-rs），采用 MIT 或 Apache-2.0 许可证。发布包在 THIRD_PARTY_LICENSES 中列出了每个捆绑库及其许可证。
• 规则根据 Detection Rule License (DRL) 1.1 发布。