Hayabusa MCP Server

An MCP (Model Context Protocol) server that connects Claude to Hayabusa, a Windows event log (EVTX) forensics timeline generator and threat hunting tool. It lets an LLM agent run real Hayabusa scans against Windows event logs and reason about the results in plain conversation, instead of a human manually running CLI commands and reading raw CSV output.

Overview

Hayabusa is a fast, Rust-based command-line tool built by Yamato Security that parses Windows Event Log (.evtx) files and matches them against thousands of Sigma-based detection rules to flag suspicious activity — failed logons, lateral movement, persistence mechanisms, credential access, and more.

This project wraps that CLI tool as an MCP server: a small Python process that exposes Hayabusa's subcommands as tools an MCP-compatible client (such as Claude Desktop or Claude Code) can call. Instead of memorizing Hayabusa's flags, a user can just ask Claude in natural language — "scan these event logs and tell me if anything looks suspicious" — and Claude invokes the appropriate tool, reads back a summarized result, and explains it.

The cybersecurity problem it solves

Windows event logs are one of the richest sources of forensic evidence during incident response and threat hunting, but they're also one of the least accessible:

• A single .evtx file can contain tens of thousands of events in a dense, semi-structured format that isn't practical to read by hand.
• Detection rules (Sigma/Hayabusa rules) require domain knowledge to write and interpret — knowing that an alert fired is only half the job; understanding why it matters takes security expertise.
• Junior analysts and students often have the tool access but not yet the pattern-recognition experience to triage results quickly; senior analysts have the experience but limited time to review every log by hand.

This project closes that gap by giving an LLM direct, structured access to Hayabusa's output. Claude can run a scan, get back event counts grouped by severity (Level) instead of a raw CSV dump, and use its own reasoning to help explain what a given alert means, which events look most urgent, and what to investigate next — while the actual detection logic still comes from Hayabusa's vetted rule engine, not from the LLM guessing.

How MCP connects Claude to Hayabusa

┌─────────────┐        MCP (stdio)        ┌───────────────────┐      subprocess       ┌───────────┐
│   Claude     │ ◄──────────────────────► │  mcp-hayabusa       │ ◄──────────────────► │ hayabusa   │
│ (Desktop/CLI)│   JSON-RPC tool calls     │  (this project)     │   CLI invocation      │  .exe      │
└─────────────┘                           └───────────────────┘                        └───────────┘
                                                     │
                                                     ▼
                                           reads/writes .evtx, .csv

