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 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 |
| 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 |
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 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 |
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 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_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: Rohitab Batra (API Monitor), Neo23x0/signature-base (YARA rules), horsicq/DIE-engine (Detect It Easy)
MIT License | xtk | Built for the DFIR community. No Windows required >)
