Zircolite v3.8.1

Zircolite

Standalone Sigma-based detection for EVTX, Auditd, Sysmon for Linux, XML, CSV and JSON logs

Zircolite runs Sigma rules over your logs. It flattens events into SQLite, turns each rule into an SQL query and reports what matches, offline, in one command.

Zircolite in a terminal

Many log formats, detected automatically: Windows EVTX (binary, XML, JSON), Auditd, Sysmon for Linux, EVTXtract, CSV, XML and JSON, plain or in gzip, bzip2, ZIP and 7-Zip archives.
Sigma rules as they are: native YAML converted with pySigma, or the ready-made rulesets in rules/. Correlation rules included.
Fast: a compiled flattening kernel, parallel workers and rule prefiltering; see the benchmark.
Field processing: split packed fields and run sandboxed Python transforms (Base64 decoding, IOC extraction, LOLBin detection, …).
Exports: JSON, CSV, and templates for Splunk, Elastic, OpenSearch, Timesketch, SARIF and ATT&CK Navigator.
Timeline: every detection as one row in time order, with a one-line summary of the event, as CSV or JSON lines (--timeline).
Zircolite Viewer: every event and detection in one zip that opens offline in a browser.

📖 Read the documentation, also in docs/.

Install

Standalone binary, nothing to install: download the zip for your platform from the releases (Linux x64 and ARM64, macOS Apple silicon, Windows x64 and ARM64).

Docker:

docker pull wagga40/zircolite:latest

From source with PDM, Python 3.11 to 3.14:

git clone https://github.com/wagga40/Zircolite.git
cd Zircolite
pdm use -f 3.14
pdm install

pdm use keeps PDM away from Python 3.15 and free-threaded builds, which are not supported yet; any of 3.11 to 3.13 works as well. With uv:

git clone https://github.com/wagga40/Zircolite.git
cd Zircolite
uv sync --python 3.14+gil

Source installs compile a native flattening kernel and need a C compiler for it; without one they fall back to a slower Python kernel. See Installation for compiler packages, binary details (macOS quarantine, checksums) and Docker permissions.

Quick start

# Windows logs, with the default ruleset (rules/rules_windows_merged.json)
python3 zircolite.py --events sysmon.evtx

# Linux logs: the format is detected
python3 zircolite.py --events auditd.log --ruleset rules/rules_linux.json

# Native Sigma rules, through pySigma pipelines
python3 zircolite.py --events logs/ --ruleset ./sigma/rules/windows/process_creation \
    --pipeline sysmon --pipeline windows-logsources

# Every event and detection, for the Zircolite Viewer
python3 zircolite.py --events logs/ --package

# The detections as a timeline, for Timeline Explorer or a spreadsheet
python3 zircolite.py --events logs/ --timeline

With a binary, run ./Zircolite instead of python3 zircolite.py. From source, prefix the command with pdm run (or uv run) unless the environment is active. With Docker, mount the logs and give absolute paths:

docker run --rm --tty -v $PWD:/case/input:ro -v $PWD:/case/output \
    wagga40/zircolite:latest --events /case/input -o /case/output/detected_events.json

On a Linux host, add --user "$(id -u):$(id -g)" and -l /case/output/zircolite.log: the image runs as an unprivileged user that cannot write to a directory you own.

Detections go to detected_events.json. For logs to try it on, see EVTX-ATTACK-SAMPLES.

[!IMPORTANT] The default rulesets can contain noisy or slow rules. Select rules for your environment, and update them with python3 zircolite.py -U.

How it works

Zircolite flattens each event into a row of an SQLite table, converts every Sigma rule into an SQL query over that table, and reports the rows that match.

How Zircolite works: logs are flattened into rows of an SQLite table, Sigma rules become SQL queries, and matching rows become detections

Zircolite Viewer

--package writes one zip holding every event of the run, with the detections and correlation alerts linked to them. Extract it and open index.html: the viewer runs offline and offers an overview, the detections, an event table you can search, filter and sort by any column, a timeline, the ATT&CK matrix, entities, stacking of the rarest values, logons and lateral movement, process trees and an SQL console. Share a package as you would the logs it came from. See Zircolite Viewer.

A tour of the Zircolite Viewer: the Overview, a critical detection and its events, a column filter and a column's rarest values, an event with its PowerShell command decoded and its process activity, the timeline, the ATT&CK matrix, entities, stacking, lateral movement and privileged sessions, the process tree and the SQL console

Benchmark

Median wall time on a 10-core Apple M1 Max, each tool at its defaults with its own rules:

Tool	4 Sysmon EVTX, 478 MB	8 EVTX over 11 channels, 13.3 GB
Zircolite	7.7 s	30.2 s
Hayabusa 4.2.0	23.3 s	500.3 s
Chainsaw 2.17.1	48.3 s	183.0 s

Zircolite uses more memory than the others, through its parallel workers (--no-parallel turns them off), and the rule sets differ, so detection counts do not compare. See Benchmark for memory, setup and how to reproduce it.

Tutorials, written for earlier versions:

English: Sigma and Zircolite, Russ McRee.
Spanish: Running Sigma rules on EVTX files, César Marín.
French: Windows log investigation and Hack the Box challenge write-up, IT-Connect.

References: