helixmap/sigwood

Local-first threat hunting for the logs you already have: Zeek, Pi-hole, syslog or the systemd journal, CloudTrail. Every run names the technique behind each detector. No agent, no daemon, no black box - between grep and a SIEM

Summary

sigwood is a local-first, command-line threat-hunting tool written in Python that runs over logs already on your machine (Zeek, Pi-hole, syslog, the systemd journal, or CloudTrail), without installing an agent, running a daemon, or shipping data anywhere. The current 1.1.0 release ships ten detectors — including beaconing, anomalous DNS, port scans, bulk outbound transfers, rare syslog events, and per-principal CloudTrail behavior — and each run names the technique behind its findings (FFT for beacons, HDBSCAN for DNS, drain3 templating for syslog, z-score composite for AWS). The project is positioned explicitly as "between grep and a SIEM," aimed at self-hosters rather than replacing a real SIEM.

What it is useful for

sigwood is useful when you already have logs sitting on disk and want a quick, reproducible way to surface things that look unusual for your environment. Engineers running a homelab with a Pi-hole, a Zeek sensor, or a Linux host whose journal just rotates into a folder can point sigwood at the directory and get findings like periodic outbound callbacks, machine-generated DNS names clustered by an HDBSCAN pass, rare syslog patterns, or anomalous CloudTrail activity for a specific principal. Each finding is described in the README as a lead rather than a verdict, and -v shows the evidence behind every score. A digest verb orients you on a log file you have not met, and a graph verb replays flows as a self-contained HTML file you can share. Six detectors run in the curated default hunt; auth, dnsblock, protocol, and ssl are opt-in.

How engineers can use it

The documented install path is pipx install sigwood (or uv tool install sigwood); the project requires Python 3.11+ and is published on PyPI. The documented quick start is:

pipx install sigwood
sigwood /var/log/                 # a directory
sigwood /opt/zeek/dns.log         # or a single file

For Pi-hole-only setups, the README shows sigwood digest /var/log/pihole/pihole.log first, then sigwood /var/log/pihole/, then sigwood dnsblock /var/log/pihole/. To try it without your own logs, the repo ships demo/gen_corpus.py, which writes a synthetic one-host corpus (no network calls) that the README says exercises beacons, a DGA burst, a bulk transfer out, and the syslog trail. JSON and CSV are the documented machine contracts — the README notes that text, HTML, and PDF layouts may change between releases, while the JSON output carries its own schema_version (currently 1) and bumps only on breaking changes.

Documented limitations to keep in mind: sigwood is agentless and behavior-first, so some attacker activity stays out of view, the exact findings on a given corpus can change between 1.x releases, and the project is explicit that it does not ship threat-intel feeds or signature packs. The manual, FAQ, KNOWN-ISSUES, and stability CONTRACT documents linked from the repository are the source of record for tuning and detector behavior.