Winforensics Mcp

Windows Forensics MCP Server

Windows DFIR from Linux - A comprehensive forensics toolkit designed for Linux environments with no Windows runtime dependencies. Parse Windows artifacts natively, with an optional Rust SIDR sidecar for Windows Search.

---

Related Projects

• mem_forensics-mcp - Unified Memory Forensics MCP Server - Multi-tier engine combining Rust speed with Vol3 coverage
• mac_forensics-mcp - macOS DFIR - Unified Logs, FSEvents, Spotlight, Plists, SQLite databases, Extended Attributes

---

Features

Core Forensics

Category	Capabilities
EVTX Logs	Compact structured queries, field filters, logon correlation, NTLM summaries, and JSONL export
Offline NTDS	Query exact SAM accounts, domain SIDs, and trust metadata without credential decryption
Registry	Analyze SAM, SYSTEM, SOFTWARE, SECURITY, and NTUSER.DAT; paginated queries, normalized FILETIMEs, and USBSTOR/WPD correlation
Remote Collection	Collect artifacts via WinRM (password or pass-the-hash)

Execution Artifacts

Category	Capabilities
PE Analysis	Static analysis with hashes (MD5/SHA1/SHA256/imphash), imports, exports, packer detection
Prefetch	Execution evidence with run counts, timestamps, loaded files
Amcache	SHA1 hashes and first-seen timestamps from Amcache.hve
SRUM	Exact application/time filtering, raw resource counters, network MB/MiB totals, and optional aggregation from SRUDB.dat

File System Artifacts

Category	Capabilities
MFT	Master File Table parsing with ADS metadata and timestomping detection
USN Journal	Change journal for file operations and deleted file recovery
Timeline	Unified timeline from MFT, USN, Prefetch, Amcache, EVTX

User Activity

Category	Capabilities
Browser	Edge, Chrome, Firefox history and downloads
LNK Files	Windows shortcut analysis for recently accessed files
ShellBags	Folder navigation history from both UsrClass.dat and NTUSER.DAT, incl. UNC shares and browsed archive interiors (libfwsi)
RecentDocs	Registry-based recent document tracking
Windows Search	SIDR-backed Windows.edb file, internet-history, activity-history, and System.Search.AutoSummary recovery

Network Forensics

Category	Capabilities
PCAP Analysis	Parse PCAP/PCAPNG files - conversations, DNS queries, HTTP requests, suspicious connections

API Monitor Capture Analysis

Category	Capabilities
APMX Parsing	Parse API Monitor captures (.apmx64/.apmx86) - process metadata, API call extraction, parameter values
Pattern Detection	Detect injection, hollowing, credential dumping, and other attack patterns from captured API call sequences with MITRE ATT&CK mapping
Handle Correlation	Track handle values across calls to reconstruct attack chains (OpenProcess -> VirtualAllocEx -> WriteProcessMemory -> CreateRemoteThread)
Injection Analysis	Extract enriched injection chain details: target PID/process, shellcode size, allocation addresses, technique classification
API Knowledge Base	26,944 Windows API definitions with parameter signatures, DLL mappings, and category browsing

Malware Detection

Category	Capabilities
YARA Scanning	718 rules from signature-base - APT, ransomware, webshells, hacktools
IoC Packs	Behavioral IoC packs for hunting across exported logs, filenames, and PCAP payloads; includes optional GPL-2.0 impacket-iocs pack with 65 rules
VirusTotal	Hash/IP/domain reputation lookups with caching and rate limiting (free tier supported)
DiE Integration	Detect packers (UPX, Themida, VMProtect), compilers, .NET, installers via Detect It Easy

Orchestrators

Tool	What It Does
investigate_execution	Correlates Prefetch + Amcache + SRUM to answer "Was this binary executed?"
investigate_user_activity	Correlates Browser + ShellBags + LNK + RecentDocs for user activity timeline
hunt_ioc	Searches for IOC (hash/filename/IP/domain) across ALL artifact sources + optional YARA scanning
hunt_ioc_pack	Hunts behavioral IoCs from bundled/external metadata packs such as impacket-iocs
build_timeline	Builds unified forensic timeline from multiple sources

Utilities

