Sigmacatch

⚠️ WIP — this project is under active development. APIs, config, and output formats may change without notice. Not production-ready.

Capture real Windows events via the Windows Event Log API (winevt), match them against SigmaHQ rules, and output structured regression data ready for SigmaHQ PRs.

What it does

SigmaHQ rules (auto-cloned via grit-lib)
    ↓
Load rules → skip existing regression → filter Windows → apply pipeline
    ↓
Resolve channels from rules (logsource → channel mapping)
    ↓
Continuous collector (live Windows events via EvtQueryW) → mpsc
    ↓
Sigma engine evaluates every event against all loaded rules
    ↓
Every 30s: generate regression triplet for each matched rule
    ↓
sigma/regression_data/<rule_rel_path>/
    ├── <rule_id>.json    ← flat event (Sigma keys)
    ├── <rule_id>.evtx    ← valid EVTX (via EvtExportLog, validated ≥1 record; no data on non-Windows)
    └── info.yml          ← SigmaHQ-compatible metadata
    ↓
commit + push to fork (continuous until Ctrl+C)

Quick start

cargo build --release
./target/release/sigmacatch

On first run, a config.yaml is created with defaults:

git:
  author: "your-username"
  email: "you@example.com"
  github_token: ""          # GitHub token (or set GITHUB_TOKEN env var) — required for HTTP transport when network is active
  transport: http           # http or ssh
  ssh_key_path: ""          # path to SSH private key (optional, only needed for SSH)
  sigma_repo_url: "https://github.com/SigmaHQ/sigma.git"
  sigma_repo_path: "sigma"
  offline: false            # true = skip pull at startup (use existing repo as-is)
  contrib: true             # true = push commits to remote fork. Default: false (local commits only)
log:
  level_file: "debug"
filter:
  product: windows          # windows, linux, or macos
  min_status: "stable"      # load rules with status >= this threshold
  min_level: "critical"     # load rules with level >= this threshold
  author: ""                # filter rules by author (optional, empty = no filter)
  max_rule_size: 1048576    # bytes (1MB default)

Rules below the configured min_status / min_level thresholds are skipped at load time. Rules missing a status or level field are always accepted.

Contrib is opt-in (git.contrib: true or --contrib): pushes regression commits to your fork. By default (false) commits stay local. The GitHub token is only required when a network operation is active (offline: false or contrib: true).

CLI flags

Flag	Description
--author <name>	Override detected username
-a, --all-rules	Load all rules — skip set is disabled
-c, --contrib	Enable push to the remote fork for this run
-o, --offline	Skip pull at startup (use existing repo as-is)
-v, --verbose	Show info-level logs on stderr (default: errors only)
--help, -h	Print help and exit

Dev tools in tools/ (run with cargo run --release --bin <tool>): check_dry_run (git diagnostics), check_channels (resolved channels), list_rules (loaded rules with techniques + ART link), check_filter, check_evtx, get_atomic (generates run_atomic.ps for rules without regression data), coverage (rule coverage stats).

Git clone performance (grit-lib vs native git)

The Sigma repo (~131K objects) is cloned and pulled through grit-lib (pure Rust, no git CLI). A fresh clone is slower and larger than a native git clone:

	git clone (native, single-branch)	sigmacatch (grit-lib + pack)
Time	~3s	~70s
.git/ size	52 MB	218 MB
Pack file	47 MB (delta-compressed)	215 MB (no delta)
git fsck --strict	clean	clean

Why the difference:

• Native git writes the server's already delta-compressed pack directly to disk — no post-processing.
• grit-lib's http_fetch unpacks every object to a loose file (131K files, ~650 MB), then sigmacatch re-packs them (no delta compression) to keep .git/ small (218 MB vs 650 MB, 3x).

The download itself is identical (~47 MB); the gap is local post-processing, inherent to grit-lib. This cost is paid once at first clone — subsequent pulls only transfer deltas (sub-second when nothing changed). On a slow VM the first clone can take a few minutes.

Requirements

• Windows with Sysmon installed — required for rich events (ParentImage, CommandLine, hashes, etc.)
• Rust 2021 edition (1.70+)
• Admin rights for Security and System Event Log channels

Cross-compilation (Linux → Windows)

cargo xwin build --release --target x86_64-pc-windows-msvc

Nécessite cargo install cargo-xwin. Télécharge automatiquement le Windows SDK.

On Linux/macOS the collector is a stub (returns empty vec) — the pipeline still runs end-to-end for testing.

Documentation

A built version of this documentation is published to GitHub Pages: https://frack113.github.io/sigmacatch/

	English	Francais
Architecture	EN	FR
Architecture reference	EN	FR
Build	EN	FR
Git	EN	FR
Output format	EN	FR
Regression data format	EN	FR
Nice-to-have	EN	FR
Tools	EN	FR

Workspace

The project is a cargo workspace of 11 crates (9 libraries + 2 binary crates):

Crate	Purpose
sigmacatch	Binary + orchestration (continuous loop)
sigmacatch-config	Config YAML + CLI parsing + custom_channels.yaml + dry-run git diagnostics
sigmacatch-logger	Two-layer tracing subscriber (stderr error by default, info with -v; daily rolling file debug)
sigmacatch-rule	SigmahqRules: rule loading, filtering, deduplication, channel resolution
sigmacatch-detection	Thin wrapper around rsigma-eval (pipelines, bloom, LogSourceExtractor)
input-windows-channels	Multi-channel Winevt collector (EvtQueryW/EvtNext/EvtRender)
sigmacatch-regression	SigmahqRegression, InfoYml, regression triplet generation
sigmacatch-types	Shared types: Event, Alert, RegressionHeader, XML parsing, logsource tables
sigmacatch-repo	grit-lib wrapper: SigmaRepo, GitHub fork detection, commit workflow
input-evtx	Parse EVTX files into Event objects for the detection engine
tools	Dev tools: check_dry_run (git diag), check_channels (channels), list_rules (rules), check_filter (filter validation), check_evtx (regression validation), get_atomic (generates run_atomic.ps), coverage (rule coverage stats)

Built with

• rsigma-eval + rsigma-parser — Sigma rule loading and evaluation
• grit-lib — pure Rust git, no CLI needed
• tokio — async runtime
• windows — Windows Event Log API, cfg-gated
• serde / serde_json / yaml_serde — serialization
• roxmltree — XML parsing for Winevt events
• evtx — EVTX file parsing

License

MIT