Mem Forensics

Python 3.10+ License: MIT MCP

A high-performance MCP Server for Memory Forensics that enables AI agents to analyze memory dumps through the Model Context Protocol. Built with two-tier architecture combining Rust speed with Volatility3 coverage.

Credits

This project is based on the excellent work by xtk in mem-forensics-mcp. The Rust engine (memoxide) is a modified version of the original implementation.

Features

• Two-Tier Architecture: Fast Rust engine (memoxide) + Volatility3 fallback for maximum coverage
• Bounded Sessions and Results: Image-fingerprint sessions, LRU cache, TTL-backed pagination, and opaque artifact resources
• Auto-Detection: Automatic OS profile detection and plugin name resolution
• High Performance: Rust native plugins for common operations (3s vs 60s)
• Full Coverage: Access to available Volatility3 plugins through the Volatility3 API
• Smart Routing: Automatically selects fastest available engine
• No Pre-analysis Required: Plugins auto-analyze image if needed

Performance Benchmarks

Tested on Windows crash dump (2GB, ~109 processes):

Operation	Rust (Memoxide)	Volatility3	Speedup
Analyze Image	3s	60s	20x faster
Process List (pslist)	1.5s	15s	10x faster
Network Scan (netscan)	2s	20s	10x faster

Requirements

• Python 3.10+
• Git CLI - used to clone/update the Volatility3 stable branch
• Rust toolchain (optional, for building memoxide from source)
• MCP-compatible client (Claude Desktop, VSCode, Cline, etc.)

Installation

1. Configure Volatility3 Source

Volatility3 prefers a managed or explicitly trusted local Git checkout. A pinned pip package is used only when no valid Git source is available.

Create .env in the project root:

cp .env.example .env

Default .env:

VOLATILITY3_REPO_URL=https://github.com/volatilityfoundation/volatility3
VOLATILITY3_BRANCH=stable
VOLATILITY3_REPO_PATH=.cache/volatility3
VOLATILITY3_UPDATE_MODE=background
VOLATILITY3_PIP_FALLBACK=true
MEMOXIDE_SYMBOLS_ROOT=/absolute/path/to/symbols/windows

2. Install MCP Server

From Source:

git clone https://github.com/jus1-c/mem-forensics-mcp-server.git
cd mem-forensics-mcp-server
pip install -e .

Configuration

Logs are written to mem-forensics-mcp.log in the project/install root, next to .env.

Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mem-forensics": {
      "command": "python",
      "args": ["-m", "mem_forensics_mcp_server"]
    }
  }
}

VSCode (with Cline extension)

Add to your settings:

