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

Zircolite 将 Sigma 检测规则应用于：

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

主要功能

• 格式检测：自动识别日志格式和时间戳字段。可读取 gzip、bzip2、ZIP 和 7-Zip 输入；加密的 ZIP/7z 输入从 --ask-archive-password 或 ZIRCOLITE_ARCHIVE_PASSWORD 环境变量获取密码。
• Sigma 规则：使用 pySigma 的 SQLite 后端转换原生 YAML 规则，或加载预转换的 JSON 规则集。
• 关联分析：计数、统计、时间序列、缺失条件和链式规则，每个告警都附带支持事件。统一模式支持跨文件关联。
• 字段处理：拆分键值字段并应用 Python 转换，包括 Base64 和十六进制解码。
• 导出：JSON、CSV 以及用于 JSONL、Splunk、Elastic、OpenSearch、Timesketch、SARIF 和 ATT&CK Navigator 的 Jinja 模板。
• 终端输出：按严重性排序的检测结果、MITRE ATT&CK 技术和战术、规则覆盖率以及输出链接。

你可以直接使用 Python 运行 Zircolite，也可以下载无需安装 Python 的独立二进制文件。

阅读文档站点或仓库文档。

要求 / 安装

[!NOTE] 源码安装需要 Python 和包管理器。 独立二进制文件和 Docker 镜像 已包含 Python、依赖项和编译好的内核。

该项目已在 Python 3.10 及以上版本中测试。依赖项声明在 pyproject.toml 中；从克隆的仓库使用 PDM（pdm install）、uv （uv sync）或 Poetry（poetry install）安装它们。

以下示例运行 python3 zircolite.py：请激活工具创建的环境， 或在命令前加上 pdm run、uv run 或 poetry run。

依赖项

依赖项声明在 pyproject.toml 中。它们的作用见 依赖项。

⚠️ 首先安装 C 编译器

源码安装使用 C 编译器构建 Cython 扁平化内核。如果编译 失败，构建后端会发出警告，并继续使用较慢的 Python 内核进行安装。 设置 ZIRCOLITE_REQUIRE_NATIVE=1 可要求原生构建必须成功。

要获得原生加速，请在 pdm install 之前安装工具链：

平台	前置条件
Debian、Ubuntu	apt install build-essential python3-dev
RHEL、Fedora、Rocky	dnf install gcc python3-devel
Alpine	apk add build-base python3-dev
macOS	xcode-select --install
Windows	Build Tools for Visual Studio（“使用 C++ 的桌面开发”）

Cython 会作为构建依赖项自动安装。

独立二进制文件

每个发布版本都会为各平台发布一个自包含 包。每个包都自带 Python 和所有依赖项，因此无需预先安装任何内容。

目标平台	归档文件	运行环境
linux-x64	Zircolite-<version>-linux-x64.zip	glibc 2.28 或更高版本：RHEL 8、Debian 10、Ubuntu 20.04 及更新版本
linux-arm64	Zircolite-<version>-linux-arm64.zip	glibc 2.28 或更高版本
macos-arm64	Zircolite-<version>-macos-arm64.zip	macOS 15 或更高版本，Apple 芯片
windows-x64	Zircolite-<version>-windows-x64.zip	Windows 10 或更高版本
windows-arm64	Zircolite-<version>-windows-arm64.zip	Windows 10 或更高版本，ARM64

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 文件

可通过以下命令获取帮助：

# Prefix with pdm run, uv run or poetry run if the environment is not active
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 模式。
• 传入格式标志（--json-input、--xml-input 等）可跳过自动格式检测。

[!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

-U 会安装 SigmaHQ 规则集、随它们发布的社区规则集（各自 遵循自己的许可证，其文本位于 rules/licenses/）以及 rules/experimental/ 中的实验性关联规则集，在此之前会对照规则 仓库的发布清单检查每个文件。从源码运行时，它会写入仓库的 rules/。独立二进制文件会写入其可执行文件旁的 rules/ 目录，当该目录无法写入时，会回退到工作目录中的 ./rules，并发出警告。 参见规则集。