mcp-hayabusa

An MCP server that combines 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

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

2. Download the Hayabusa binary and detection rules

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 into that path, e.g.:

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

3. Download the ATT&CK technique lookup

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

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:

{
  "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:

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)