Windows Memory Forensics MCP

WARNING: PROOF OF CONCEPT

This is a proof-of-concept implementation developed for research and CTF purposes. Use at your own risk. Not recommended for production forensic investigations without thorough testing and validation.

A Model Context Protocol (MCP) server for Windows memory forensics. Provides AI agents with 33 tools for analyzing memory dumps using Volatility 3, MemProcFS, and CLR analysis backends.

Author: Jacob Krell

Prerequisites

Before running setup, ensure you have:

Python 3.10+ - Download from python.org
Visual C++ Build Tools - Required for yara-python compilation
- Download Visual C++ Build Tools
- During installation, select "Desktop development with C++" workload
- This is required for YARA scanning functionality

Quick Setup (One Command)

# Clone and setup
git clone https://github.com/0xhackerfren/windows-memory-forensics-mcp.git
cd windows-memory-forensics-mcp
.\setup.ps1

The setup script will:

Create a Python virtual environment
Install all dependencies (Volatility 3, MemProcFS, pefile, yara-python)
Verify the installation
Print configuration instructions for Cursor/Claude

After setup, verify with a memory dump:

python verify_setup.py C:\path\to\memory.raw

AI Agent Usage

For AI agent guidance, see AGENT_RULES.md - this file contains:

Complete tool reference
Investigation workflow patterns
Common analysis patterns
Example commands

You can use AGENT_RULES.md as:

A Cursor rule (copy to .cursor/rules/)
A Claude Desktop system prompt
A reference document

Disclaimer

This software is provided "as-is" for research, education, and CTF purposes.

No warranty or guarantee of accuracy or completeness
Test thoroughly before using on real forensic evidence
Not intended for production use - validate all results independently
The author is not responsible for any damages, data loss, or incorrect conclusions drawn from this tool
Always follow proper chain-of-custody procedures for real forensic investigations

Features

Pluggable Backends: Volatility 3, MemProcFS, cdb.exe, dotnet-dump
Process Analysis: List processes, command lines, DLLs, handles
Malware Detection: malfind, hidden module detection, injection detection
Memory Extraction: VAD dumping (raw and reconstructed), arbitrary memory reads
CLR/.NET Analysis: Deep .NET inspection via SOS commands on minidumps
Staged Payload Reconstruction: Extract and decode payloads from environment variables (PASTALOADER, GrimResource patterns)
Network Forensics: Network connection enumeration

MCP Client Configuration

Cursor IDE

Add to .cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "memory-forensics-mcp": {
      "command": "C:/path/to/windows-memory-forensics-mcp/venv/Scripts/python.exe",
      "args": ["C:/path/to/windows-memory-forensics-mcp/src/memory_forensics_mcp.py"]
    }
  }
}

Important: Use the virtual environment Python (venv/Scripts/python.exe) to ensure dependencies are available.

Restart Cursor to load the MCP.

Claude Desktop / Claude Code

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "memory-forensics-mcp": {
      "command": "C:/path/to/windows-memory-forensics-mcp/venv/Scripts/python.exe",
      "args": ["C:/path/to/windows-memory-forensics-mcp/src/memory_forensics_mcp.py"]
    }
  }
}

Restart Claude Desktop to load the MCP.

Available Tools (33)

Process Analysis

| Tool | Description | |------|-------------| | list_processes | List all processes with PIDs, names, and timestamps | | get_cmdline | Get command line arguments for processes | | list_dlls | List loaded DLLs for a process | | ldrmodules | Compare module lists to detect hidden modules | | handles | List process handles | | handles_enriched | Handles with filtering, summaries, and cross-references |

Memory Extraction

| Tool | Description | |------|-------------| | vadinfo | List Virtual Address Descriptors for a process | | dump_vad | Dump VAD region to file (with PE reconstruction) | | dump_vad_raw | Dump raw VAD bytes without reconstruction | | read_virtual_memory | Read arbitrary virtual memory from a process | | read_physical_memory | Read physical memory at a given address | | memprocfs_get_minidump | Extract WinDbg-compatible minidump |

VFS Browsing (MemProcFS)

| Tool | Description | |------|-------------| | vfs_list | List directory entries in MemProcFS virtual file system | | vfs_read | Read bytes from a file in MemProcFS VFS | | vfs_export | Export a file from MemProcFS VFS to disk |

Malware Detection

| Tool | Description | |------|-------------| | malfind | Find injected or suspicious code | | find_hidden_modules | Find modules not in PEB loader lists | | yara_scan | Scan memory with custom YARA rules |

Network Forensics

| Tool | Description | |------|-------------| | netscan | Scan for network connections | | filescan | Scan for file objects in memory |

Registry Analysis

| Tool | Description | |------|-------------| | list_registry_hives | List registry hives found in memory | | registry_printkey | Print registry key values from memory |

CLR/.NET Analysis

| Tool | Description | |------|-------------| | list_clr_modules | List CLR assemblies with addresses (via SOS) |

Staged Payload Analysis

| Tool | Description | |------|-------------| | get_process_environment | Extract environment variables from PEB | | reconstruct_staged_payload | Reconstruct payload from staged env vars |

Tagging and Timeline (AI Workflow)

