mcp-hayabusa

An MCP (Model Context Protocol) server that wraps Hayabusa for EVTX (Windows Event Log) analysis. It exposes Hayabusa's detection capabilities as an MCP tool so an MCP client (e.g. Claude Code, Claude Desktop) can drive EVTX analysis conversationally.

The server is a thin wrapper: it shells out to a locally installed Hayabusa CLI binary and translates its JSONL output into a structured MCP tool response, rather than reimplementing any detection logic in Python.

Setup

1. Create a virtual environment and install dependencies

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

2. Download Hayabusa

The Hayabusa binary, detection rules, and config are not checked into this repo (see .gitignore) — they're downloaded release assets, not project source. Fetch them with:

.venv\Scripts\python scripts\download_hayabusa.py

This detects your OS/architecture, pulls the latest release from Yamato-Security/hayabusa, and extracts it into ./hayabusa/ (binary, rules/, config/). Set a GITHUB_TOKEN environment variable first if you hit GitHub API rate limits.

3. Register the MCP server

.mcp.json is already configured to launch the server via the venv's Python:

{
  "mcpServers": {
    "hayabusa": {
      "command": "C:********************.venv/Scripts/python.exe",
      "args": ["server.py"]
    }
  }
}

Update the command path if you cloned the repo elsewhere. Any MCP-compatible client (Claude Code, Claude Desktop) pointed at this config will pick up the hayabusa server automatically.

Usage

Once connected, the server exposes one tool:

scan_evtx

Scans an EVTX file with Hayabusa and returns findings as structured JSON.

Argument	Type	Required	Description
evtx_path	string	yes	Path to the .evtx file to scan
min_severity	string	no	Minimum severity to include: informational, low, medium, high, critical

Example response shape:

{
  "evtx_path": "C:/logs/Security.evtx",
  "min_severity": "high",
  "finding_count": 3,
  "findings": [ { "...": "one JSON object per Hayabusa detection" } ]
}

Errors (missing file, invalid min_severity, missing Hayabusa binary, non-zero Hayabusa exit code, or a scan Hayabusa silently failed to parse) are raised as Python exceptions with a clear message rather than crashing the server.

From an MCP client, just ask conversationally, e.g.:

Scan C:\logs\Security.evtx with Hayabusa and only show me high and critical findings.

Testing

tests/test_scan_evtx.py is a standalone script (not pytest) that downloads a sample EVTX from the EVTX-ATTACK-SAMPLES repo on first run, caches it under tests/fixtures/, and exercises the happy path, severity filtering, and error handling:

.venv\Scripts\python tests\test_scan_evtx.py

Project layout

server.py                  # MCP server + scan_evtx tool
scripts/download_hayabusa.py  # Fetches the latest Hayabusa release into ./hayabusa/
hayabusa/                  # Downloaded binary, rules, config (gitignored)
tests/test_scan_evtx.py    # Standalone functional test
.mcp.json                  # MCP client registration