Tool	What It Does
ingest_parsed_csv	Import Eric Zimmerman tool CSV output (MFTECmd, PECmd, AmcacheParser)

---

Installation

Prerequisites

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Ensure Python 3.10+
python3 --version

Install from PyPI

uv tool install winforensics-mcp

Install from source

git clone https://github.com/x746b/winforensics-mcp.git
cd winforensics-mcp

# Install with uv (recommended)
uv sync

# Or install with all optional extras
uv venv && source .venv/bin/activate
uv pip install -e ".[all]"

Windows Search parsing uses SIDR 0.9.2. The source repository includes stripped Linux releases for ARM64 (.tools/sidr) and x86_64 (.tools/sidr_x86), built from the pinned commit recorded in their adjacent manifests. Either architecture can rebuild that exact revision with:

bash scripts/build_sidr.sh

The server discovers SIDR from an explicit tool argument, WINFORENSICS_SIDR_PATH, the architecture-matched bundled binary, or PATH, in that order. It never downloads or builds executables at runtime. Build or supply SIDR 0.9.2 separately on unsupported platforms. Without SIDR, windows_search_parse uses a clearly marked partial pyesedb fallback that cannot recover every compressed long value.

Verify

uv run python -m winforensics_mcp.server
# Should start without errors (Ctrl+C to exit)

---

Add to an MCP client

Register winforensics-mcp as a local stdio server in your MCP client's settings. Configuration format and location depend on the client. For clients that accept mcpServers JSON, a PyPI install (uv tool install winforensics-mcp) looks like this:

{
  "mcpServers": {
    "winforensics-mcp": {
      "command": "winforensics-mcp"
    }
  }
}

For a source checkout (uv sync), use:

{
  "mcpServers": {
    "winforensics-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/winforensics-mcp", "python", "-m", "winforensics_mcp.server"]
    }
  }
}

Replace the example path with the absolute path to your checkout. If your client uses a different configuration format, enter the same command and arguments through its MCP server settings. Make sure winforensics-mcp or uv, respectively, is on the client's PATH, then use the client's MCP server list to confirm it connects.

---

Quick Start Examples

Was This Binary Executed?

Investigate if mimikatz.exe was executed on the system at /mnt/evidence

The investigate_execution orchestrator checks Prefetch, Amcache, and SRUM:

{
  "target": "mimikatz.exe",
  "execution_confirmed": true,
  "confidence": "HIGH",
  "evidence": [
    {"source": "Prefetch", "finding": "Executed 3 times, last at 2024-03-15T14:23:45Z"},
    {"source": "Amcache", "finding": "SHA1: abc123..., First seen: 2024-03-14T09:00:00Z"},
    {"source": "SRUM", "finding": "Network: 15.2 MB sent; Foreground: 47 seconds"}
  ]
}

Hunt for IOC Across All Artifacts

Hunt for the hash 204bc44c651e17f65c95314e0b6dfee586b72089 in /mnt/evidence

The hunt_ioc tool searches Prefetch, Amcache, SRUM, MFT, USN, Browser, EVTX, and optionally YARA:

{
  "ioc": "204bc44c651e17f65c95314e0b6dfee586b72089",
  "ioc_type": "sha1",
  "found": true,
  "sources_with_hits": ["Amcache", "MFT"],
  "findings": [
    {"source": "Amcache", "matches": 1, "details": "bloodhound.exe"},
    {"source": "MFT", "matches": 1, "details": "Users\\Admin\\Downloads\\bloodhound.exe"}
  ]
}

---

Compact EVTX and Offline AD Queries

Use compact, fields, where, and max_chars to keep EVTX results focused:

{
  "evtx_path": "/evidence/Security.evtx",
  "event_ids": [4724],
  "where": {"EventData.SubjectUserName": {"neq": "Administrator"}},
  "compact": true,
  "fields": ["EventID", "TimeCreated", "EventData.TargetUserName"],
  "max_chars": 12000
}

Follow next_cursor with the same query; evtx_get_event opens a full record. Use the helpers below for logon correlation, rare-first NTLM summaries, and JSONL exports. Descriptor tools decode explicit hex/base64 and report unavailable values honestly. NTDS tools query account, domain, and trust metadata without SYSTEM or credential decryption.

