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.

Project overview

An MCP (Model Context Protocol) server that wraps Hayabusa (a Windows event log analysis tool) for EVTX file analysis, and doubles as a small detection engineering knowledge base. It exposes three tools:

• scan_evtx — runs Hayabusa against an EVTX file and returns structured JSON findings, filterable by severity and rule title. Scans the bundled hayabusa/rules/ catalog (~4,961 rules), so findings aren't limited to our own small ruleset.
• get_hayabusa_rules — lists the Sigma detection rules Hayabusa ships with (the bundled hayabusa/rules/ set), optionally filtered by keyword. Since scan_evtx runs against this same catalog, a rule_filter string found here is a valid filter for scan_evtx output.
• analyze_coverage — given an ATT&CK technique ID or tactic name, reports which techniques our curated custom_rules/ set covers, partially covers, or leaves as gaps. Combines the resource-side ATT&CK data with the same coverage logic backing detection://attack/techniques/{technique_id}, but works over a whole technique subtree or tactic in one call instead of one technique at a time. With only 8 curated rules across 6 techniques, most techniques will show as gaps — this is expected, not a bug.

...and four MCP resources backing the knowledge-base side, all under the detection:// URI scheme:

• detection://rules — index of our own curated Sigma rules (distinct from the ~5000 Hayabusa ships).
• detection://rules/{rule_name} — a specific curated rule's raw YAML.
• detection://rules/by-technique/{technique_id} — curated rules tagged with a given ATT&CK technique ID.
• detection://attack/techniques/{technique_id} — an ATT&CK technique's name/description plus which curated custom_rules/ rules detect it and a coverage verdict (covered / partial / gap).

Stack

• Python 3, using the mcp library (mcp.server.Server, stdio transport), pydantic, and pyyaml (for parsing Sigma rule files — prefers the CSafeLoader libyaml binding when available, since parsing ~5000 rule files with the pure-Python loader takes ~6s vs ~0.6s with libyaml)
• Hayabusa CLI, downloaded as a prebuilt binary (not built from source) and invoked as a subprocess