{
  "mcpServers": {
    "mem-forensics": {
      "command": "python",
      "args": ["-m", "mem_forensics_mcp_server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools

1. memory_analyze_image

Initialize memory image analysis and detect OS profile.

Parameters:

• image_path: Absolute path to memory dump (required)
• os_hint: Optional windows, linux, or mac; use Linux/macOS hints to skip Windows-native profile detection
• dtb: Override DTB address (optional, hex string)
• kernel_base: Override kernel base address (optional, hex string)

Example:

{
  "image_path": "/evidence/memory.raw",
  "dtb": "0x1ad000"
}

2. memory_run_plugin

Run a forensics plugin. Auto-routes to Rust (fast) or Vol3 (fallback).

Parameters:

• image_path: Absolute path to memory dump (required)
• plugin: Plugin name - can be short ("pslist") or full ("windows.pslist.PsList")
• args: List of plugin arguments (optional, e.g., ["--pid", "1234"])
• params: Typed plugin parameter object; use memory_describe_plugin first for requirements
• engine: auto, rust, or vol3
• allow_fallback: Allow Rust-to-Vol3 fallback (default true)
• filter: Server-side filter string (optional)

Important Notes:

• args supports compatibility CLI-style plugin arguments; params is preferred for new integrations
• Output is always JSON-rendered through the Volatility3 API
• -r json is accepted but ignored for backward compatibility
• Short plugin names are auto-resolved to full format

Examples:

// List all processes
{
  "image_path": "/evidence/memory.raw",
  "plugin": "pslist"
}

// Dlllist for specific PID
{
  "image_path": "/evidence/memory.raw",
  "plugin": "dlllist",
  "args": ["--pid", "3692"]
}

// Filescan with filter
{
  "image_path": "/evidence/memory.raw",
  "plugin": "filescan",
  "filter": "svchost"
}

// Using full plugin name
{
  "image_path": "/evidence/memory.raw",
  "plugin": "windows.netscan.NetScan"
}

3. memory_list_plugins

List all available plugins from both engines.

Parameters:

• image_path: Memory dump path (for context)

Returns:

• 9 Rust plugins (fast)
• Vol3 plugins discovered from the managed stable checkout (Windows/Linux/Mac/Other)

4. memory_list_sessions

List all active analysis sessions.

Parameters: None

5. memory_get_status

Get server status and engine availability.

Parameters: None

6. memory_list_dumpable_files

List files found in memory using filescan plugin.

Parameters:

• image_path: Absolute path to memory dump (required)
• args: Optional args like ["--pid", "1234"]

Result pages and artifacts

Large row results return a cursor for memory_get_result_page. Large structured reports and extracted files return an opaque memforensics://artifact/<token> resource link. Read it with the MCP resource API and release it early with memory_release_result; artifacts and result cursors expire automatically.

Native analysis tools

Native Memoxide tools include full triage, process anomalies, injected-code/C2/command analysis, registry hive enumeration and queries, KDBG/RSDS scans, and guarded hash dumping. memory_hashdump requires allow_sensitive: true because it returns credential material.

Curated cross-platform tools

Use these wrappers when an investigation needs a common task rather than a Volatility plugin name. They still execute through the isolated Volatility3 API worker and return the resolved canonical plugin in provenance.

Tool	Windows	Linux	macOS
memory_dump_process_memory	Memmap	Maps	Maps
memory_list_memory_maps	VadInfo	Maps	Maps
memory_list_open_handles	Handles	Lsof	Lsof
memory_list_network_connections	NetScan	Sockstat	Netstat
memory_list_kernel_modules	DriverScan	Lsmod	Lsmod
memory_list_environment	Envars	Envars	Not available
memory_list_security_ids	GetSIDs	Not available	Not available
memory_scan_callbacks	Callbacks	Not available	Not available

memory_extract_files wraps Windows DumpFiles. memory_dump_process_memory enables Volatility's dump option; extracted bytes are returned as managed MCP artifact resources, not host filesystem paths.

Evidence workflow tools

Pass structured results from memory_run_plugin, curated wrappers, or memory_full_triage directly into these tools:

• memory_build_timeline: emits only parseable timestamp evidence in chronological order.
• memory_extract_iocs: extracts conservative IP, URL, hash, PID, port, and domain observables while excluding secret-named fields.
• memory_diff_results: compares two plugin result snapshots using optional identity fields such as pid, offset, or name.
• memory_response_playbook: generates a reviewable preservation, validation, containment, and reporting sequence. It never changes a host.

Usage Examples

Basic Analysis (Auto-detect)

Please analyze this memory dump and list all processes.
File: /evidence/windows.dmp

The server will:

1. Auto-analyze the image
2. Cache the results
3. Return process list

Process Investigation with PID Filter

Get command line for process ID 1234 from this memory dump.
File: /evidence/malware.dmp

{
  "image_path": "/evidence/malware.dmp",
  "plugin": "cmdline",
  "args": ["--pid", "1234"]
}

Network Analysis

Find all network connections in this memory dump.
File: /evidence/c2.dmp

Code Injection Detection

Scan for injected code (malfind) in this memory dump.
File: /evidence/suspicious.dmp

List Files in Memory

List all files found in memory.
File: /evidence/windows.dmp

Caching System

The server includes an intelligent caching system:

• Cache Key: Image fingerprint, plugin, engine, arguments, and typed parameters
• Invalidation: Cache is invalidated when an image changes or its session closes
• LRU Eviction: Oldest entries removed when cache is full

Benefits:

• Second query for same plugin returns instantly
• Separate cache per memory dump file

Security Features

• Path Validation: Only absolute paths allowed
• Engine Isolation: Rust plugins run in separate subprocess
• Artifact Isolation: Generated files are served only through server-managed opaque resource URIs
• Timeout Protection: 60s timeout for Rust engine calls
• Size Limits: Configurable response size limits
• No Secrets: No logging of sensitive memory contents

.env Variables

Variable	Description	Default
VOLATILITY3_REPO_URL	Volatility3 git repository URL	https://github.com/volatilityfoundation/volatility3
VOLATILITY3_BRANCH	Volatility3 branch to use	stable
VOLATILITY3_REPO_PATH	Local checkout path, relative to project root if not absolute	.cache/volatility3
VOLATILITY3_UPDATE_MODE	Git update mode; updates run after MCP startup	background
VOLATILITY3_PIP_FALLBACK	Permit pinned pip fallback when no Git source is valid	true
VOLATILITY3_LOCAL_REPOS	Explicit trusted local Git checkouts; comma/semicolon separated	Empty
MEMOXIDE_SYMBOLS_ROOT	Absolute local Windows ISF symbol store forwarded to Memoxide	symbols/windows

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   MCP Client    │────▶│  MCP Server      │────▶│  Memoxide   │
│ (Claude/VSCode) │     │  (Python/FastMCP)│     │   (Rust)    │
└─────────────────┘     └──────────────────┘     └─────────────┘
                               │                           │
                               │                    ┌──────┴──────┐
                               │                    │ Memory Dump │
                               │                    └─────────────┘
                               ▼
                        ┌─────────────┐     ┌─────────────┐
                         │  LRU Cache  │────▶│  Volatility3│
                         │             │     │ API Fallback│
                        └─────────────┘     └─────────────┘

Project Structure

mem-forensics-mcp-server/
├── mem_forensics_mcp_server/
│   ├── __init__.py
│   ├── __main__.py              # Entry point
│   ├── server.py                # MCP server with tools
│   ├── config.py                # Configuration
│   ├── core/
│   │   ├── session.py           # Session management
│   │   ├── cache.py             # Plugin result caching
│   │   ├── settings.py          # .env settings loader
│   │   ├── vol3_provider.py     # Managed/trusted Volatility3 source selection
│   │   ├── vol3_worker.py       # Isolated Vol3 Python API worker
│   │   ├── results.py           # Pagination and artifact lifecycle
│   │   └── jobs.py              # Background job lifecycle
│   ├── engine/
│   │   ├── memoxide_client.py   # Rust engine client
│   │   └── memoxide/            # Prebuilt binaries
│   │       ├── x86_64/
│   │       └── aarch64/
│   └── utils/
│       └── helpers.py
├── pyproject.toml
├── .env.example
├── README.md
└── .gitignore

Development

Setup Development Environment

pip install -e ".[dev]"

Building Rust Engine

cd mem_forensics_mcp_server/engine/memoxide-src
cargo build --release

Troubleshooting

Memoxide not available

Memoxide requires platform-specific binaries. This package currently includes:

• Windows x86_64
• Linux x86_64
• Linux aarch64

macOS uses Volatility3 unless a matching Memoxide binary is built and installed. The GitHub Actions native job builds a macOS binary for the current macos-latest runner architecture, stages it as memoxide.macos, builds a wheel, and uploads the wheel and raw binary as workflow artifacts.

To build for other platforms:

cd mem_forensics_mcp_server/engine/memoxide-src
cargo build --release --target <target-triple>

After building, place the executable under mem_forensics_mcp_server/engine/memoxide/<architecture>/ using these names:

• Linux: memoxide
• Windows: memoxide.exe
• macOS: memoxide.macos

Run the CI workflow manually with Run workflow to produce platform build artifacts without requiring a local cross-compilation toolchain. The workflow does not commit generated binaries; download the matching wheel or binary from the workflow run. Platforms without a matching native binary continue using the Volatility3 fallback.

Vol3 plugin requirements not met

Some memory dump formats may not be compatible with certain plugins. Error message will indicate:

• Translation layer issues (unsupported format)
• Symbol table issues (missing ISF files)

Timeout errors on large dumps

Rust engine has 60s timeout. For very large dumps, Vol3 fallback will be used automatically.

Plugin argument errors

This means the arguments passed do not match the plugin's Volatility3 requirements. Use memory_describe_plugin for typed requirements or call memory_list_plugins to verify the resolved plugin name.

Recent Updates

v0.2.0

• Added isolated Volatility3 API workers with background Git source refresh and pinned pip fallback
• Added typed plugin discovery, pagination, background jobs, YARA scanning, native registry tools, and sensitive hashdump gate
• Added server-managed MCP artifact resources, session cleanup, bounded symbol fallback, and explicit incomplete-triage reporting
• Added Python/Rust CI checks, platform-native Memoxide builds, and wheel packaging audit

License

MIT License - see LICENSE file for details.

Acknowledgments

• xtk - Original author of mem-forensics-mcp and the memoxide Rust engine
• Volatility3 - Memory forensics framework
• Model Context Protocol - MCP specification
• FastMCP - Python MCP SDK

Support

For issues and feature requests, please use the GitHub issue tracker.