See the query reference for examples, limits, and completeness semantics.

Tool Reference

Orchestrators (High-Level Investigation)

Tool	Description
investigate_execution	Correlate Prefetch/Amcache/SRUM to prove binary execution
investigate_user_activity	Correlate Browser/ShellBags/LNK/RecentDocs for user activity
hunt_ioc	Hunt IOC (hash/filename/IP/domain) across all artifacts; yara_scan=True adds YARA threat intel
build_timeline	Build unified timeline from multiple artifact sources

Execution Artifacts

Tool	Description
file_analyze_pe	Static PE analysis - hashes, imports, exports, Authenticode program name, packer detection
disk_parse_prefetch	Parse Prefetch for execution evidence
disk_parse_amcache	Parse Amcache.hve for SHA1 hashes and timestamps
disk_parse_srum	Parse SRUDB.dat with exact/regex app filters, UTC ranges, derived network units, and optional aggregation

Malware Detection (YARA)

Tool	Description
yara_scan_file	Scan file with 718 YARA rules (Mimikatz, CobaltStrike, webshells, APT, ransomware)
yara_scan_directory	Batch scan directory for malware
yara_list_rules	List available/bundled YARA rules

Behavioral IoC Packs

Tool	Description
ioc_pack_list	List bundled and external IoC packs with license metadata
hunt_ioc_pack	Hunt behavioral IoCs across text exports, filenames, and PCAP payloads

Threat Intelligence (VirusTotal)

Tool	Description
vt_lookup_hash	Look up file hash (MD5/SHA1/SHA256) on VirusTotal
vt_lookup_behavior	Bounded sandbox domains, URLs, commands, registry/file writes; optional full-result persistence
vt_lookup_ip	Get IP address reputation and geolocation
vt_lookup_domain	Get domain reputation and categorization
vt_lookup_file	Calculate file hashes and look up on VirusTotal

Network Forensics (PCAP)

Tool	Description
pcap_get_stats	Get PCAP statistics - packet counts, protocols, top talkers
pcap_get_conversations	Extract TCP/UDP conversations with byte counts
pcap_get_dns	Extract DNS queries and responses
pcap_get_http	Extract HTTP requests with URLs, methods, user-agents
pcap_search	Search packet payloads for strings or regex patterns
pcap_find_suspicious	Detect C2 indicators, beaconing, DNS tunneling

API Monitor Capture Analysis (APMX)

Tool	Description
apmx_parse	Parse .apmx64/.apmx86 capture - process info, modules, call counts
apmx_get_calls	Extract API calls with filtering, pagination, and time range support
apmx_get_call_details	Detailed records with parameter values, return values, timestamps
apmx_detect_patterns	Detect attack patterns (injection, hollowing, credential dumping) with MITRE ATT&CK IDs
apmx_correlate_handles	Track handle producer/consumer chains across API calls
apmx_get_injection_info	Enriched injection chain extraction (target PID, shellcode size, technique)
apmx_get_calls_around	Context window of calls around a specific record
apmx_search_params	Search all records for a specific parameter value
api_analyze_imports	Full PE import analysis with pattern detection and MITRE ATT&CK mapping
api_detect_patterns	Detect attack patterns from PE import tables
api_lookup	Look up Windows API signature (26,944 APIs with params, DLL, category)
api_search_category	Browse APIs by category (e.g., "Process Injection", "File Management")

Packer Detection (DiE)

Tool	Description
die_analyze_file	Analyze file for packers, compilers, protectors, .NET
die_scan_directory	Batch scan directory for packed executables
die_get_packer_info	Get info about packer (difficulty, unpack tools)

File System

Tool	Description
disk_parse_mft	Parse $MFT with ADS metadata and timestomping detection
disk_parse_usn_journal	Parse $J for file operations and deleted files

User Activity

Tool	Description
browser_get_history	Parse Edge/Chrome/Firefox history and downloads
user_parse_lnk_files	Parse Windows shortcuts for target paths
user_parse_shellbags	Parse ShellBags (UsrClass.dat + NTUSER.DAT) for folder navigation, network shares and archive browsing
windows_search_parse	Parse an explicit Windows.edb with SIDR; filter and paginate file, internet, activity, and indexed-content records

