Metadata-Version: 2.4
Name: winhunt
Version: 0.1.1
Summary: 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.
Author: zzzzsecurityzzzz
License-Expression: MIT
License-File: LICENSE
Keywords: cli,compromise-assessment,dfir,hayabusa,security,sigma,threat-hunting,windows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: platformdirs>=4.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.32
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# winhunt

**Windows compromise-assessment CLI.** It hunts your machine's event logs with
thousands of community **Sigma** rules (via the [Hayabusa](https://github.com/Yamato-Security/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](https://www.python.org/downloads/)
(tick *"Add Python to PATH"*), or:
```powershell
winget install Python.Python.3.12
```

**2. Install pipx** (recommended — isolates the tool and puts `winhunt` on your PATH):
```powershell
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:**
```powershell
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

```bash
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](https://github.com/Yamato-Security/hayabusa)
and the [Sigma](https://github.com/SigmaHQ/sigma) project.
