hayabusa-mcp

An MCP (Model Context Protocol) server that wraps Hayabusa for EVTX (Windows Event Log) analysis, exposing scan_evtx, get_hayabusa_rules, analyze_coverage, and suggest_rule tools, plus read-only detection:// resources for browsing the bundled Sigma rule set (see Resources below).

Project status

This project is complete and is retained as a portfolio and educational reference. No additional feature development is currently planned; the sections below document its final setup, usage, and scope.

Related MCP server: mcp-hayabusa

Setup

1. ./download_hayabusa.sh — downloads and checksum-verifies the Hayabusa binary into ./hayabusa/

2. pip install -r requirements.txt (or use a .venv)

3. Connect via .mcp.json (Claude Code) or as a Claude Desktop extension (see below)

Tools

• scan_evtx — runs Hayabusa against an EVTX file and returns findings as structured JSON, filterable by severity level.

• get_hayabusa_rules — lists/searches the bundled Hayabusa and Sigma detection rules by keyword.

• analyze_coverage — given a batch of MITRE ATT&CK technique IDs, reports binary local coverage (covered/not_covered) against the bundled rule set.

• suggest_rule — given one MITRE ATT&CK technique ID, returns existing matching rules if already covered, or a read-only draft rule template (never written to disk) if not.

A project-scoped skill at .claude/skills/detection-engineering/ packages the rule-authoring workflow built on these tools — see that directory for details.

Testing

Each test file is run directly (no pytest), the same convention used by the hooks' own test suite (see Testing hooks below):

.venv/bin/python test_scan_evtx.py
.venv/bin/python test_get_hayabusa_rules.py
.venv/bin/python test_resources.py
.venv/bin/python test_analyze_coverage.py
.venv/bin/python test_suggest_rule.py

The detection-engineering skill has its own test suite, run the same way:

.venv/bin/python .claude/skills/detection-engineering/tests/test_validate_rule.py

Slash commands

• /investigate-evtx <evtx-path> [severity] — scans an EVTX file, resolves findings to MITRE ATT&CK tags, and writes a general investigation note under investigations/ (gitignored), cross-linking prior investigations on verified technique/RuleID overlap.

• /triage <evtx-path> [severity] [case-id] — the case-oriented counterpart: same scan → resolve-tags → coverage pipeline, plus a required triage outcome (escalate, investigate, investigate further, likely benign, insufficient evidence), writing to investigations/triage/ (gitignored) and syncing reusable techniques/<TechniqueID>.md knowledge-base notes (tracked in git, case-data-free by design).

See .claude/commands/investigate-evtx.md and .claude/commands/triage.md for the full step-by-step each command follows.

Hooks

Four Claude Code hooks live under .claude/hooks/ and are registered in .claude/settings.json:

• SessionStart — read-only prerequisite check (Hayabusa binary present and executable, pyyaml importable, hayabusa-mcp enabled), surfaced as context at the start of a session.

• PreToolUse (Write/Edit) — denies writes to sensitive paths: repo-internal/vendored directories (.git/, hayabusa/, lib/), the hook config itself (.claude/settings*.json), credential directories (.ssh/, .aws/, .gnupg/), credential/secret/key-shaped files (.env and variants, id_rsa and friends, credentials/ credentials.json, .npmrc, .netrc, and .pem/.key/.pfx/.p12/ .crt/.cer), or anything resolving outside the project root. Directory rules match at any depth, not just directly under the project root; matching is case-insensitive.

• PostToolUse (Write/Edit) — after a Sigma/Hayabusa rule YAML is written or edited, re-runs the same validator the detection-engineering skill uses (validate_rule.py) and reports any structural errors back to Claude.

• Stop — fires when Claude finishes responding and sends a fixed, generic desktop notification (notify-send, if installed) reading "Task complete - review required". The notification text is always a literal, never built from hook input (no prompt, transcript, file path, or session data is ever passed to notify-send); the only state written is a single timestamp in the OS temp dir, named by a hash of the project path rather than the raw path, used solely to debounce repeat notifications within 20 seconds. Never blocks the stop and never alters Claude's turn — exit code is always 0, with no decision/continue output.

None of these hooks can auto-approve a tool call — manual approval is unchanged for every file change and command except the narrow sensitive-path denylist above, which is a hard deny, not an auto-allow. To disable all hooks locally without touching the shared config, set "disableAllHooks": true in a personal, gitignored .claude/settings.local.json.

Prerequisites

• Python 3 with pyyaml installed — already a project dependency (see Setup above); validate_rule_hook.py and session_start_check.py both import it.

• A populated .venv/ at .venv/bin/python. .claude/settings.json invokes every hook as ${CLAUDE_PROJECT_DIR}/.venv/bin/python ..., so if that interpreter doesn't exist the hook command itself fails to launch (see Troubleshooting below).

• Nothing hook-specific requires hayabusa/ to be downloaded — a missing or non-executable Hayabusa binary is reported by SessionStart as a status line, not treated as an error.

