<p align="center">
<img src="assets/logo.png" height="300">
</p>
<h1 align="center">Volatility MCP</h1>
<p align="center"><em>Your AI Assistant in Memory Forensics</em></p>

MCP-сервер, который оборачивает **Volatility 3** и позволяет LLM-ассистенту
(opencode / Claude Desktop и др.) проводить memory forensics на естественном
языке: «покажи процессы», «найди инъекцию», «есть ли C2-соединения».

Форк [Gaffx/volatility-mcp](https://github.com/Gaffx/volatility-mcp) (Apache 2.0)
с доработками под курс SOC: **single-process** запуск (без FastAPI-слоя),
**OS-aware** плагины (Windows/Linux/macOS с автоопределением), расширенный набор
инструментов и извлечение шеллкода из памяти.

---

## Architecture

```
MCP client (opencode)  ──stdio──▶  vol_mcp_server.py  ──subprocess──▶  vol -q -f <dump> <plugin>
    естественный язык               (FastMCP, single-process)              Volatility 3
```

`vol_mcp_server.py` — самодостаточный MCP-сервер: он **напрямую** вызывает
бинарник `vol` через `subprocess` (никакого HTTP/FastAPI-бэкенда не требуется).

Опционально остаётся REST-режим (как в оригинале): `volatility_fastapi_server.py`
поднимает FastAPI-бэкенд, эндпоинты `/plugins`, `/analyze/{plugin}`.

## Features

- **Single-process** MCP-сервер (без FastAPI-зависимости).
- **OS-aware**: `--os auto|windows|linux|mac`, по умолчанию определяется по образу.
- **12 именованных инструментов** + `extract_vad` + generic `run_plugin`.
- **`format="json"`** — машиночитаемый вывод (JSON-рендерер Volatility).
- **extract_vad** — дамп региона памяти (шеллкод) на диск + SHA256 + hex-превью.
- **Lazy validation** — сервер стартует без образа (для CI/универсального деплоя).

## Tools

| Tool | Windows | Linux | macOS | Что даёт |
|---|---|---|---|---|
| `get_info` | `windows.info.Info` | `banners.Banners` | `banners.Banners` | идентификация образа (OS build, DTB, SystemTime) |
| `get_processes` | `windows.pslist.PsList` | `linux.pslist.PsList` | `mac.pslist.PsList` | список процессов |
| `get_pstree` | `windows.pstree.PsTree` | `linux.pstree.PsTree` | `mac.pstree.PsTree` | дерево процессов |
| `get_psscan` | `windows.psscan.PsScan` | `linux.psscan.PsScan` | — | скрытые/завершённые процессы (DKOM) |
| `get_malfind` | `windows.malware.malfind.Malfind` | `linux.malware.malfind.Malfind` | `mac.malfind.Malfind` | **инжектированный код** (RWX VAD) |
| `get_vadinfo(pid)` | `windows.vadinfo.VadInfo` | — | — | VAD-узлы (`File=N/A` ⇒ инъекция) |
| `get_dlllist(pid)` | `windows.dlllist.DllList` | `linux.elfs.Elfs` | — | DLL/ELF (шеллкод vs DLL-injection) |
| `get_connections` | `windows.netscan.NetScan` | `linux.sockstat.Sockstat` | `mac.netstat.Netstat` | сетевые соединения (C2) |
| `get_cmdline` | `windows.cmdline.CmdLine` | — | — | командные строки |
| `get_handles(pid)` | `windows.handles.Handles` | `linux.lsof.Lsof` | `mac.lsof.Lsof` | открытые хэндлы/fd |
| `get_envars(pid)` | `windows.envars.Envars` | — | — | переменные окружения (LD_PRELOAD и т.п.) |
| `get_filescan` | `windows.filescan.FileScan` | `linux.lsof.Lsof` | — | открытые/маппленные файлы |
| `extract_vad(pid, address)` | дамп VAD + SHA256 + hex | — | — | извлечение шеллкода |
| `run_plugin(plugin, args)` | любой плагин | любой | любой | generic-пасстор |

## Installation

```bash
git clone <this-repo> && cd volatility-mcp
./setup.sh          # создаст .venv и поставит зависимости
# или вручную: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```

## Usage

### CLI (проверка)

```bash
export VOLATILITY_BIN=$PWD/.venv/bin/vol
python vol_mcp_server.py -i /path/to/mem.raw                 # авто-OS
python vol_mcp_server.py -i /path/to/mem.raw --os linux      # принудительно Linux
```

### opencode (или другой MCP-клиент)

`~/.config/opencode/opencode.jsonc` (или `opencode.json` проекта):

```jsonc
{
  "mcp": {
    "vol": {
      "type": "local",
      "command": ["/path/to/run_vol_mcp.sh", "-i", "/path/to/mem.raw"],
      "enabled": true
    }
  }
}
```

`run_vol_mcp.sh` — тонкий лаунчер: задаёт `VOLATILITY_BIN`/символы и запускает
`vol_mcp_server.py`. После правки конфига перезапустите opencode.

### Пример диалога

```
> покажи процессы в дампе, что подозрительного?
  → get_processes: spoolsv.exe PID 2476 + win32calc.exe PID 2768

> найди инжектированный код
  → get_malfind: spoolsv.exe 0x234f27a0000 PAGE_EXECUTE_READWRITE VadS N/A

> извлеки шеллкод из этого региона
  → extract_vad(pid=2476, address=0x234f27a0000, size=276)
     sha256[276] = cdfc6f54…  hex[276] = fc4883e4f0…

> есть ли C2-соединения?
  → get_connections: только RPC spooler (49677), внешних нет
```

## Optional — FastAPI/REST backend

```bash
export VOLATILITY_BIN=$PWD/.venv/bin/vol
.venv/bin/uvicorn volatility_fastapi_server:app --host 127.0.0.1 --port 8000
# GET /plugins
# GET /analyze/malfind?image_path=/path/mem.raw
# GET /analyze/vadinfo?image_path=/path/mem.raw&args=--pid 2476
```

## Security

- Дампы памяти содержат чувствительные данные — слушать только на `127.0.0.1`,
  не открывать наружу.
- `run_vol_mcp.sh` и FastAPI привязываются к loopback по умолчанию.

## Development

```bash
pip install -r requirements.txt
# Smoke-тест (то же, что в CI): .github/workflows/ci.yml
```

## License

Apache 2.0 — унаследовано от [Gaffx/volatility-mcp](https://github.com/Gaffx/volatility-mcp).