Wintools Mcp

Windows Tools MCP

[](https://github.com/AppliedIR/wintools-mcp/actions/workflows/ci.yml) [](https://github.com/AppliedIR/wintools-mcp/blob/main/LICENSE)

Catalog-gated Windows forensic tool execution with knowledge-enriched response envelopes.

Platform Documentation · Deployment Guide

> Important Note — While extensively tested, this is a new platform. > ALWAYS verify results and guide the investigative process. If you just > tell Valhuntir to "Find Evil" it will more than likely hallucinate > rather than provide meaningful results. The AI can accelerate, but the > human must guide it and review all decisions.

Architecture

wintools-mcp runs independently on a Windows forensic workstation, exposing a Streamable HTTP endpoint on port 4624. The LLM client and vhir CLI are the two human-facing tools. The vhir CLI always runs on the SIFT workstation — it requires direct filesystem access to the case directory. When the LLM client runs on a separate machine, the examiner must have SSH access to SIFT for all CLI operations. The LLM client connects to wintools-mcp over the network.

graph LR
    subgraph sift ["SIFT Workstation"]
        CC["LLM Client(human interface)"]
        CLI["vhir CLI(human interface)"]
        CASE["Case Directory"]

        CLI --> CASE
    end

    subgraph winbox ["Windows Forensic Workstation"]
        WAPI["wintools-mcp API:4624"]
        WM["wintools-mcpWindows tool execution"]
        FK["forensic-knowledge"]

        WAPI --> WM
        WM --> FK
    end

    CC -->|"streamable-http"| WAPI
    WM -->|"SMB"| CASE

Execution Pipeline

Every tool execution flows through the same security and enrichment pipeline.

graph LR
    REQ["MCP tool call"] --> DENY{"HardcodedDenylist"}
    DENY -->|"blocked binary"| BLOCK["BLOCKED"]
    DENY -->|"pass"| CAT{"YAML CatalogAllowlist"}
    CAT -->|"not cataloged"| REJECT["REJECTED"]
    CAT -->|"cataloged"| SANITIZE{"ArgumentSanitization"}
    SANITIZE -->|"dangerous flagor metachar"| REJECT
    SANITIZE -->|"clean"| RESOLVE["ResolveBinary Path"]
    RESOLVE --> EXEC["subprocess.runshell=False"]
    EXEC --> PARSE["Parse OutputCSV / JSON / text"]
    PARSE --> ENRICH["FK Enrichmentcaveats, corroboration,field notes, discipline"]
    ENRICH --> RESP["Response Envelope"]

Security Model

This MCP opens attack vectors where connected LLM clients can execute tools on this system. It must only be installed on dedicated forensic workstations that are isolated behind firewalls on a trusted network segment. Never install on personal laptops, production systems, or machines containing data outside the scope of the investigation.

The installer requires typing security_hole or passing -AcknowledgeSecurityHole before proceeding. This is an intentional friction point.

The additional controls in place (catalog allowlists, denylist of dangerous binaries, argument sanitization, shell=False execution) are defense-in-depth measures, not preventative controls. The MCP is not hardened and should never be deployed facing the Internet or other untrusted systems.

graph TB
    INPUT["Tool Execution Request"] --> D{"Hardcoded Denylist20 binaries + .exe variants"}
    D -->|"cmd, powershell, pwsh,wscript, cscript, mshta,rundll32, regsvr32, certutil,bitsadmin, msiexec, bash,wsl, sh, msbuild, installutil,regasm, regsvcs, cmstp, control"| BLOCKED["BLOCKED"]
    D -->|"pass"| A{"YAML CatalogAllowlist"}
    A -->|"unknown binary"| REJECTED["REJECTED"]
    A -->|"cataloged"| S{"ArgumentSanitization"}
    S -->|"shell metacharacters,execution flags, or@file response-file"| REJECTED
    S -->|"clean"| E["EXECUTEsubprocess.run(shell=False)"]

All execution uses subprocess.run(shell=False). Only tools defined in YAML catalog files can run. Dangerous binaries (cmd, powershell, wscript, etc.) are unconditionally blocked by a hardcoded denylist. Arguments are checked for shell metacharacters, dangerous flags (execution-related: -e, --exec, --command, -enc), and response-file syntax (@filename).

Quick Start

On the Windows forensic workstation, clone the repo:

git clone https://github.com/AppliedIR/wintools-mcp.git; cd wintools-mcp

Or if git is not installed, download and extract the ZIP:

Invoke-WebRequest https://github.com/AppliedIR/wintools-mcp/archive/refs/heads/main.zip -OutFile wintools.zip
Expand-Archive wintools.zip -DestinationPath . -Force; cd wintools-mcp-main

Then run the installer:

.\scripts\setup-windows.ps1

See [SETUP.md](SETUP.md) for detailed deployment options and SMB configuration.

MCP Tools (10 total)

Discovery (6 tools)

| Tool | Description | |------|-------------| | scan_tools | Scan for all cataloged forensic tools, report availability and install guidance | | list_windows_tools | List all cataloged tools with installation status, filterable by category | | list_missing_windows_tools | List tools not installed, with installation guidance and alternatives | | check_windows_tools | Check specific tools by name for availability | | get_windows_tool_help | Get tool-specific help, flags, caveats, and interpretation guidance | | suggest_windows_tools | Given an artifact type, suggest relevant tools and check availability |

Evidence Access (1 tool)

| Tool | Description | |------|-------------| | get_share_info | Get SMB share paths for evidence access (shareroot, casedir, evidencedir, extractionsdir) |

KAPE Discovery (1 tool)

| Tool | Description | |------|-------------| | list_kape_targets | List available KAPE targets or modules in structured categories. KAPE is for parsing already-collected evidence, not live collection. |

Batch Execution (1 tool)

| Tool | Description | |------|-------------| | batch_scan | Run a tool against all files in a directory with safety bounds (max_files cap, timeout, per-tool limits like 100 for capa) |

Generic Execution (1 tool)

| Tool | Description | |------|-------------| | run_windows_command | Execute any cataloged tool with arguments (catalog-gated) |

All per-tool wrappers (Zimmerman suite, Hayabusa, mactime) are consolidated into run_windows_command. The tool catalog defines each binary's input flags, output format, and FK knowledge mapping. batch_scan extends this to directory-level operations with safety caps.

Tool Catalog

Tools are defined in YAML catalog files under data/catalog/. The catalog currently contains 31 tool entries across 7 files:

| File | Count | Tools | |------|-------|-------| | zimmerman.yaml | 14 | AmcacheParser, AppCompatCacheParser, EvtxECmd, JLECmd, LECmd, MFTECmd, PECmd, RBCmd, RECmd, SBECmd, SQLECmd, SrumECmd, WxTCmd, bstrings | | sysinternals.yaml | 5 | autorunsc, sigcheck, strings, handle, procdump | | memory.yaml | 4 | winpmem, dumpit, moneta, hollows_hunter | | timeline.yaml | 3 | Hayabusa, chainsaw, mactime | | analysis.yaml | 3 | capa, yara, densityscout | | collection.yaml | 1 | KAPE | | scripts.yaml | 1 | Get-InjectedThreadEx |

Each entry defines the binary name, input style, output format, timeout, FK knowledge name, install methods, and search paths:

# data/catalog/zimmerman.yaml (excerpt)
category: zimmerman
tools:
  - name: AmcacheParser
    binary: AmcacheParser.exe
    description: "Parse Amcache.hve for program execution evidence"
    input_flag: "-f"
    output_format: csv
    timeout_seconds: 300
    fk_tool_name: AmcacheParser
    install_methods:
      - method: direct
        url: "https://ericzimmerman.github.io/#!index.md"
      - method: dotnet
        command: "dotnet tool install --global AmcacheParser"
    install_paths:
      - "C:\\Tools\\ZimmermanTools"

Response Envelope

Every tool response is wrapped in a structured envelope with forensic-knowledge enrichment:

{
  "success": true,
  "tool": "run_windows_command",
  "data": {"output": {"rows": ["..."], "total_rows": 42}},
  "data_provenance": "tool_output_may_contain_untrusted_evidence",
  "output_format": "parsed_csv",
  "audit_id": "wintools-steve-20260220-001",
  "examiner": "steve",
  "caveats": [
    "Amcache entries indicate installation, not necessarily execution",
    "Timestamps reflect installation time, not last run"
  ],
  "advisories": ["Cross-reference with Prefetch for execution confirmation"],
  "corroboration": {
    "artifacts": ["prefetch", "shimcache"],
    "tools": ["PECmd", "AppCompatCacheParser"]
  },
  "field_notes": {"KeyLastWriteTimestamp": "Last time the registry key was modified"},
  "discipline_reminder": "Evidence is sovereign -- if results conflict with your hypothesis, revise the hypothesis, never reinterpret evidence to fit"
}

| Field | Source | Description | |-------|--------|-------------| | audit_id | Audit | Unique identifier (wintools-{examiner}-{YYYYMMDD}-{NNN}) | | caveats | forensic-knowledge | Artifact-specific limitations and interpretation warnings | | advisories | forensic-knowledge | Usage guidance and common misinterpretation corrections | | corroboration | forensic-knowledge | Suggested cross-reference artifacts and tools | | field_notes | forensic-knowledge | Timestamp field meanings from artifact definitions | | discipline_reminder | Built-in | Rotating forensic methodology reminder (14 total, cycled per call) |

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | WINTOOLS_TIMEOUT | 600 | Default command timeout in seconds | | WINTOOLS_HOST | 127.0.0.1 | HTTP server bind address | | WINTOOLS_PORT | 4624 | HTTP server port | | WINTOOLS_TOOL_PATHS | (none) | Additional binary search directories (path-separated) | | WINTOOLS_CATALOG_DIR | (auto) | Override path to catalog YAML directory | | VHIR_CASE_DIR | (none) | Active case directory; enables per-case audit trail | | VHIR_AUDIT_DIR | (none) | Local audit directory (overrides VHIRCASEDIR/audit/) | | VHIR_SHARE_ROOT | (none) | SMB mount root for evidence reads and extraction writes (e.g., E:\cases\SRL2\) | | VHIR_ACTIVE_CASE | (none) | Case identifier recorded in audit entries | | VHIR_EXAMINER | OS user | Examiner identity (lowercase slug) |

YAML Config File

Pass via --config path/to/config.yaml. Environment variables override YAML values.

| Key | Default | Description | |-----|---------|-------------| | default_timeout | 600 | Subprocess timeout in seconds | | max_output_bytes | 52428800 | Subprocess capture limit (50MB) | | response_byte_budget | 10240 | Maximum bytes in MCP response envelope (10KB) | | http_host | 127.0.0.1 | HTTP bind address | | http_port | 4624 | HTTP port | | hayabusa_dir | C:\Tools\Hayabusa | Hayabusa installation directory | | tool_paths | [] | Additional binary search directories | | api_keys | {} | API keys for Bearer token authentication |

Bearer Token Authentication

All API requests require a valid bearer token. Tokens are generated during installation with the vhir_wt_ prefix (24 hex characters, 96 bits of entropy). The token is stored in config.yaml under api_keys and displayed post-install for the examiner to copy to their SIFT gateway configuration.

# config.yaml (on Windows)
api_keys:
  vhir_wt_a1b2c3d4e5f6a1b2c3d4e5f6:
    examiner: "default"
    role: "examiner"

Every request must include the Authorization: Bearer header. Requests without a valid token receive a 401 response. Use --no-auth during development only.

Connecting from the SIFT Gateway

To route tool calls through the SIFT gateway, add a wintools backend entry to gateway.yaml on the SIFT workstation:

backends:
  wintools-mcp:
    type: http
    url: "http://WIN_IP:4624/mcp"
    bearer_token: "vhir_wt_..."

Alternatively, vhir setup prompts for the Windows VM address and token during interactive configuration.

LLM clients can also connect directly to wintools-mcp without going through the gateway, using the same bearer token in their MCP client configuration.

Evidence Access via SMB

wintools-mcp accesses the case directory on the SIFT workstation via an authenticated SMB share. The Valhuntir installer (vhir join --wintools) configures this automatically. The SMB share gives wintools-mcp:

• Read access to evidence files (disk images, registry hives, event logs, prefetch, etc.)
• Write access to the extractions directory (parsed output: CSVs, timelines, JSON)
• Write access to the audit directory (per-tool execution logs)

Set VHIR_SHARE_ROOT to the SMB mount point on Windows:

$env:VHIR_SHARE_ROOT = "E:\cases\SRL2\"

The share must use authenticated connections. Restrict access to the Valhuntir components that need it. See [SETUP.md](SETUP.md) for detailed SMB configuration including share creation, user credentials, and firewall rules.

Network requirements: The SIFT gateway connects to wintools-mcp over HTTPS with Bearer token authentication (port 4624). The Windows workstation connects to SIFT over SMB (port 445). Both connections must be permitted by the firewall on the isolated forensic network. No connections should be allowed from outside the forensic environment.

Audit Trail

Every tool execution is logged to the audit directory. Resolution order: explicit audit_dir constructor parameter > VHIR_AUDIT_DIR env var > VHIR_CASE_DIR/audit/. Evidence IDs follow the format wintools-{examiner}-{YYYYMMDD}-{NNN} and resume sequence numbering across process restarts.

Security Considerations

All Valhuntir components are assumed to run on an isolated forensic network, protected by firewalls, and not exposed to the Internet or untrusted systems. wintools-mcp accepts incoming connections from the SIFT gateway and LLM clients within this network. These inter-component connections are expected and intentional. The system must never be exposed to networks outside the forensic environment.

All API requests require a valid bearer token (vhir_wt_ prefix). Tokens are generated during installation and must be securely transferred to the SIFT gateway configuration or LLM client setup. The --no-auth flag is for development only and must not be used in any environment with real evidence.

Any data loaded into the system runs the risk of being exposed to the underlying AI. Only place data on these systems that you are willing to send to your AI provider.

wintools-mcp parses forensic artifacts (registry hives, event logs, prefetch files, memory dumps) that may contain hostile content crafted by an attacker. Tools run as subprocesses with shell=False and catalog-gated execution to limit attack surface. The hardcoded denylist, catalog allowlist, and argument sanitization are defense-in-depth measures, not preventative controls.

Case directory access via SMB share should use authenticated connections. The share should be restricted to the Valhuntir components that need access. Read-only access is sufficient for evidence files; write access is needed for extractions and audit entries.

Evidence Handling

Never place original evidence on any Valhuntir system. Only use working copies for which verified originals or backups exist. Valhuntir workstations process evidence through AI-connected tools, and any data loaded into these systems may be transmitted to the configured AI provider. Treat all Valhuntir systems as analysis environments, not evidence storage.

Evidence integrity is verified by SHA-256 hashes recorded at registration. Examiners can optionally lock evidence to read-only via vhir evidence lock. Proper evidence integrity depends on verified hashes, write blockers, and chain-of-custody procedures that exist outside this platform.

Case directories can reside on external or removable media.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AppliedIR
• Source: AppliedIR/wintools-mcp
• License: MIT
• Homepage: https://appliedir.github.io/Valhuntir/

Install and usage instructions live in the source repository linked above.