• notify-send is optional, used only by Stop. If it isn't installed (checked via shutil.which), the hook exits 0 with no notification and no error — desktop notifications are a convenience, never a dependency.

Hook setup

No separate installation step: all four hooks are plain Python scripts under .claude/hooks/, already registered in the git-tracked .claude/settings.json. Completing this project's normal Setup (download Hayabusa, pip install -r requirements.txt into .venv/) is enough — Claude Code reads the hooks key automatically for any session started in this project directory, with no extra step to enable any of them.

Testing hooks

Run the hook test suite directly (no pytest, same convention as every other test in this repo):

.venv/bin/python .claude/hooks/tests/test_hooks.py

This drives each hook's pure logic (classify(), should_skip()/ looks_like_rule(), the session_start_check functions, and stop_notify's should_notify()/state_file_path()/read_last_notified()/ write_last_notified()) directly rather than through stdin/stdout, matching how test_scan_evtx.py and the other repo-root suites are run.

Restarting after a hook change

Claude Code's file watcher normally picks up edits to .claude/settings.json and the hook scripts mid-session. If a change doesn't seem to take effect, start a fresh Claude Code session in this directory to force a clean reload — the same operational caveat this project already documents for server.py changes and the MCP connection (see HANDOFF.md).

Troubleshooting

• A hook doesn't seem to fire at all: confirm the interpreter exists (ls .venv/bin/python) — a missing .venv makes the hook command fail silently rather than raise a visible error. Re-run pip install -r requirements.txt into .venv/ if needed.

• protect_sensitive_paths.py blocks a file you expected to write: read the denial reason shown — it names the specific rule that matched (a protected directory, a credential file name/extension, or "outside the project root"). Treat an unexpected match as a denylist bug to fix, not something to work around by disabling hooks project-wide.

• validate_rule_hook.py doesn't flag an invalid rule you just wrote: it only validates files inside the project root, outside hayabusa/ and any tests/fixtures/ path, that look Sigma/Hayabusa-rule-shaped (a logsource or detection key present) — a file lacking both keys looks like "not a rule" to the heuristic and is silently skipped.

• Need to disable a hook temporarily: set "disableAllHooks": true in a personal .claude/settings.local.json (gitignored, machine-local) rather than editing the shared .claude/settings.json.

Limitations

• protect_sensitive_paths.py only covers Write/Edit. A Bash command that mutates a sensitive path (rm, mv, shell redirection) isn't covered by this hook — Claude Code's own manual approval for Bash still applies regardless, so this is a defense-in-depth gap, not a missing safeguard.

• validate_rule_hook.py's "does this look like a rule" check (a logsource or detection key) is a heuristic, not a guarantee — it could in principle miss an unusual rule dialect or flag an unrelated YAML file that happens to define one of those keys.

• Hooks are local automation, not a substitute for reviewing a diff yourself before committing — see HANDOFF.md for the full known-limitations list and this project's standing sensitive-data-sweep practice.

Resources

Alongside the tools above, the server exposes four read-only detection:// MCP resources for browsing the bundled Sigma/Hayabusa rule set and looking up MITRE ATT&CK technique coverage:

• detection://rules — a compact JSON index of the bundled rules (resource_id, id_source, title, level only — not full rule bodies). Capped at 500 entries per read; truncated/total_rules in the response indicate when more exist.

• detection://rules/{rule_identifier} — the complete YAML text of one rule. rule_identifier is the rule's own YAML id: (a UUID); a small number of rules missing a valid id get a stable fallback-<hash> identifier instead — check id_source in the index to tell them apart.

• detection://rules/by-technique/{technique_id} — rules tagged with a given MITRE ATT&CK technique ID (case-insensitive). A bare parent ID like T1003 matches its own tag plus any sub-technique tagged beneath it (labeled inherited_subtechnique in the response); a specific sub-technique query like T1003.001 matches only that exact tag, never its parent or sibling sub-techniques.

• detection://attack/techniques/{technique_id} — local coverage facts for a technique ID (match count, covered/not_covered), computed solely from the bundled rule set. This server does not bundle an ATT&CK technique-name/tactic/description dataset, so no such fields are returned — the response only contains what can be derived from local rule data.

Claude Desktop extension

The extension's manifest.json points PYTHONPATH at a vendored ./lib/ directory rather than any external virtualenv. lib/ is not tracked in git (it contains compiled, platform-specific wheels) — build it locally with:

./package_extension.sh

This regenerates ./lib/ from requirements.txt and produces dist/hayabusa-mcp.zip. You'll still need ./hayabusa/ populated separately via download_hayabusa.sh before the extension can run.

License

This project is licensed under the MIT License.

Hayabusa itself is a separate project licensed under AGPL-3.0. It is downloaded at setup time by download_hayabusa.sh and invoked as an external subprocess — it is not vendored or linked into this repository.