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 >)