| Tool | Description | |------|-------------| | add_tag | Add a tag to track findings across tool calls | | list_tags | List all tags in the session | | clear_tags | Clear all tags | | add_timeline_event | Add an event to the investigation timeline | | list_timeline | List timeline events | | clear_timeline | Clear timeline events |

Utility

| Tool | Description | |------|-------------| | check_installation | Check backend installation status | | list_capabilities | List all available tools | | get_documentation | Get usage documentation |

Usage Examples

Basic Process Analysis

# List all processes
result = list_processes(memory_file="C:/evidence/memory.raw")
for proc in result["results"]:
    print(f"PID {proc['PID']}: {proc['ImageFileName']}")

# Get command line for suspicious process
cmdline = get_cmdline(memory_file="C:/evidence/memory.raw", pid=1234)
print(cmdline["results"])

Detect Hidden/Injected Modules

# Use ldrmodules to find modules with suspicious flags
ldr = ldrmodules(memory_file="memory.raw", pid=3120)
for mod in ldr["results"]:
    if not mod["InLoad"] and not mod["InInit"] and not mod["InMem"]:
        print(f"Hidden module: {mod['Base']} - {mod['MappedPath']}")

# Or use the automated detection
hidden = find_hidden_modules(memory_file="memory.raw", pid=3120)
print(f"Found {hidden['count']} hidden modules")

Detect Staged Payloads (PASTALOADER/GrimResource Pattern)

# Extract environment variables with a specific prefix
env = get_process_environment(
    memory_file="memory.raw",
    pid=3120,
    filter_prefix="B_"  # PASTALOADER uses B_1, B_2, ... B_N
)
print(f"Found {env['filtered_count']} staged payload chunks")

# Reconstruct the payload
payload = reconstruct_staged_payload(
    memory_file="memory.raw",
    pid=3120,
    var_prefix="B_",
    decode_algorithm="pastaloader",
    output_path="./output/reconstructed_payload.bin"
)
print(f"Payload MD5: {payload['md5']}")

Backends

The setup script installs all backends automatically:

| Backend | Purpose | Status | |---------|---------|--------| | Volatility 3 | Classic memory forensics | Installed by setup.ps1 | | MemProcFS | VFS access, minidumps, reliable VA reads | Installed by setup.ps1 | | pefile | PE file parsing | Installed by setup.ps1 | | yara-python | YARA rule scanning | Installed by setup.ps1 (may require Visual C++) |

Optional External Tools

| Tool | Purpose | Install Command | |------|---------|-----------------| | cdb.exe | Deep CLR/SOS analysis | Install Windows SDK Debugging Tools | | dotnet-dump | .NET Core dump analysis | dotnet tool install -g dotnet-dump |

Backend Selection

Most tools support an engine parameter:

# Auto-select best available backend (default)
list_processes(memory_file="memory.raw", engine="auto")

# Force Volatility 3
list_processes(memory_file="memory.raw", engine="volatility")

# Force MemProcFS
list_processes(memory_file="memory.raw", engine="memprocfs")

Troubleshooting

Common Issues

| Issue | Solution | |-------|----------| | "No backend available" | Run .\setup.ps1 to install dependencies | | "mcp module not found" | Use venv Python: venv/Scripts/python.exe | | "Memory file not found" | Use absolute paths to memory files | | "yara-python failed to install" | Install Visual C++ Build Tools, then retry | | "Kernel symbols not found" | Volatility auto-downloads from Microsoft - ensure internet access |

Verify Installation

# Check backends only
python verify_setup.py --check-only

# Full test with memory file
python verify_setup.py C:\path\to\memory.raw

Manual Installation

If setup.ps1 fails, install manually:

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install mcp volatility3 pefile memprocfs

Project Structure

windows-memory-forensics-mcp/
+-- src/
|   +-- memory_forensics_mcp.py  # Main MCP server
+-- examples/
|   +-- basic_analysis.py        # Basic usage examples
|   +-- malware_detection.py     # Malware detection workflow
|   +-- staged_payload.py        # Staged payload reconstruction
|   +-- quickstart.py            # Quick verification script
+-- .cursor/
|   +-- mcp.json.example         # Cursor configuration example
+-- setup.ps1                    # One-command setup script
+-- verify_setup.py              # Installation verification
+-- AGENT_RULES.md               # AI agent usage guide
+-- requirements.txt             # Python dependencies
+-- pyproject.toml               # Package metadata
+-- LICENSE                      # MIT License
+-- README.md                    # This file

Requirements

Windows 10/11
Python 3.10+
PowerShell 5.1+ (for setup.ps1)

All Python dependencies are installed automatically by setup.ps1.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Jacob Krell - Creator and maintainer

Acknowledgments

Volatility Foundation for Volatility 3
Ulf Frisk for MemProcFS
Anthropic for the MCP specification
Hack The Box for the Sherlock challenges that drove development

Related Projects

Volatility 3 - Memory forensics framework
MemProcFS - Memory Process File System
MCP Specification - Model Context Protocol

Proof of Concept - Created from real-world DFIR investigations. Battle-tested on HTB Sherlock challenges including Novitas (Insane difficulty).

Use at your own risk. Always validate forensic findings through multiple methods.