/Zircolite

A standalone SIGMA-based detection tool for EVTX.

Primary LanguagePython

Standalone SIGMA-based detection tool for EVTX, Auditd, Sysmon for linux, XML or JSONL/NDJSON Logs

python version

Zircolite is a standalone tool written in Python 3. It allows to use SIGMA rules on : MS Windows EVTX (EVTX, XML and JSONL format), Auditd logs, Sysmon for Linux, EVTXtract, CSV and XML logs

  • Zircolite is relatively fast and can parse large datasets in just seconds
  • Zircolite is based on a Sigma backend (SQLite) and do not use internal sigma to "something" conversion
  • Zircolite can export results to multiple format with using Jinja templates : JSON, CSV, JSONL, Splunk, Elastic, Zinc, Timesketch...

Zircolite can be used directly in Python or you can use the binaries provided in releases.

Documentation is here (dedicated site) or here (repo directory).

Requirements / Installation

Python 3.8 minimum is required. If you only want to use base functionnalities of Zircolite, you can install dependencies with : pip3 install -r requirements.txt. But pip3 install -r requirements.full.txt is strongly recommanded.

The use of evtx_dump is optional but required by default (because it is -for now- much faster), If you do not want to use it you have to use the --noexternal option. The tool is provided if you clone the Zircolite repository (the official repository is here).

⚠️ On some systems (Mac, Arm, ...) the evtx library may need Rust and Cargo to be installed.

Quick start

EVTX files :

Help is available with zircolite.py -h. If your EVTX files have the extension ".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_sysmon_pysigma.json

The SYSMON ruleset employed is a default one, intended for analyzing logs from endpoints with SYSMON installed.

Auditd / Sysmon for Linux / JSONL or NDJSON logs :

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 JSON_FILE> --ruleset rules/rules_windows_sysmon_pysigma.json --jsononly

ℹ️ If you want to try the tool you can test with EVTX-ATTACK-SAMPLES (EVTX Files).

Run with Docker

# Pull 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

You can replace $PWD with the directory (absolute path only) where your logs and rules/rulesets are stored.

Updating default rulesets

python3 zircolite.py -U

ℹ️ Please note these rulesets are provided to use Zircolite out-of-the-box but you should generate your own rulesets but they can be very noisy or slow. These auto-updated rulesets are available on the dedicated repository : Zircolite-Rules.

Docs

Everything is here.

Mini-Gui

The Mini-GUI can be used totally offline, it allows the user to display and search results. You can automatically generate a Mini-Gui "package" with the --package option. To know how to use the Mini-GUI, check docs here.

Detected events by Mitre Att&ck (c) techniques and criticity levels

Detected events Timeline

Detected events by Mitre Att&ck (c) techniques displayed on the Matrix

Tutorials, references and related projects

Tutorials

  • Russ McRee has published a pretty good tutorial on SIGMA and Zircolite in his blog

  • César Marín has published a tutorial in spanish here

References

Get it from Pypi

BETA : Zircolite is now available on Pypi. You can install it with pip install zircolite. This version don't have the config files and rulesets so you will have to get them and provide them as command line arguments.

License