Winforensics Mcp

Windows Forensics MCP Server

> Windows DFIR from Linux - A comprehensive forensics toolkit designed entirely for Linux environments with zero Windows tool dependencies. Parse Windows artifacts natively using pure Python libraries.

---

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 | Parse Windows Event Logs with filtering, search, and pre-built security queries | | Registry | Analyze SAM, SYSTEM, SOFTWARE, SECURITY, NTUSER.DAT hives | | 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 | Application resource usage, CPU time, network activity 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 with suspicious path detection | | RecentDocs | Registry-based recent document tracking |

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]"

Verify

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

---

Adding to Claude CLI

Installed from PyPI

claude mcp add winforensics-mcp --scope user -- uv run winforensics-mcp

Installed from sources

claude mcp add winforensics-mcp \
  --scope user \
  -- uv run --directory /path/to/winforensics-mcp python -m winforensics_mcp.server

Verify:

claude mcp list
# Should show winforensics-mcp

---

LLM Integration (CLAUDE.md)

For AI-assisted forensic analysis, include [CLAUDE.md](CLAUDE.md) in your case directory. It provides:

• Orchestrator-first guidance - Ensures LLMs use high-level tools before low-level parsers
• Token efficiency - Reduces API costs by 50%+ through proper tool selection
• Investigation workflow - Step-by-step methodology for consistent analysis

Usage

Copy CLAUDE.md to your case directory:

cp /path/to/winforensics-mcp/CLAUDE.md /your/case/directory/
# Edit paths in CLAUDE.md to match your case

The LLM will automatically follow the orchestrator-first approach:

| Question | Orchestrator Used | |----------|------------------| | "Was malware.exe executed?" | investigate_execution | | "What did the user do?" | investigate_user_activity | | "Find this hash everywhere" | hunt_ioc | | "Build incident timeline" | build_timeline |

---

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"}
  ]
}

---

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, 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 for app resource and network usage |

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_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 for folder navigation history |

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 (time, Event ID, keywords) | | 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_get_persistence | Get Run keys and services | | registry_get_users | Get user accounts from SAM | | registry_get_usb_history | Get USB device history | | 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

Remove MCP Server

claude mcp remove winforensics-mcp --scope user

---

License

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

Core winforensics-mcp code is MIT licensed. See [LICENSE](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 >)

Source & license

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

• Author: x746b
• Source: x746b/winforensics-mcp
• License: MIT

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