# mcp-hayabusa

## Project layout

- `server.py` — the MCP server entry point; both tools are defined here
- `requirements.txt` — Python dependencies (`mcp`, `pyyaml`)
- `hayabusa/` — the Hayabusa binary, rule set, and config, installed by
  `scripts/download_hayabusa.py` (gitignored; not checked in)
- `scripts/download_hayabusa.py` — downloads the latest Hayabusa release for the current
  platform and extracts it into `hayabusa/`
- `samples/` — sample EVTX files for manual testing (e.g. `sysmon_lsass_mimikatz.evtx`)
- `.mcp.json` — registers the `hayabusa` MCP server (`python server.py`) for this project
- `.claude/settings.json` — allowlists (`enabledMcpjsonServers`) the server defined in
  `.mcp.json` so Claude Code doesn't prompt for approval on every session

## Setup and running locally

```
pip install -r requirements.txt
python scripts/download_hayabusa.py   # installs hayabusa/ (binary + rules), if not present
```

The server is launched by Claude Code via `.mcp.json` (`python server.py`, stdio transport) —
there's no separate "start the server" step when working through Claude Code. To run/debug it
standalone, `python server.py` starts it directly.

There is no formal test suite (no pytest config) — verify behavior by calling the tools directly,
e.g.:

```
python -c "from server import scan_evtx; print(scan_evtx('samples/sysmon_lsass_mimikatz.evtx'))"
python -c "from server import get_hayabusa_rules; print(get_hayabusa_rules(keyword='mimikatz'))"
```

Note: an already-running MCP connection does not pick up `server.py` edits — reconnect/restart
the MCP server (e.g. `/mcp` reconnect in Claude Code) to see code changes reflected in tool calls.

## MCP tools

### `scan_evtx(evtx_path, min_severity="informational", rule_filter="", output_format="summary", max_results=0)`

Runs `hayabusa json-timeline` against a single EVTX file and returns structured JSON detections.

- Invokes the binary with `-L` (JSONL output), `-w` (no interactive wizard), `-q`/`-N`/`-K`
  (quiet, no summary table, no color codes), `-C` (clobber output file), `-b` (disable Level
  abbreviations) — output is written to a temp file and parsed line by line.
- `min_severity` is **post-filtered** in Python against `SEVERITY_LEVELS`
  (informational < low < medium < high < critical), not passed to Hayabusa as a CLI flag.
  `LEVEL_ALIASES` maps abbreviated Level values back to full names as a defensive fallback.
- `rule_filter` is a case-insensitive substring match against each finding's `RuleTitle`.
- `output_format="summary"` (default) trims each finding to `SUMMARY_FIELDS` (Timestamp,
  RuleTitle, Level, Computer, Channel, EventID, RecordID, RuleID); `"full"` returns every field
  Hayabusa produced, including `Details` and `ExtraFieldInfo`.
- `max_results` truncates the returned list after severity/rule filtering; the response's
  `total_findings` still reports the full filtered count so callers can tell when results were
  capped.
- Scans time out after `SCAN_TIMEOUT_SECONDS` (600s).

### `get_hayabusa_rules(keyword="", max_results=100)`

Lists Hayabusa's bundled Sigma/built-in detection rules by parsing every YAML file under
`hayabusa/rules/**/*.yml` (~5000 files). Useful for discovering rule titles (to feed into
`scan_evtx`'s `rule_filter`) or understanding what a rule detects before scanning.

- Parsed rule metadata (`id`, `title`, `level`, `status`, `description`, `tags`, `logsource`,
  `path`) is cached in `_rules_cache` for the life of the process — the first call takes several
  seconds (full YAML parse), subsequent calls are near-instant. The cache is invalidated only by
  restarting the server.
- `keyword` is a case-insensitive substring match against title, description, rule ID, and tags.
- `max_results` defaults to 100 (there are thousands of rules); `0` means no limit. Response
  includes `total_rules`, `total_matched`, and `returned_count`.
- Malformed rule YAML, or files without a `title` field, are silently skipped.

## Error handling conventions

Both tools return `_error(message)` — `{"success": false, "error": "..."}` — rather than raising,
for: invalid enum/range arguments (`min_severity`, `output_format`, negative `max_results`),
missing/non-file `evtx_path`, missing Hayabusa binary or rules directory, non-zero Hayabusa exit
code, missing output file, malformed JSONL output line, subprocess timeout, and `OSError`/
`FileNotFoundError` when invoking the binary. Successful responses always include `"success":
true`.