Submit

Windows Forensics MCP Server

@x746b

Visit Server
23 days ago
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
OverviewToolsComments
Overview

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.

Why This Matters

Traditional Windows forensics often requires:

  • Running analysis tools on Windows
  • Commercial forensic suites with expensive licenses
  • Eric Zimmerman tools that only run on Windows/.NET

WinForensics-MCP changes this. Built from the ground up for Linux-based analysis:

  • No Windows Required - Analyze Windows disk images directly from your Linux forensics workstation
  • No Wine/Mono Hacks - Pure Python implementations using battle-tested open-source libraries
  • AI-Assisted Analysis - Integrates with Claude CLI and any MCP-compatible client for intelligent artifact correlation
ProjectFocusLink
mem_forensics-mcpUnified Memory Forensics MCP Server - Multi-tier engine combining Rust speed with Vol3 coverage.GitHub
mac_forensics-mcpmacOS DFIR - Unified Logs, FSEvents, Spotlight, Plists, SQLite databases, Extended AttributesGitHub

Use together for complete incident response across platforms.

Features

Core Forensics

CategoryCapabilities
EVTX LogsParse Windows Event Logs with filtering, search, and pre-built security queries
RegistryAnalyze SAM, SYSTEM, SOFTWARE, SECURITY, NTUSER.DAT hives
Remote CollectionCollect artifacts via WinRM (password or pass-the-hash)

Execution Artifacts

CategoryCapabilities
PE AnalysisStatic analysis with hashes (MD5/SHA1/SHA256/imphash), imports, exports, packer detection
PrefetchExecution evidence with run counts, timestamps, loaded files
AmcacheSHA1 hashes and first-seen timestamps from Amcache.hve
SRUMApplication resource usage, CPU time, network activity from SRUDB.dat

File System Artifacts

CategoryCapabilities
MFTMaster File Table parsing with timestomping detection
USN JournalChange journal for file operations and deleted file recovery
TimelineUnified timeline from MFT, USN, Prefetch, Amcache, EVTX

User Activity

CategoryCapabilities
BrowserEdge, Chrome, Firefox history and downloads
LNK FilesWindows shortcut analysis for recently accessed files
ShellBagsFolder navigation history with suspicious path detection
RecentDocsRegistry-based recent document tracking

Network Forensics

CategoryCapabilities
PCAP AnalysisParse PCAP/PCAPNG files - conversations, DNS queries, HTTP requests, suspicious connections

Malware Detection

CategoryCapabilities
YARA Scanning718 rules from signature-base - APT, ransomware, webshells, hacktools
VirusTotalHash/IP/domain reputation lookups with caching and rate limiting (free tier supported)
DiE IntegrationDetect packers (UPX, Themida, VMProtect), compilers, .NET, installers via Detect It Easy

Orchestrators

ToolWhat It Does
investigate_executionCorrelates Prefetch + Amcache + SRUM to answer "Was this binary executed?"
investigate_user_activityCorrelates Browser + ShellBags + LNK + RecentDocs for user activity timeline
hunt_iocSearches for IOC (hash/filename/IP/domain) across ALL artifact sources + optional YARA scanning
build_timelineBuilds unified forensic timeline from multiple sources

Utilities

ToolWhat It Does
ingest_parsed_csvImport 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

git clone https://github.com/x746b/winforensics-mcp.git
cd winforensics-mcp

# Install with uv (recommended)
uv sync

# Or traditional pip
uv venv && source .venv/bin/activate
uv pip install -e .

# For remote collection (WinRM, SSH, SMB):
uv pip install -e ".[remote]"

# For YARA malware scanning:
uv pip install -e ".[yara]"

# For VirusTotal threat intelligence:
uv pip install -e ".[virustotal]"

# For PCAP network analysis:
uv pip install -e ".[pcap]"

# Install everything:
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

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

Alternative: Manual JSON

Edit ~/.claude.json:

{
  "mcpServers": {
    "winforensics-mcp": {
      "command": "uv",
      "args": [
        "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:

QuestionOrchestrator 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,
  "confidence": "HIGH",
  "sources_with_hits": ["Amcache", "MFT"],
  "findings": [
    {"source": "Amcache", "matches": 1, "details": "bloodhound.exe"},
    {"source": "MFT", "matches": 1, "details": "Users\\Admin\\Downloads\\bloodhound.exe"}
  ]
}

Hunt with YARA Scanning

For filename IOCs, enable YARA scanning to get threat intelligence in the same call:

Hunt for suspicious.exe in /mnt/evidence with YARA scanning enabled

{
  "ioc": "suspicious.exe",
  "ioc_type": "filename",
  "found": true,
  "confidence": "HIGH",
  "sources_with_hits": ["Prefetch", "MFT", "YARA"],
  "findings": [
    {"source": "Prefetch", "matches": 1, "details": "Executed 5 times"},
    {"source": "MFT", "matches": 1, "details": "Users\\Admin\\Downloads\\suspicious.exe"},
    {"source": "YARA", "matches": 2, "details": ["Mimikatz_Memory_Rule", "HKTL_Mimikatz"]}
  ]
}

User Activity Investigation

What did the user 'Alpha' do on this system? Check /mnt/evidence/Users/Alpha

The investigate_user_activity orchestrator correlates browser, shellbags, LNK, and RecentDocs:

{
  "activity_found": true,
  "confidence": "HIGH",
  "evidence": [
    {"source": "Browser", "finding": "15 visits, 3 downloads (PowerView.ps1, mimikatz.zip)"},
    {"source": "ShellBags", "finding": "42 folders navigated including \\Windows\\Temp"},
    {"source": "LNK Files", "finding": "8 executables, 12 documents accessed"}
  ],
  "timeline": [
    {"time": "2025-01-20T14:30:00Z", "source": "Browser", "event": "Downloaded: mimikatz.zip"},
    {"time": "2025-01-20T14:31:00Z", "source": "ShellBags", "event": "Navigated: Downloads\\mimikatz"}
  ]
}

Detect Timestomping

Find timestomped files in the MFT at /mnt/evidence/$MFT

{
  "total_timestomped": 2,
  "timestomped_files": [
    {
      "path": "Users\\Alpha\\Downloads\\backdoor.exe",
      "si_created": "2019-01-15T10:00:00Z",
      "fn_created": "2025-01-20T14:30:00Z",
      "detection_reason": "$SI created before $FN (impossible without manipulation)"
    }
  ]
}

Analyze Network Traffic

Analyze the PCAP file at /evidence/capture.pcap for suspicious activity

The pcap_find_suspicious tool detects C2 indicators, beaconing, and DNS tunneling:

{
  "total_findings": 5,
  "findings": {
    "suspicious_ports": [
      {"src_ip": "192.168.1.100", "dst_ip": "185.220.101.1", "port": 4444, "reason": "Connection on suspicious port 4444"}
    ],
    "potential_beaconing": [
      {"src_ip": "192.168.1.100", "dst_ip": "10.10.10.10", "connection_count": 48, "avg_interval_seconds": 60.2}
    ],
    "dns_tunneling_indicators": [
      {"query": "aGVsbG8gd29ybGQ.evil.com", "reason": "Unusually long DNS label (45 chars)"}
    ]
  }
}

Detect Packers with DiE

Check if malware.exe is packed using DiE

The die_analyze_file tool detects packers, compilers, and protectors:

{
  "file": "/evidence/malware.exe",
  "file_type": "PE32",
  "arch": "x86",
  "detects": [
    {"type": "Packer", "name": "UPX", "version": "3.96"},
    {"type": "Compiler", "name": "MSVC", "version": "14.0"}
  ],
  "is_packed": true,
  "is_dotnet": false
}

Look Up Hash on VirusTotal

Look up this hash on VirusTotal: d41d8cd98f00b204e9800998ecf8427e

{
  "hash": "d41d8cd98f00b204e9800998ecf8427e",
  "hash_type": "md5",
  "found": true,
  "verdict": "malicious",
  "detection_ratio": "45/72",
  "popular_threat_names": ["Trojan.GenericKD", "Win32/Trojan"],
  "file_type": "Win32 EXE",
  "first_submission": "2024-01-15T10:00:00Z"
}

Scan for Malware with YARA

Scan /mnt/evidence/Users/Admin/Downloads for malware

The yara_scan_directory tool uses 718 rules from signature-base:

{
  "directory": "/mnt/evidence/Users/Admin/Downloads",
  "files_scanned": 47,
  "files_matched": 2,
  "matches": [
    {
      "file": "mimikatz.exe",
      "match_count": 3,
      "matches": [
        {"rule": "Mimikatz_Memory_Rule_1", "namespace": "gen_mimikatz"},
        {"rule": "mimikatz", "namespace": "gen_mimikatz"},
        {"rule": "HKTL_Mimikatz", "namespace": "thor-hacktools"}
      ]
    },
    {
      "file": "beacon.dll",
      "match_count": 1,
      "matches": [
        {"rule": "CobaltStrike_Beacon", "namespace": "apt_cobaltstrike"}
      ]
    }
  ]
}

Import Eric Zimmerman CSV Output

Already ran MFTECmd on Windows? Import the CSV:

Ingest the MFTECmd CSV at /cases/MFTECmd_output.csv and search for .exe files

{
  "csv_type": "mftecmd",
  "total_rows": 193008,
  "filter": {"field": "extension", "value": ".exe"},
  "total_matched": 4308,
  "entries": [...]
}

Tool Reference

Orchestrators (High-Level Investigation)

ToolDescription
investigate_executionCorrelate Prefetch/Amcache/SRUM to prove binary execution
investigate_user_activityCorrelate Browser/ShellBags/LNK/RecentDocs for user activity
hunt_iocHunt IOC (hash/filename/IP/domain) across all artifacts; yara_scan=True adds YARA threat intel
build_timelineBuild unified timeline from multiple artifact sources

Execution Artifacts

ToolDescription
file_analyze_peStatic PE analysis - hashes, imports, exports, packer detection
disk_parse_prefetchParse Prefetch for execution evidence
disk_parse_amcacheParse Amcache.hve for SHA1 hashes and timestamps
disk_parse_srumParse SRUDB.dat for app resource and network usage

Malware Detection (YARA)

ToolDescription
yara_scan_fileScan file with 718 YARA rules (Mimikatz, CobaltStrike, webshells, APT, ransomware)
yara_scan_directoryBatch scan directory for malware
yara_list_rulesList available/bundled YARA rules

Threat Intelligence (VirusTotal)

ToolDescription
vt_lookup_hashLook up file hash (MD5/SHA1/SHA256) on VirusTotal
vt_lookup_ipGet IP address reputation and geolocation
vt_lookup_domainGet domain reputation and categorization
vt_lookup_fileCalculate file hashes and look up on VirusTotal

Network Forensics (PCAP)

ToolDescription
pcap_get_statsGet PCAP statistics - packet counts, protocols, top talkers
pcap_get_conversationsExtract TCP/UDP conversations with byte counts
pcap_get_dnsExtract DNS queries and responses
pcap_get_httpExtract HTTP requests with URLs, methods, user-agents
pcap_searchSearch packet payloads for strings or regex patterns
pcap_find_suspiciousDetect C2 indicators, beaconing, DNS tunneling

Packer Detection (DiE)

ToolDescription
die_analyze_fileAnalyze file for packers, compilers, protectors, .NET
die_scan_directoryBatch scan directory for packed executables
die_get_packer_infoGet info about packer (difficulty, unpack tools)

File System

ToolDescription
disk_parse_mftParse $MFT with timestomping detection
disk_parse_usn_journalParse $J for file operations and deleted files

User Activity

ToolDescription
browser_get_historyParse Edge/Chrome/Firefox history and downloads
user_parse_lnk_filesParse Windows shortcuts for target paths
user_parse_shellbagsParse ShellBags for folder navigation history

Event Logs

ToolDescription
evtx_list_filesList EVTX files in a directory
evtx_get_statsGet event counts, time range, Event ID distribution
evtx_searchSearch with filters (time, Event ID, keywords)
evtx_security_searchPre-built security event searches (logon, process creation, etc.)
evtx_explain_event_idGet Event ID description

Registry

ToolDescription
registry_get_keyGet specific key and values
registry_searchSearch values by pattern
registry_get_persistenceGet Run keys and services
registry_get_usersGet user accounts from SAM
registry_get_usb_historyGet USB device history
registry_get_system_infoGet OS version, hostname, timezone
registry_get_networkGet network configuration

Utilities

ToolDescription
ingest_parsed_csvImport Eric Zimmerman CSV output (MFTECmd, PECmd, AmcacheParser, SrumECmd)
forensics_list_important_eventsList important Event IDs by channel
forensics_list_registry_keysList forensic registry keys by category

Remote Collection

ToolDescription
remote_collect_artifactsCollect artifacts via WinRM (password or pass-the-hash)
remote_get_system_infoGet remote system info

Typical Investigation Workflow

1. Mount Evidence

mount -o ro,loop /path/to/image.E01 /mnt/evidence
# Or use ewfmount for E01 files

2. Quick Triage

Investigate execution of mimikatz.exe and powershell.exe in /mnt/evidence

3. Hunt for Known IOCs

Hunt for these hashes in /mnt/evidence: abc123..., def456...

4. User Activity Deep Dive

Investigate user activity for 'Administrator' in /mnt/evidence

5. Timeline Analysis

Build a timeline for /mnt/evidence filtering for 'mimikatz'

6. Persistence Check

Check persistence mechanisms in the SYSTEM and SOFTWARE hives

7. Malware Analysis

Scan the Downloads folder for malware with YARA

8. Threat Intelligence

Look up suspicious hashes on VirusTotal
Check if this C2 IP is known malicious: 185.220.101.1

Configuration

VirusTotal API Key

For threat intelligence lookups, configure your 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.

Note: Free tier is rate-limited to 4 requests/minute. The client automatically handles rate limiting and caches results for 24 hours.

Adjusting Response Limits

Edit winforensics_mcp/config.py:

MAX_EVTX_RESULTS = 50       # Event log search results
MAX_REGISTRY_RESULTS = 50   # Registry search results
MAX_PREFETCH_RESULTS = 20   # Prefetch entries
MAX_AMCACHE_RESULTS = 30    # Amcache entries
MAX_TIMELINE_RESULTS = 50   # Timeline events
MAX_MFT_RESULTS = 30        # MFT entries
MAX_USN_RESULTS = 30        # USN Journal records

Troubleshooting

Missing dependencies

uv pip install pefile libscca-python libesedb-python mft pylnk3

# For YARA scanning
uv pip install yara-python

# For VirusTotal lookups
uv pip install vt-py

VirusTotal API errors

If you see "API key not configured":

# Check if key is set
echo $VIRUSTOTAL_API_KEY

# Or create config file
mkdir -p ~/.config/winforensics-mcp
echo "your-key" > ~/.config/winforensics-mcp/vt_api_key

If you see rate limit errors, wait 15 seconds between requests (automatic) or use cached results.

DiE (Detect It Easy) not found

Install diec (command-line version):

# Debian/Ubuntu
sudo apt install detect-it-easy

# Or download from GitHub
# https://github.com/horsicq/DIE-engine/releases
# Extract and add to PATH

Permission denied on registry hives

Registry hives may be locked. Use offline/copied hives from a mounted image.

Remove MCP Server

claude mcp remove winforensics-mcp --scope user

Dependencies

All parsing is done with pure Python libraries:

LibraryPurpose
python-evtxEVTX parsing
python-registryRegistry hive parsing
pefilePE file analysis
libscca-pythonPrefetch parsing
libesedb-pythonESE database (SRUM) parsing
mftMFT parsing (Rust-based, Python bindings)
pylnk3LNK file parsing
yara-pythonYARA rule scanning (optional)
vt-pyVirusTotal API client (optional)
scapyPCAP/PCAPNG parsing (optional)

Bundled YARA Rules

718 rules from Neo23x0/signature-base are included:

CategoryExamples
APTLazarus, APT28, APT29, Turla, Sofacy, CobaltStrike
CrimewareEmotet, TrickBot, Ransomware families
GenericMimikatz, webshells, PowerShell obfuscation
ExploitsLog4Shell, ProxyShell, PrintNightmare
HacktoolsBruteRatel, Empire, Metasploit payloads

Changelog

v0.4.0 - Threat Intel & Network Edition

  • YARA Scanning: 718 bundled rules from signature-base (APT, ransomware, hacktools, webshells)
  • VirusTotal Integration: Hash/IP/domain lookups with rate limiting and 24h caching
  • PCAP Analysis: Network forensics with conversation extraction, DNS/HTTP parsing, C2 detection
  • DiE Integration: Packer/compiler detection via Detect It Easy CLI
  • hunt_ioc Enhancement: Optional yara_scan=True parameter to scan found files with YARA rules
  • New Tools: yara_scan_*, vt_lookup_*, pcap_*, die_*
  • Total Tools: 46

v0.3.x

  • Core forensics: EVTX, Registry, PE analysis, Prefetch, Amcache, SRUM
  • File system: MFT parsing with timestomping detection, USN Journal
  • User activity: Browser history, LNK files, ShellBags
  • Orchestrators: investigate_execution, investigate_user_activity, hunt_ioc, build_timeline

License

MIT License

Author

xtk

Built for the DFIR community. No Windows required.

Try in Playground

Server Config

{
  "mcpServers": {
    "winforensics-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/winforensics-mcp",
        "python",
        "-m",
        "winforensics_mcp.server"
      ]
    }
  }
}
© 2025 MCP.so. All rights reserved.

Build with ShipAny.