# 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](https://github.com/x746b/mem_forensics-mcp)** - Unified Memory Forensics MCP Server - Multi-tier engine combining Rust speed with Vol3 coverage - **[mac_forensics-mcp](https://github.com/x746b/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](http://www.rohitab.com/apimonitor) 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](https://github.com/Neo23x0/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 ```bash # 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 ```bash uv tool install winforensics-mcp ``` ### Install from source ```bash 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 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 ```bash 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: ```json { "mcpServers": { "winforensics-mcp": { "command": "winforensics-mcp" } } } ``` For a source checkout (`uv sync`), use: ```json { "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: ```json { "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: ```json { "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: ```json { "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](docs/query-reference.md) 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 ```bash # 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](https://www.virustotal.com/gui/join-us). 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 ```bash # 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 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](https://github.com/omerbenamram/evtx) (Rust EVTX parser), [strozfriedberg/sidr](https://github.com/strozfriedberg/sidr) (Windows Search), [Rohitab Batra](http://www.rohitab.com/apimonitor) (API Monitor), [Neo23x0/signature-base](https://github.com/Neo23x0/signature-base) (YARA rules), [horsicq/DIE-engine](https://github.com/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](https://github.com/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 >)