Skip to main content
Glama
msadigo

mcp-hayabusa

by msadigo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mcp-hayabusa

Tests License: MIT Python 3.10+

An MCP (Model Context Protocol) server that wraps Hayabusa, the Windows event log fast forensics timeline and threat-hunting tool, so an MCP client (e.g. Claude Code) can run detection scans over .evtx files.

Prerequisites

  • Python 3.10+

  • The hayabusa binary, downloaded from the Hayabusa releases page (or built from source), available on PATH, or pointed to via the HAYABUSA_BIN environment variable.

    scripts/download_hayabusa.py will fetch the latest release for your platform and extract it to ./hayabusa/:

    python scripts/download_hayabusa.py
# then either add ./hayabusa to PATH, or:
export HAYABUSA_BIN=./hayabusa/hayabusa   # ./hayabusa/hayabusa.exe on Windows

    Pass --version vX.Y.Z to pin a release, --musl for a musl build on Linux, or --force to re-download.

Related MCP server: mcp-hayabusa

Install

pip install -e .

Run

mcp-hayabusa

Or point an MCP client's config at the installed console script (mcp-hayabusa) or at python -m mcp_hayabusa.server.

Configuration

Env var

Purpose

HAYABUSA_BIN

Full path (or PATH-resolvable name) of the hayabusa binary to invoke.

Copy .env.example to .env and fill it in as a reference for what to set. Nothing auto-loads .env: export the variables yourself (or use a tool like direnv) before running mcp-hayabusa/ mcp dev/mcp run, or, if installing into the Claude Desktop app, pass it straight to mcp install src/mcp_hayabusa/server.py --env-file .env.

Tools

scan_evtx

Runs hayabusa csv-timeline or hayabusa json-timeline against a single .evtx file or a directory of .evtx files, always non-interactively.

Parameters: target, is_file, output_format (csv/json/jsonl), rules_dir, min_level, utc, output_path.

Returns the command that was run, exit code, a preview of up to 20 result records, the total record count, and truncated stdout/stderr. Pass output_path explicitly to keep the full result file on disk; otherwise a temporary file is used and removed after the preview is extracted.

get_hayabusa_rules

Lists Hayabusa/Sigma detection rules, optionally filtered by keyword — useful for browsing/searching what's available before running scan_evtx with a rule_filter, since both use the same case-insensitive text match.

Parameters: keyword, rules_dir, max_results.

Returns total_matched (true count) and up to max_results rules, each with path, id, title, level, status, description, author, tags, and logsource.

Resources

A read-only, browsable detection knowledge base — Sigma rules and their ATT&CK mappings — for a client to navigate directly instead of only through tool calls.

URI

Kind

Description

hayabusa://attack

static

Every ATT&CK technique ID present in the loaded rule set, with a rule count each.

hayabusa://attack/{technique_id}

template

Rules tagged with one technique, e.g. hayabusa://attack/T1003 (case-insensitive).

hayabusa://rules/{path}

template

Raw Sigma rule YAML (including its detection: logic) for one rule file.

path in hayabusa://rules/{path} is a rule's path field from get_hayabusa_rules or an ATT&CK resource, with every / percent-encoded (%2F) — MCP resource URI templates only match a single path segment.

Available Tools

2 tools
get_hayabusa_rulesA

List available Hayabusa/Sigma detection rules, optionally filtered by keyword.

Useful for understanding what rules exist before running scan_evtx — e.g. call with keyword="mimikatz" to see which rules would be loaded by scan_evtx(rule_filter="mimikatz"), since both use the same case-insensitive match against rule file text.

Args: keyword: Only return rules whose rule file text contains this string (case-insensitive), e.g. "lateral" or "mimikatz". Omit to list all rules (subject to max_results). rules_dir: Optional path to a custom Sigma/Hayabusa rules directory. Defaults to Hayabusa's bundled ./rules. max_results: Cap on the number of rules returned (default 50). total_matched in the response is always the true match count.

Returns: A dict with total_matched (true count of matching rule files) and rules: a list of {path, id, title, level, status, description, author, tags, logsource}, capped at max_results.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordNo
rules_dirNo
max_resultsNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses case-insensitive matching, default max_results (50), and the meaning of total_matched. It does not mention read-only nature or auth requirements, but for a listing tool, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: purpose sentence, usage paragraph, then bulleted parameters (though not in markdown), and return format. Every sentence adds value with no repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all aspects: inputs, outputs, relationship to sibling, example usage, default behaviors. Given 3 optional params and no output schema, the description is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description compensates fully: explains keyword filtering (case-insensitive, examples), rules_dir default path, and max_results cap with response field clarification. Each parameter gets detailed, contextualized meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List available Hayabusa/Sigma detection rules, optionally filtered by keyword.' It identifies the specific verb (list) and resource (rules), and distinguishes from sibling tool scan_evtx by explaining the relationship.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states it's 'useful for understanding what rules exist before running scan_evtx' and provides an example with keyword='mimikatz'. It could be improved by mentioning when not to use (e.g., for scanning logs), but the guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_evtxA