Offline Active Directory

Tool	Description
ntds_get_object_by_sam	Read allowlisted metadata for an exact offline SAM account selector
ntds_get_object_sid	Return SID metadata with explicit ambiguity/completeness status
ntds_get_domain_info	Read domain metadata and evidence-backed forest-root attribution
ntds_get_trusts	Read paginated trust metadata without authentication secrets

Event Logs

Tool	Description
evtx_list_files	List EVTX files in a directory
evtx_get_stats	Get event counts, time range, Event ID distribution
evtx_search	Search with filters, compact field projection, response budgets, and stable continuation
evtx_get_event	Retrieve a full normalized event using its source-bound reference
evtx_correlate_logon_id	Join subject/target LUID occurrences within an explicit time window
evtx_export	Persist filtered JSONL with a hash, completion diagnostics, and bounded preview
evtx_ntlm_operational_summary	Group NTLM 4021/4022/4023 events and surface rare process/user combinations
security_descriptor_decode	Decode bounded self-relative descriptor bytes from explicit hex/base64
evtx_describe_security_descriptor	Describe an EVTX attribute descriptor or report its source placeholder
evtx_security_search	Pre-built security event searches (logon, process creation, etc.)
evtx_attack_summary	Compact TSV summary for rapid triage - one line per event, attack-relevant columns only
evtx_explain_event_id	Get Event ID description

Registry

Tool	Description
registry_get_key	Get specific key and values
registry_search	Search values by pattern
registry_query	Paginated exact/substring/regex registry query with subtree scope, field projection, and diagnostics
registry_get_persistence	Get Run keys and services
registry_get_users	Get user accounts from SAM
registry_get_usb_history	Correlate USBSTOR identity, physical serial, WPD device names, and secondary volume labels
registry_get_system_info	Get OS version, hostname, timezone
registry_get_network	Get network configuration

Utilities

Tool	Description
ingest_parsed_csv	Import Eric Zimmerman CSV output (MFTECmd, PECmd, AmcacheParser, SrumECmd)
forensics_list_important_events	List important Event IDs by channel
forensics_list_registry_keys	List forensic registry keys by category

Remote Collection

Tool	Description
remote_collect_artifacts	Collect artifacts via WinRM (password or pass-the-hash)
remote_get_system_info	Get remote system info

---

Configuration

VirusTotal API Key

# Option 1: Environment variable
export VIRUSTOTAL_API_KEY="your-api-key-here"

# Option 2: Config file
mkdir -p ~/.config/winforensics-mcp
echo "your-api-key-here" > ~/.config/winforensics-mcp/vt_api_key

Get your free API key at virustotal.com. Free tier is rate-limited to 4 requests/minute; the client handles rate limiting and caches results for 24 hours.

---

Troubleshooting

DiE (Detect It Easy) not found

# Debian/Ubuntu
sudo apt install detect-it-easy

# Or download from https://github.com/horsicq/DIE-engine/releases

SIDR not found

Source checkouts include stripped SIDR releases for Linux ARM64 and x86_64. To rebuild the pinned revision for the current Rust target, run:

bash scripts/build_sidr.sh

For another installation, set WINFORENSICS_SIDR_PATH to a SIDR 0.9.2 executable. The parser reports the executable path, version, SHA-256, database state, extraction completeness, and evidence hashes in every response. See .tools/SIDR-LICENSE for the bundled sidecar's Apache-2.0 license.

Remove MCP Server

Remove the winforensics-mcp entry from your MCP client's server settings.

---

License

Credits: omerbenamram/evtx (Rust EVTX parser), strozfriedberg/sidr (Windows Search), Rohitab Batra (API Monitor), Neo23x0/signature-base (YARA rules), horsicq/DIE-engine (Detect It Easy)

Core winforensics-mcp code is MIT licensed. See LICENSE.

Optional bundled IoC packs may use different licenses:

• winforensics_mcp/ioc_packs/impacket-iocs contains material derived from ThatTotallyRealMyth/Impacket-IoCs and is licensed under GPL-2.0. See winforensics_mcp/ioc_packs/impacket-iocs/LICENSE.

Built for the DFIR community. No Windows required >)