winhunt 0.1.1

Windows compromise-assessment CLI: hunts your event logs with Sigma rules (via Hayabusa), then uses AI to correlate the findings into an attack narrative and verdict.

winhunt

Windows compromise-assessment CLI. It hunts your machine's event logs with thousands of community Sigma rules (via the Hayabusa engine), then uses AI to correlate the raw detections into an attack narrative and a verdict — turning a firehose of alerts into "here's what happened, and how worried you should be."

The detection engine is best-in-class and battle-tested; the missing piece it adds is the interpretation layer — prioritization, correlation, and plain-English triage that the underlying tools don't provide.

Why it's different

• Detection: thousands of maintained Sigma rules (not a handful of hand-written ones).
• Correlation: AI stitches related detections into one story (e.g. brute force → new admin → log cleared = likely intrusion).
• Verdict: a single AI-adjusted risk score + clean / suspicious / likely compromised call — it downgrades benign noise (a raw 100/100 of installer/OS churn becomes a calm ~12/100) so it doesn't cry wolf, while still catching real attack chains.
• Explains itself: shows both genuine concerns and what it cleared as benign (e.g. "that was the uv installer / a signed Microsoft module").

Privacy

By default (deep triage), short detail snippets from each detection are sent to the AI so it can tell legitimate software apart from real threats. To keep raw log content on the machine, use --no-deep (AI sees only rule titles/counts/tactics), or --no-ai to skip the model entirely and get the rule-based report.

Install on Windows

winhunt is Windows-only (it analyzes Windows event logs). You need Python 3.10+.

1. Install Python (if you don't have it) — from python.org (tick "Add Python to PATH"), or:

winget install Python.Python.3.12

2. Install pipx (recommended — isolates the tool and puts winhunt on your PATH):

py -m pip install --user pipx
py -m pipx ensurepath

Then close and reopen PowerShell so the PATH change takes effect.

3. Install winhunt + its engine:

pipx install winhunt
winhunt setup        # one-time: downloads the Hayabusa engine + Sigma rules (~41 MB)

4. (Optional) enable the AI verdict — set an Anthropic key. Run winhunt where to see the exact path, then add ANTHROPIC_API_KEY=sk-ant-... to a .env there (or set it as an environment variable). Without a key, winhunt still gives the full rule-based report.

Prefer not to use pipx? pip install winhunt works too — but pipx is recommended for CLI tools (isolated dependencies, clean winhunt command).

Use

winhunt scan                     # hunt the live host + AI verdict (deep triage on)
winhunt scan --no-deep           # AI sees only summaries, not raw detail content
winhunt scan --no-ai             # rule-based only, zero cost
winhunt scan -m high             # only high-and-up (min-level)
winhunt scan --report r.html     # also write an HTML report
winhunt scan --evtx C:\logs      # analyze exported .evtx files instead
winhunt where                    # paths + key status

Run elevated for full coverage. The Windows Security log (logons, account changes, etc.) requires Administrator. Without it, winhunt still scans System / PowerShell / Defender logs but warns that coverage is reduced.

How it works

Sigma rules (Hayabusa)  →  detections  →  group + score  →  AI correlation  →  verdict + report

Built on the excellent Hayabusa and the Sigma project.