Hayabusa MCP Server

Hayabusa MCP Server

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

Overview

Hayabusa is a fast, Rust-based command-line tool built by Yamato Securitythat parses Windows Event Log (.evtx) files and matches them against thousands ofSigma-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 exposesHayabusa's subcommands as tools an MCP-compatible client (such as Claude Desktop orClaude Code) can call. Instead of memorizing Hayabusa's flags, a user can just ask Claudein 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 incidentresponse 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-structuredformat 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 takessecurity expertise.
• Junior analysts and students often have the tool access but not yet the pattern-recognitionexperience to triage results quickly; senior analysts have the experience but limited timeto 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 rawCSV dump, and use its own reasoning to help explain what a given alert means, which events lookmost urgent, and what to investigate next — while the actual detection logic still comes fromHayabusa'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 itover the MCP protocol (JSON-RPC over stdio).
2. On startup, the server (built with the mcp Python SDK'sFastMCP) 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 anddocstrings.
3. When the user asks something that maps to one of those tools, Claude calls it with structuredarguments (e.g. {"directory": "C:\\logs", "extra_args": ["-m", "medium"]}).
4. The server translates that call into a real hayabusa <subcommand> ... invocation viaPython'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 returnthe 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 toolcalls (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-compatibleclient, and Claude doesn't need any Hayabusa-specific training — the tool descriptions arethe 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 outputand returns event counts by severity level plus a small sample, so a large scan doesn't blowpast the model's context window.
• Subcommand allowlist — the wrapper only ever invokes a fixed set of known-safe Hayabusasubcommands (ALLOWED_SUBCOMMANDS in hayabusa.py), rather than passing arbitraryattacker-or-model-controlled strings straight to a shell.
• No shell interpolation — all commands are built as argument lists and run withsubprocess.run(..., shell=False), which avoids shell/command-injection risk even thoughinputs (file paths, keywords) can come from model-generated text.
• Version-tolerant flag handling — only the input/output flags (-d, -f, -o) arehardcoded, since Hayabusa's other flags have changed across releases; everything else (rulesdirectory, minimum level, output profile) is passed through an explicit extra_args listrather than guessed.
• Configurable, fail-fast binary lookup — the Hayabusa binary path is resolved once viaHAYABUSA_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 theargument-building logic and CSV summarization can be verified in CI without installingHayabusa or providing real .evtx files.

Project architecture

The server is a thin, layered wrapper — it does not reimplement any detection or log-parsinglogic 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) — theactual 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, downloadedseparately — 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 environmentvariable 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 containinghayabusa.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, toolcalls 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 MCPInspector:

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 viaclaude 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 atC:\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 topotential credential dumping (LSASS access). Want me to pull the full detail on those threeevents, 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

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 wrapperdoesn't hardcode (rules directory, minimum level, output profile, etc.) — runhayabusa <subcommand> --help to see what your installed version supports, since flags havechanged 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), includingtool schemas, docstring-driven descriptions, and stdio transport
• Secure subprocess handling: shell-free command construction, an explicitsubcommand allowlist, and timeout enforcement around an external security tool
• Applying defensive security tooling (Hayabusa / Sigma-based detection) in anagentic/LLM-assisted workflow
• API/response design for LLM consumption — summarizing large structured output (CSVtimelines) into a compact, model-friendly shape instead of dumping raw data
• Layered architecture with clear separation of concerns (config resolution → CLIinvocation → tool interface)
• Test-driven verification without the real dependency — unit tests that mocksubprocess.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 notcurrently passed to any Hayabusa invocation; a rules directory must be supplied per call viaextra_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'sCLI flags have changed across releases and this project hasn't been verified against everyversion.
• No output size/row cap on search, logon-summary, or eid-metrics — unlikehayabusa_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 serverintended 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 productionor 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 automaticallyinstead of requiring extra_args on every call
• Add hayabusa_json_timeline, computer_metrics, log_metrics, and pivot_keywords_listtool 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 waycsv_timeline is already summarized
• Add integration tests that run against sample/synthetic .evtx files and a real Hayabusabinary in CI
• Cross-platform support (Hayabusa itself runs on Linux/macOS too; this wrapper's binaryresolution 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 explicithayabusa_update_rules calls

Disclaimer

This project is built for educational and defensive security purposes only. It is apersonal/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 incidentresponse or training engagement).
• It performs read-only analysis of event log data — it does not modify, exploit, or attackany system. Detection logic comes entirely from Hayabusa's own Sigma-based rule engine, notfrom 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 ownanalysis before acting on them.