<img src="icon.png" width="150" alt="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](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 >)