sigwood is a local-first, agentless threat-hunting CLI that profiles and analyzes logs you already own — Zeek, Pi-hole, syslog, and CloudTrail — for authorized defensive work.
| Tool | helixmap/sigwood — local-first, agentless threat-hunting CLI for logs at rest, positioned "between grep and a SIEM" |
| Category | Defensive log analysis / behavioral detection (Python, MIT-licensed) |
| Primary Use | Running behavioral detectors — beacon, dns, syslog, scan, exfil, ssl, aws — over existing Zeek, Pi-hole, syslog, and CloudTrail logs on your own machine |
| Safe Use | Purely defensive: threat hunting and triage on logs from systems you own or administer, in labs, homelabs, or authorized security assessments; logs never leave the host |
| Telemetry Note | Leaves essentially no footprint on production systems — it is agentless and reads logs at rest; defenders observe its use only as local process activity and read I/O on log directories, with no network egress or daemon |
sigwood is a Python command-line threat-hunting tool built for self-hosters and small defensive teams who have logs but no SIEM budget. Its self-description — "between grep and a SIEM" — is an accurate placement: it accepts directories or single files of logs you already collect (Zeek conn.log/dns.log/ssl.log, Pi-hole or dnsmasq output, syslog and the systemd journal, and CloudTrail JSON), profiles what is in them, and then runs ten behavioral detectors over the data. There is no database, no daemon, no agent, no account, and no network calls; it runs on your own box over logs at rest, which makes it unusually easy to justify from a data-handling perspective in authorized environments.
The repository reports version 1.2.0 as stable, with the detectors covered by tests, supports Python 3.11 through 3.14, and is MIT-licensed with around 181 stars. Installation is deliberately boring: pipx install sigwood is the recommended path, with uv tool install sigwood and a plain venv as equivalents, and the package deliberately refuses install on Python 3.15 until its dependency stack ships wheels. After that, the entry point is just sigwood /var/log/ for a directory or sigwood /opt/zeek/dns.log for a single file — no configuration required to get a first pass.
The detector suite is where the engineering shows. beacon looks for periodic C2-style callbacks by running an FFT over connection timing in Zeek conn.log — the classic fixed-rhythm exfil channel. dns hunts DGA-style lookups and tunneling via HDBSCAN clustering over per-query behavior, and it works against both Zeek dns.log and Pi-hole logs, adapting to whichever fidelity it is handed. syslog applies drain3 log templating plus rarity scoring to surface rare event patterns and recorded reboots, reading from the live systemd journal, flat rsyslog files, or Zeek's syslog.log. aws computes a per-principal z-score composite over CloudTrail activity (including .gz-compressed JSON) to flag anomalous IAM behavior.
Four detectors are opt-in rather than part of the curated default hunt: dnsblock (behavioral patterns in names your Pi-hole already blocked), auth (authentication structure — failure concentration, volume, spread, and landings), protocol (expected-port mismatch and newly unlabeled payloads), and ssl (outbound TLS setups unlike your estate's norm, using ssl.log and x509.log). The remaining two, scan (vertical, horizontal, block, and slow port scans) and exfil (bulk outbound byte transfer), are heuristic pattern detectors over conn.log. You can invoke any detector as its own subcommand (sigwood beacon ~/zeek), select subsets with --detect, or run everything with --detect=all.
The interface design rewards reading the output rather than staring at scores. The README's illustrative run — explicitly synthetic, using RFC 5737 documentation addresses and example domains — shows a coherent narrative: high-entropy DNS names clustered under one disposable domain, two outbound connections on fixed periods (a 3-minute and a 10-minute rhythm), and a root SSH login from one of the same IPs. The key epistemic framing is stated plainly: a finding means "unusual for your network," not "known-bad"; it is a lead, not a verdict, and HIGH severity is deliberately scarce. Adding -v explains the evidence behind each finding and suggests next steps to run it down.
Several supporting subcommands round out the workflow. sigwood digest produces a fast factual profile of a file before you hunt — orientation first, which is good tradecraft. sigwood graph replays conn.log flows as a self-contained HTML artifact (an animated Sankey of hosts, services, and destinations), and the tool can emit its findings as an HTML report. sigwood init writes a detection-driven config, and sigwood hunt runs the curated default set. For evaluation without production data, the repo ships a synthetic corpus generator (demo/gen_corpus.py) that simulates one compromised host — beacons, a DGA burst, a bulk transfer, and the syslog trail — with no network calls, letting you watch the whole detection chain in a lab before pointing it at real logs.
The project's documentation posture is unusually honest for a tool this young. An EVIDENCE.md ledger records what has and has not been measured for every detector, a FIELDKIT.md provides a privacy-bounded way to validate on environments that did not shape development, and the README openly states the tool was built with heavy AI assistance under human review, with an FAQ explaining the process. There are also MANUAL, CONTRACT, SCHEMA, ROADMAP, KNOWN-ISSUES, and REFERENCES documents, plus a SECURITY.md — a paper trail that matters when you are choosing what to trust for detection logic.
Architecturally, the design philosophy is behavior-first and explicitly anti-enumeration. The roadmap maps coverage onto the MITRE ATT&CK matrix tactic by tactic, including which gaps will never close — some because closing them would mean shipping threat-intel feeds or signature packs, others because agentless design cannot see them at all (endpoint telemetry, for instance, is out of scope). The stated muse is the top of the "pyramid of pain" — catching attacker behaviors that are expensive to change (timing, structure, rhythm) rather than indicators that rotate. Every run names the technique behind each detector, which makes findings auditable and teachable rather than black-box scores.
For defenders, sigwood fills a real gap: the homelab, small-business, or consultancy context where grep over logs is the status quo but a full SIEM is overkill. Operationally, the sensible workflow is digest for orientation, hunt for the curated pass, then targeted detector subcommands with -v for triage of anything interesting. Because findings are anomaly-relative to your own baseline, first runs on noisy or short-history logs will need tuning expectations — rarity and z-score methods need representative data before they mean much. The dns and syslog detectors adapting across source families (Zeek, Pi-hole, journal, rsyslog) makes it practical for heterogeneous estates where you cannot standardize on one log format.
Nothing here facilitates offense — there is no payload, no exploitation, and no outbound capability; the entire tool is a read-only analytical pass over local files. That makes the compliance picture trivial: use it on logs from systems you own or are contractually authorized to defend, keep it lab-side when learning via the synthetic corpus, and be aware that because it is agentless it sees only what your logs already capture — network flows, DNS, auth, and cloud API events — leaving endpoint-resident behavior to other tooling. For a first-party, evidence-documented, no-telemetry hunting utility, sigwood is a credible addition to a lightweight defensive stack.
helixmap/sigwood.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.