mcp-hayabusa: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP (Model Context Protocol) server that wraps the Hayabusa CLI — a Rust-based Windows event log (.evtx) forensic timeline generator and threat hunting tool. It exposes Hayabusa's analysis commands (detection timelines, keyword search, event/computer/logon metrics, pivot keyword extraction, base64 extraction, critical-system detection) as MCP tools so an LLM client (Claude Desktop, Claude Code, etc.) can run them directly against .evtx files. See the README's Tools table for the full list. It also exposes a set of read-only MCP resources for browsing the installed Sigma detection rule set and its ATT&CK technique/tactic coverage, independent of any .evtx file — see the README's Resources table.

The server itself does no log parsing — it shells out to a locally installed hayabusa binary and parses its output (mostly CSV/JSONL, plus plain text for the one subcommand that has no file-output option) into bounded, structured MCP tool results. Two things are the exception, reading hayabusa's local Sigma rule YAML files directly instead of shelling out: the get_hayabusa_rules tool (see below) and everything in knowledge.py behind the hayabusa:// resources (see below).

Commands

# Install (editable, with test deps)
pip install -e ".[dev]"

# Run the server (stdio transport — meant to be launched by an MCP client, not run interactively)
mcp-hayabusa
python -m mcp_hayabusa

# Tests
pytest
pytest tests/test_hayabusa.py::test_csv_timeline_parses_and_truncates  # single test

# Lint / typecheck
ruff check .
mypy          # checks src/mcp_hayabusa (see [tool.mypy] in pyproject.toml)
mypy tests    # tests aren't covered by the mypy config's default package selection

Architecture

Four-module core under src/mcp_hayabusa/:

• config.py — resolves the path to the hayabusa binary: HAYABUSA_BIN env var if set, otherwise searched on PATH. Raises HayabusaNotFoundError if neither works. Every subprocess call goes through this.
• hayabusa.py — the actual CLI wrapper. Most public functions (csv_timeline, json_timeline, search, eid_metrics, computer_metrics, log_metrics, extract_base64, and others) follow the same shape:
  1. Validate the target path exists (_require_existing_path) — every other user-supplied path-like argument (rules_dir on csv_timeline/json_timeline/get_hayabusa_rules) is routed through the same function before use, for the same reason. See "Security / trust boundary" below for what this validation does and deliberately does not do.
  2. Build a hayabusa <subcommand> argv list (never through a shell — no shell-injection surface).
  3. Write output to a temp file (hayabusa requires -o <file> for structured results; it won't stream them to stdout), then parse that file.
  4. Return a dict with total_rows/records, a max_rows-bounded slice, a truncated flag, the exact command that was run (for debuggability), and a trimmed stderr_summary.