1. Claude (the MCP client) launches mcp-hayabusa as a local subprocess and talks to it over the MCP protocol (JSON-RPC over stdio).
2. On startup, the server (built with the mcp Python SDK's FastMCP) advertises its available tools — e.g. hayabusa_csv_timeline, hayabusa_search — along with a description and parameter schema for each, generated from Python type hints and docstrings.
3. When the user asks something that maps to one of those tools, Claude calls it with structured arguments (e.g. {"directory": "C:\\logs", "extra_args": ["-m", "medium"]}).
4. The server translates that call into a real hayabusa <subcommand> ... invocation via Python's subprocess, waits for it to finish, and reads back the result.
5. For scans that produce large output files (like csv-timeline), the server doesn't return the raw file to Claude — it parses the CSV and returns a compact summary (total event count, counts grouped by alert Level, and a small row sample), plus the full file path so a human (or Claude, via other tools) can inspect the complete results directly.
6. Claude uses that summary to answer the user in natural language, and can chain further tool calls (e.g. hayabusa_search for a specific keyword) based on what it sees.

MCP is what makes this generic: the same server works unmodified with any MCP-compatible client, and Claude doesn't need any Hayabusa-specific training — the tool descriptions are the documentation it reads at connection time.

Main features

• Six MCP tools covering the most common Hayabusa workflows: building a detection timeline, searching logs, summarizing logons, and reporting event-ID/rule metrics.
• Result summarization, not raw dumps — hayabusa_csv_timeline parses its own CSV output and returns event counts by severity level plus a small sample, so a large scan doesn't blow past the model's context window.
• Subcommand allowlist — the wrapper only ever invokes a fixed set of known-safe Hayabusa subcommands (ALLOWED_SUBCOMMANDS in hayabusa.py), rather than passing arbitrary attacker-or-model-controlled strings straight to a shell.
• No shell interpolation — all commands are built as argument lists and run with subprocess.run(..., shell=False), which avoids shell/command-injection risk even though inputs (file paths, keywords) can come from model-generated text.
• Version-tolerant flag handling — only the input/output flags (-d, -f, -o) are hardcoded, since Hayabusa's other flags have changed across releases; everything else (rules directory, minimum level, output profile) is passed through an explicit extra_args list rather than guessed.
• Configurable, fail-fast binary lookup — the Hayabusa binary path is resolved once via HAYABUSA_PATH (or PATH), lazily on first tool call, with a clear error if it can't be found.
• Unit-tested without needing the real binary — tests mock subprocess.run, so the argument-building logic and CSV summarization can be verified in CI without installing Hayabusa or providing real .evtx files.

Project architecture

The server is a thin, layered wrapper — it does not reimplement any detection or log-parsing logic itself; all of that stays inside the Hayabusa binary.

Claude (MCP client)
      │  MCP tool calls (JSON-RPC / stdio)
      ▼
server.py        FastMCP app + @mcp.tool() functions.
                  Thin adapters: validate/shape arguments, call into hayabusa.py,
                  and summarize large results before returning them to the model.
      │
      ▼
hayabusa.py       subprocess wrapper. run_subcommand() is the single choke point every
                  call goes through — it enforces the ALLOWED_SUBCOMMANDS allowlist and
                  invokes the binary with an explicit argument list (no shell=True).
                  Convenience functions (csv_timeline, search, logon_summary, ...) build
                  argument lists on top of it. summarize_csv_timeline() reads scan output
                  back off disk and reduces it to counts + a sample.
      │
      ▼
config.py         Resolves the hayabusa binary path from HAYABUSA_PATH (env var) or PATH,
                  and reads HAYABUSA_TIMEOUT_SECONDS. Raises a clear error if the binary
                  can't be found; resolved lazily so the server can still start and list
                  its tools before Hayabusa is configured.
      │
      ▼
hayabusa.exe      The actual Hayabusa binary (external dependency, not bundled).
                  Reads .evtx files, applies Sigma-based detection rules, writes
                  CSV/JSON/stdout output.

Technologies used

• Python 3.10+ — implementation language
• mcp Python SDK (FastMCP) — MCP server framework: tool registration, JSON-RPC/stdio transport, schema generation from type hints
• subprocess (standard library) — safe, shell-free invocation of the Hayabusa CLI
• csv (standard library) — parsing Hayabusa's CSV timeline output for summarization
• Hayabusa (Rust, external binary) — the actual event-log parsing and Sigma-rule detection engine this project wraps
• pytest — unit tests, with subprocess.run mocked out
• pyproject.toml / setuptools — packaging, editable installs, console-script entry point

Installation and setup (Windows)

Prerequisites

• Python 3.10 or later
• The hayabusa binary, downloaded separately — this project does not bundle, download, or install it

Steps

# 1. Clone or download this repository, then from its root:
python -m venv .venv
.venv\Scripts\Activate.ps1

# 2. Install the project (editable install) plus dev/test dependencies
pip install -e ".[dev]"

# 3. Run the tests to confirm the install worked (no hayabusa binary required for this)
pytest

Configuring HAYABUSA_PATH

The server needs to know where the Hayabusa binary lives. Set the HAYABUSA_PATH environment variable to its full path — if it isn't set, the server falls back to looking for hayabusa (or hayabusa.exe) on your system PATH.

PowerShell (current session only):

$env:HAYABUSA_PATH = "C:\tools\hayabusa\hayabusa.exe"

PowerShell (persist across sessions, current user):

[System.Environment]::SetEnvironmentVariable("HAYABUSA_PATH", "C:\tools\hayabusa\hayabusa.exe", "User")

Or, if you'd rather not set an environment variable at all, just add the folder containing hayabusa.exe to your PATH instead — the server will find it automatically.

If HAYABUSA_PATH is unset and nothing named hayabusa/hayabusa.exe is found on PATH, tool calls will fail with a clear HayabusaNotFoundError explaining how to fix it.

Running the server

mcp-hayabusa

or, without relying on the installed console script:

python -m mcp_hayabusa.server

For interactive debugging (lets you call tools by hand and inspect responses) via the MCP Inspector:

mcp dev src/mcp_hayabusa/server.py

Registering with Claude Desktop / Claude Code

Add an entry to your MCP client config (e.g. claude_desktop_config.json, or via claude mcp add):

{
  "mcpServers": {
    "hayabusa": {
      "command": "mcp-hayabusa",
      "env": {
        "HAYABUSA_PATH": "C:\\tools\\hayabusa\\hayabusa.exe"
      }
    }
  }
}

Example usage

Once the server is registered with Claude, a conversation might look like this:

You: I have some Windows Security event logs from a suspicious host at C:\incident\host23. Can you build a detection timeline and tell me if anything stands out?

Claude: (calls hayabusa_csv_timeline with directory="C:\\incident\\host23")

I ran a scan across that directory — 4,812 events total. Severity breakdown: 3 critical, 12 high, 47 medium, the rest informational. The critical alerts are all related to potential credential dumping (LSASS access). Want me to pull the full detail on those three events, or search for related activity around the same timestamps?

You: Search for "lsass" across the same logs.

Claude: (calls hayabusa_search with directory="C:\\incident\\host23", keywords=["lsass"])

Found 9 matching events...

Equivalent direct tool calls (what Claude actually sends under the hood):

{
  "tool": "hayabusa_csv_timeline",
  "arguments": {
    "directory": "C:\\incident\\host23",
    "extra_args": ["-m", "medium"]
  }
}

{
  "tool": "hayabusa_search",
  "arguments": {
    "directory": "C:\\incident\\host23",
    "keywords": ["lsass"]
  }
}

Available tools

Tool	Purpose
hayabusa_csv_timeline	Scan .evtx file(s)/directory into a CSV detection timeline; returns a summary (total events, counts by Level, sample rows) plus the full output file path
hayabusa_search	Keyword/regex search across .evtx file(s)/directory
hayabusa_logon_summary	Summarize successful/failed logon events
hayabusa_eid_metrics	Event counts/percentages by Event ID
hayabusa_list_profiles	List available output profiles
hayabusa_update_rules	Sync Sigma-based detection rules to the latest version

Every tool that takes log input accepts exactly one of directory (a folder of .evtx files) or file (a single .evtx file), plus an extra_args passthrough list for flags this wrapper doesn't hardcode (rules directory, minimum level, output profile, etc.) — run hayabusa <subcommand> --help to see what your installed version supports, since flags have changed across Hayabusa releases.

Project folder structure

mcp-hayabusa/
├── src/
│   └── mcp_hayabusa/
│       ├── __init__.py     # package version
│       ├── config.py       # resolves HAYABUSA_PATH / timeout from environment
│       ├── hayabusa.py     # subprocess wrapper, subcommand allowlist, CSV summarizer
│       └── server.py       # FastMCP app and @mcp.tool() definitions
├── tests/
│   └── test_hayabusa.py    # unit tests (subprocess.run mocked out)
├── pyproject.toml          # packaging, dependencies, console-script entry point
├── README.md
└── CLAUDE.md                # guidance for AI coding agents working in this repo

Skills demonstrated

• Designing and building an MCP server from the official Python SDK (FastMCP), including tool schemas, docstring-driven descriptions, and stdio transport
• Secure subprocess handling: shell-free command construction, an explicit subcommand allowlist, and timeout enforcement around an external security tool
• Applying defensive security tooling (Hayabusa / Sigma-based detection) in an agentic/LLM-assisted workflow
• API/response design for LLM consumption — summarizing large structured output (CSV timelines) into a compact, model-friendly shape instead of dumping raw data
• Layered architecture with clear separation of concerns (config resolution → CLI invocation → tool interface)
• Test-driven verification without the real dependency — unit tests that mock subprocess.run so core logic is verified without needing the Hayabusa binary installed
• Environment-based configuration and packaging for a Windows development workflow (pyproject.toml, editable installs, console-script entry points)

Current limitations

• Windows-oriented, manual dependency install — Hayabusa itself is not bundled, vendored, or auto-downloaded; the user must install it separately and point HAYABUSA_PATH at it.
• No automated integration tests against a real Hayabusa binary or real .evtx files — current tests only cover argument-building and CSV-summarization logic with mocks.
• HAYABUSA_RULES_PATH is defined but not yet wired up — it's read into config but not currently passed to any Hayabusa invocation; a rules directory must be supplied per call via extra_args (e.g. ["-r", "C:\\hayabusa\\rules"]) instead.
• Flag coverage is intentionally partial — only -d/-f/-o are hardcoded per subcommand; everything else relies on the caller supplying correct flags via extra_args, since Hayabusa's CLI flags have changed across releases and this project hasn't been verified against every version.
• No output size/row cap on search, logon-summary, or eid-metrics — unlike hayabusa_csv_timeline, these tools return raw stdout, which could be large on bigger log sets.
• No authentication or multi-user access control — this is a local, single-user MCP server intended to run on the same machine as the Claude client, not a shared network service.
• No log/audit trail of tool invocations — useful for a personal workflow, but a production or team deployment would likely want to record what scans were run, by whom, and when.

Future improvements

• Wire up HAYABUSA_RULES_PATH so a configured rules directory is applied automatically instead of requiring extra_args on every call
• Add hayabusa_json_timeline, computer_metrics, log_metrics, and pivot_keywords_list tool wrappers (the underlying hayabusa.py functions/allowlist already support most of these)
• Cap and paginate output for search, logon_summary, and eid_metrics the same way csv_timeline is already summarized
• Add integration tests that run against sample/synthetic .evtx files and a real Hayabusa binary in CI
• Cross-platform support (Hayabusa itself runs on Linux/macOS too; this wrapper's binary resolution and packaging currently assume a Windows workflow)
• Structured logging of tool calls (subcommand, arguments, duration, result) for auditability
• Optional automatic rule updates on a schedule, rather than only on explicit hayabusa_update_rules calls

Disclaimer

This project is built for educational and defensive security purposes only. It is a personal/portfolio project demonstrating how to integrate an LLM agent with a legitimate, publicly available forensics tool (Hayabusa) via the Model Context Protocol.

• It is intended for use on event logs you own or are explicitly authorized to analyze (e.g. your own systems, lab environments, or logs provided as part of an authorized incident response or training engagement).
• It performs read-only analysis of event log data — it does not modify, exploit, or attack any system. Detection logic comes entirely from Hayabusa's own Sigma-based rule engine, not from this project or from the LLM.
• It is not a replacement for professional incident response tooling, processes, or judgment. Always validate findings from any automated tool — including this one — against your own analysis before acting on them.