npm package: @modular-intelligence/volatility
Description: MCP server wrapping Volatility 3 for memory forensics analysis
Latest version: 1.0.2

# 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:**
```typescript
{
  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:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "os": "windows",
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}
```

**Example Request:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  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:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  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:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  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:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  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:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "pid": 2840,
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}
```

**Example Request:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}
```

**Example Request:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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:**
```typescript
{
  dump_path: string  // Path to memory dump file (.raw/.dmp/.vmem/.lime/.mem)
  timeout: number    // Timeout in seconds (30-600, default: 300)
}
```

**Example Request:**
```json
{
  "dump_path": "/path/to/memory.dmp",
  "timeout": 300
}
```

**Example Output:**
```json
{
  "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.

```bash
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:
```bash
vol --version
```

### Steps

1. Clone or download this repository:
```bash
git clone <repo-url>
cd volatility
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
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`:

```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):

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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