Run a Hayabusa detection scan over Windows Event Log (.evtx) data.

Wraps hayabusa csv-timeline / hayabusa json-timeline, always run non-interactively (no rule-config wizard, no launch banner).

Args: target: Path to a single .evtx file (set is_file=True) or a directory containing .evtx files. is_file: True if target is a single .evtx file rather than a directory. output_format: "csv" (uses csv-timeline), or "json"/"jsonl" (both use json-timeline; jsonl adds Hayabusa's -L flag). This controls Hayabusa's own output format, not the shape of the dict returned by this tool — see result_detail for that. rules_dir: Optional path to a custom Sigma/Hayabusa rules directory or file (passed as -r). Defaults to Hayabusa's bundled ./rules. Ignored if rule_filter is set (see below). rule_filter: Only run rules whose rule file text contains this string (case-insensitive), e.g. "lateral" or "mimikatz". Hayabusa has no native free-text rule filter, so this copies matching rule files from rules_dir (or Hayabusa's default ./rules) into a temporary rules directory and scans with just those loaded. min_level: Optional minimum alert level to load: "informational", "low", "medium", "high", or "critical" (passed as -m). utc: Output timestamps in UTC instead of local time (-U). output_path: Where to write the full result file. If omitted, a temporary file is used and deleted after a preview is extracted, so the full result set is only kept on disk when you pass this explicitly. result_detail: "summary" (default) returns counts by level, the top matching rules, and a condensed preview (key fields only); stdout/stderr tails are only included on non-zero exit. "full" returns the complete record preview with all fields plus stdout/stderr tails, as before. max_results: Cap on the number of preview records returned (default 20). Does not affect record_count, which is always the true total.

Returns: A dict shaped per result_detail; see above.

ParametersJSON Schema
NameRequiredDescriptionDefault
utcNo
targetYes
is_fileNo
min_levelNo
rules_dirNo
max_resultsNo
output_pathNo
rule_filterNo
output_formatNojson
result_detailNosummary

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description discloses key behaviors: wraps hayabusa commands, runs non-interactively, temporary file handling for output_path, rule_filter copying, and result_detail controls. Could add error handling or permissions but is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with purpose first, then parameter details, then return. Each sentence adds value, though slightly lengthy. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (10 params, no annotations, no output schema), description covers parameters, return shape, and behavioral nuances. Lacks error cases or performance notes but is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, description fully explains all 10 parameters with context, defaults, and relationships to underlying tool. Adds meaning beyond field names, e.g., rule_filter copies files, result_detail controls preview.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it runs a Hayabusa detection scan on .evtx files, distinguishing it from sibling tool 'get_hayabusa_rules' which retrieves rules. Verb 'scan' and resource 'Windows Event Log (.evtx) data' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains when to use the tool (scanning evtx files) and contrasts with sibling tool. Provides context on interactive vs non-interactive, default behaviors, and output handling. Lacks explicit when-not-to-use or alternative tools beyond the sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_hayabusa_rules
    • First observedscan_evtx
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one lists available rules, the other performs a scan. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools use consistent snake_case naming with a verb_noun pattern (get_hayabusa_rules, scan_evtx), which is predictable and clear.

Tool Count4/5

Two tools is slightly on the low side, but it aligns with the focused scope of the MCP server (rule listing and scanning). It is reasonable for a targeted purpose.

Completeness4/5

The core workflow of listing rules and scanning EVTX files is covered. Minor gaps exist (e.g., no tool for retrieving previous scan results or managing rules), but the essential functionality is present.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-hayabusa

    meg4tech
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables an LLM client to scan Windows event log files (EVTX) for suspicious activity using Hayabusa, and browse its detection rules directly in conversation.
    -

  • mcp-hayabusa

    TregardLabs-Dana
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables scanning Windows EVTX event log files with Hayabusa, returning structured detection results through an MCP tool.
    -

  • mcp-hayabusa

    baobao26
    F
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that wraps the Hayabusa CLI, enabling analysis of Windows EVTX event log files and browsing of its detection rule set.
    -

  • mcp-hayabusa

    chiomao23
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables EVTX (Windows Event Log) analysis via Hayabusa, providing tools to scan event logs and retrieve detection rules.
    -