Content
# PWN-MCP
AI-assisted debugging platform for CTF Pwn challenges. Based on the Model Context Protocol (MCP) protocol, allowing AI models to directly operate GDB on remote targets, interact with CTF services, analyze heap states, and achieve automated heap exploitation.
## Architecture
```
AI (MCP Client) ──stdio──▶ PWN-MCP Server ──SSH──▶ Remote Target
│ ├─ GDB + heap_logger.py
│ ├─ CTF binary (socat)
│ └─ /tmp/heap_*.json
└── Local IDA headless
```
## Installation
```bash
pip install -e .
```
Dependencies: `mcp`, `paramiko`
## Running
```bash
# Any of the following methods can be used
ctf-debugger
python -m src
python src/server.py
```
### MCP Client Configuration
```json
{
"mcpServers": {
"ctf-debugger": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/PWN-MCP"
}
}
}
```
## Module Overview
| Module | File | Responsibility |
|------|------|------|
| **MCP Server** | `src/server.py` | FastMCP entry point, registers all tool groups, stdio transport |
| **SSH Manager** | `src/ssh_manager.py` | Singleton SSH connection management (paramiko), provides exec/upload/download |
| **GDB Controller** | `src/gdb_controller.py` | Singleton GDB session control, operates remote GDB through SSH PTY Channel |
| **CTF Connector** | `src/ctf_connector.py` | Singleton CTF service connection, SSH direct-tcpip port forwarding, pwntools-style interface |
| **Heap Analyzer** | `src/heap_analyzer.py` | Parses heap_logger-produced JSON (delta/snapshot), filters and formats |
| **GDB Plugin** | `remote_scripts/heap_logger.py` | GDB Python plugin uploaded to target machine, hooks malloc/calloc/realloc/free |
## MCP Tools
### SSH Tool Group (`src/tools/ssh_tools.py`)
| Tool | Description |
|------|------|
| `ssh_connect` | Establishes SSH connection (key/password authentication) |
| `ssh_exec` | Executes shell commands remotely |
| `ssh_upload_file` | Uploads files via SFTP |
| `ssh_download_file` | Downloads file contents via SFTP |
| `ssh_disconnect` | Disconnects SSH connection |
### GDB Tool Group (`src/tools/gdb_tools.py`)
| Tool | Description |
|------|------|
| `gdb_start` | Starts GDB session, loads heap_logger.py plugin |
| `gdb_run` | Runs target program |
| `gdb_continue` | Continues execution (foreground) |
| `gdb_continue_background` | Continues execution in background, used for granular collection |
| `gdb_interrupt` | Interrupts program with Ctrl-C |
| `gdb_pause` | Pauses program (prioritizes GDB `interrupt` command, compatible with background continue) |
| `gdb_restart` | Restarts program (kill + run) |
| `gdb_stop` | Exits GDB session |
| `gdb_command` | Executes arbitrary GDB/pwndbg/gef commands |
| `gdb_memory` | Dumps memory (bytes + words dual view, supports GDB expressions) |
| `gdb_chunk` | Displays glibc malloc chunk header (prev_size/size + pwndbg malloc_chunk) |
| `gdb_source_window` | Displays overflow window memory around source chunk |
| `gdb_read_output` | Reads GDB output buffer (does not wait for prompt) |
### Heap Analysis Tool Group (`src/tools/heap_tools.py`)
**Request Granularity Tracking**
| Tool | Description |
|------|------|
| `heap_begin_action` | Marks beginning of heap operation stage |
| `heap_end_action` | Ends stage, returns incremental delta (supports caller/address/type filtering) |
| `heap_snapshot` | Obtains complete heap state snapshot (all active chunks) |
| `heap_get_state` | Quickly views heap statistics overview |
| `heap_query_delta` | Performs secondary query filtering on recent delta |
| `heap_query_log` | Queries complete text log heaplog.txt |
**Bin and Chunk Tracking**
| Tool | Description |
|------|------|
| `heap_bins_json` | Exports glibc bin state JSON (fastbins/unsorted/smallbins/largebins) |
| `heap_find_chunk` | Finds chunk in which bin |
| `heap_chunk_bin` | Returns chunk's bin description |
| `track_chunk` | Begins tracking chunk lifecycle (header/bin/memory diff) |
| `untrack_chunk` | Stops tracking chunk |
| `tracked_chunks_status` | Displays tracked chunk status |
**Request-level Timeline**
| Tool | Description |
|------|------|
| `begin_request` | Begins heap timeline at network request granularity |
| `end_request` | Ends request timeline |
| `request_timeline` | Reads request-level heap timeline |
| `request_events` | Queries heap events within request by label |
**Advanced Capabilities**
| Tool | Description |
|------|------|
| `add_probe` / `remove_probe` / `list_probes` | Conditional breakpoints + automatic sampling probe |
| `mem_snapshot` | Saves memory snapshot |
| `mem_diff` | Compares two memory snapshots (offset/old/new/u32/ascii) |
| `run_heap_sweep` | Payload sweep automation framework (batch tests configuration, terminates by stop condition) |
### CTF Interaction Tool Group (`src/tools/ctf_tools.py`)
| Tool | Description |
|------|------|
| `ctf_connect` | Connects to CTF service via SSH port forwarding (automatically receives banner) |
| `ctf_send` | Sends data (supports hex mode sending raw bytes) |
| `ctf_sendline` | Sends line of text (automatically appends newline) |
| `ctf_recv` | Receives response data |
| `ctf_recv_until` | Receives until specified pattern |
| `ctf_close` | Closes CTF connection |
| `ctf_menu_action` | Composite tool: automatically completes menu-driven interaction (select menu → wait for prompt → fill value) |
### IDA Static Analysis Tool Group (`src/tools/ida_tools.py`)
| Tool | Description |
|------|------|
| `ida_headless_scan` | Calls local IDA headless to analyze ELF, outputs JSON scan results |
| `ida_find_functions` | Searches functions in scan results by regex/substring |
| `ida_get_pseudocode` | Retrieves function decompiled pseudocode |
| `ida_get_xrefs` | Retrieves function cross-references (xrefs_to / calls_from) |
## Project Structure
```
PWN-MCP/
├── pyproject.toml # Project configuration and dependencies
├── README.md
├── src/
│ ├── __init__.py
│ ├── __main__.py # python -m src entry point
│ ├── server.py # MCP Server entry point, registers all tools
│ ├── ssh_manager.py # SSH connection manager (singleton)
│ ├── gdb_controller.py # GDB session controller (singleton, PTY Channel)
│ ├── ctf_connector.py # CTF service connector (singleton, port forwarding)
│ ├── heap_analyzer.py # Heap log JSON parsing and formatting
│ └── tools/
│ ├── __init__.py
│ ├── ssh_tools.py # SSH tool group (5 tools)
│ ├── gdb_tools.py # GDB tool group (13 tools)
│ ├── heap_tools.py # Heap tool group (20 tools)
│ ├── ctf_tools.py # CTF tool group (7 tools)
│ └── ida_tools.py # IDA tool group (4 tools)
├── remote_scripts/
│ └── heap_logger.py # GDB Python plugin (uploaded to target machine)
├── scripts/
│ └── verify_mcp_heap_debug.py
├── skills/
│ └── ctf-heap-spray.md # AI Skill: heap spray automation workflow
└── docs/
└── mcp_heap_debug_capabilities.md
```
## Typical Workflow
```
ssh_connect → ssh_upload_file(heap_logger.py)
→ gdb_start(binary, plugin) → gdb_command("set disable-randomization on") → gdb_run
→ ctf_connect(127.0.0.1, port)
→ Iterative loop:
heap_begin_action("spray")
→ gdb_continue → ctf_menu_action("1", [...]) → gdb_interrupt
→ heap_end_action() # Analyze delta
→ heap_snapshot() # Critical step to verify layout
→ Send exploit payload
```
## GDB Plugin (heap_logger.py)
Uploaded to target machine and loaded with `gdb -x heap_logger.py`. Features:
- x86_64 / i386 ABI-aware parameter and return value extraction
- Hooks malloc / calloc / realloc / free (raw + pending libc breakpoints)
- User pointer → chunk header conversion, chunk size field reading
- Caller analysis to main program call point
- Action-scoped delta JSON (`/tmp/heap_delta.json`) and full snapshot JSON (`/tmp/heap_snapshot.json`)
- Custom GDB commands: `heap-begin`, `heap-end`, `heap-snapshot`, `heap-status`, `heap-bins-json`, `heap-find-chunk`, `track-chunk`, `add-probe-json`, etc.
## Technology Stack
- **MCP SDK** — MCP protocol support (FastMCP + stdio transport)
- **Paramiko** — SSH2 protocol (connection, SFTP, PTY Channel, port forwarding)
- **asyncio** — Asynchronous runtime, bridges synchronous calls with `asyncio.to_thread`
- **IDA Pro** — Headless mode static analysis (optional)
