# mcp-hayabusa

An [MCP](https://modelcontextprotocol.io) server that combines [Hayabusa](https://github.com/Yamato-Security/hayabusa), the Rust-based Windows event log (EVTX) fast forensics and threat-hunting tool, with a small detection engineering knowledge base — so an LLM client like Claude Code can scan EVTX files, browse detection rules, and reason about ATT&CK coverage directly in conversation.

Point Claude at a `.evtx` file and ask it to find suspicious logons, lateral movement, or persistence activity — it drives Hayabusa under the hood and gets back structured JSON it can reason about. Or ask it "what detects T1003.001?" and it'll cross-reference this repo's curated Sigma rules against MITRE ATT&CK and tell you whether that technique is covered, partially covered, or a gap — and scaffold a new rule if it's a gap.

## Tools

### `scan_evtx`

Runs Hayabusa's `json-timeline` command against a single EVTX file and returns matched events as JSON.

| Argument | Description |
|---|---|
| `path` | Path to the `.evtx` file to scan. |
| `min_severity` | Minimum severity to include: `informational`, `low`, `medium`, `high`, `critical`. Defaults to `informational` (no filtering). |
| `rule_filter` | Only include events whose rule title contains this substring (case-insensitive), e.g. `"lateral"` or `"mimikatz"`. |
| `output_format` | `summary` (default) returns condensed fields (timestamp, rule title, level, computer, channel, event ID, record ID); `full` returns the complete Hayabusa record. |
| `max_results` | Caps the number of events returned. `event_count` in the response always reflects the total before truncation. |

### `get_hayabusa_rules`

Lists available Hayabusa/Sigma detection rules, optionally filtered by keyword — useful for discovering what detections exist, or for finding the right `rule_filter` value before calling `scan_evtx`.

| Argument | Description |
|---|---|
| `keyword` | Only include rules whose title, description, or tags contain this substring (case-insensitive). |
| `max_results` | Caps the number of rules returned (default `100`; the full set has several thousand entries). `rule_count` always reflects the total before this cap. |

### `analyze_coverage`

Reports whether this repo's curated Sigma rules (`rules/`) detect a given ATT&CK technique or tactic — each technique is `covered` (a detecting rule at or above the `high` severity threshold), `partial` (a detecting rule below it), or a `gap` (no detecting rule at all).

| Argument | Description |
|---|---|
| `query` | An ATT&CK technique ID (e.g. `"T1558.003"` or `"1558.003"`) for a single-technique report, or a tactic name (e.g. `"credential-access"`) for a report across every technique in that tactic, grouped by coverage status. |

### `suggest_rule`

Checks coverage for an ATT&CK technique and, if it's not already covered, suggests how to detect it: a technique summary, log-source guidance for the relevant tactic, and up to three existing curated rules for sibling techniques to use as a style reference.

| Argument | Description |
|---|---|
| `technique_id` | ATT&CK technique ID, e.g. `"T1110.003"` or `"1110.003"`. |
| `create_template` | If `true` and the technique isn't already covered, writes a skeleton Sigma YAML file into `rules/` (title/description/detection block full of `TODO` placeholders, tagged with the technique's tactics and ID). Never overwrites an existing file. Defaults to `false`. |

## Resources

Alongside the four tools above, the server exposes curated Sigma rules and ATT&CK technique metadata as MCP resources:

| URI | Returns |
|---|---|
| `detection://rules` | All curated Sigma rules in `rules/`, with ATT&CK technique IDs extracted from each rule's tags. |
| `detection://rules/{rule_name}` | The raw Sigma YAML for one rule, addressed by filename stem. |
| `detection://rules/by-technique/{technique_id}` | Curated rules mapped to a given ATT&CK technique ID (e.g. `T1003.001`). |
| `detection://attack/techniques/{technique_id}` | MITRE's technique metadata (name, description, tactics) plus this repo's coverage verdict for it — the same data `analyze_coverage`/`suggest_rule` use. |

## Setup

### 1. Create a virtual environment and install dependencies

```powershell
py -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Download the Hayabusa binary and detection rules

```powershell
py scripts/download_hayabusa.py
```

This fetches the latest Hayabusa release for your platform from GitHub and extracts it into `./hayabusa/`. The server expects the binary at `hayabusa/hayabusa.exe` on Windows (or `hayabusa/hayabusa` on Linux/macOS) — rename the downloaded, versioned binary (e.g. `hayabusa-3.10.0-win-x64.exe`) to that name if needed.

Detection rules are expected at `hayabusa/rules/` (Hayabusa's own `hayabusa` and `sigma` rule sets). Clone them from the [official rules repo](https://github.com/Yamato-Security/hayabusa-rules) into that path, e.g.:

```powershell
git clone https://github.com/Yamato-Security/hayabusa-rules.git hayabusa/rules
```

### 3. Download the ATT&CK technique lookup

```powershell
py scripts/download_attack_data.py
```

This fetches the MITRE ATT&CK Enterprise data and writes a compact `technique_id -> {name, description, tactics, url}` lookup to `mappings/attack_techniques.json`. It's gitignored and regenerated locally, so this step is required before `analyze_coverage`, `suggest_rule`, or the `detection://attack/*` resource will work. This repo's curated Sigma rules (`rules/`) are already checked in and don't need a download step.

### 4. Verify

```powershell
py server.py
```

The server communicates over stdio, so it won't print anything on success — it's ready for an MCP client to connect.

## Connecting to Claude Code

This repo includes an `.mcp.json` with the server already configured:

```json
{
  "mcpServers": {
    "hayabusa": {
      "command": "py",
      "args": ["server.py"]
    }
  }
}
```

With this file present at the project root, Claude Code picks it up automatically when you open the project — no extra registration step needed. To add it manually to another project instead, run:

```powershell
claude mcp add hayabusa -- py "C:\path\to\mcp-hayabusa\server.py"
```

Once connected, ask Claude something like *"Scan this EVTX file for high-severity events"*, *"What Hayabusa rules cover lateral movement?"*, or *"Do we have detection coverage for T1003.001?"* and it will call `scan_evtx`, `get_hayabusa_rules`, `analyze_coverage`, or `suggest_rule` directly.

## Requirements

- Python 3.10+
- Windows, Linux, or macOS (Hayabusa ships native binaries for all three)