# pwndbg-mcp

通过标准 HTTP MCP 协议让 AI Agent 控制 pwndbg，支持 Agent 全自动无界面调试和用户终端协作调试。

## 架构

```text
Agent ── MCP/HTTP ──> Gateway :22334
                           ├── managed/headless pwndbg ──> 127.0.0.1:动态端口
                           └── attached/collaborative pwndbg ──> 127.0.0.1:动态端口
```

- Gateway 是始终运行、对 Agent 暴露全部工具的 MCP Server。
- `debug_session_start` 自动启动的 managed session 固定为 headless。
- 用户手动启动的 pwndbg 自动注册为 attached/collaborative session，保留完整 context、命令回显和人工输入能力。
- pwndbg 插件仅作为内部后端，使用回环动态端口；managed 后端使用独立随机 Bearer token。
- 全部 `gdb_*` 工具作用于 Gateway 默认会话，无需传递 `session_id`。

## 要求

- Python 3.10+
- PATH 中存在独立的 `pwndbg` 启动器
- Linux；自动服务安装需要 systemd user service

项目不会通过系统 `/usr/bin/gdb` 检测 pwndbg，因为独立安装的 pwndbg 带有自己的 GDB 和 Python 运行环境。

## 安装

运行交互式设置，将插件 loader 加入 `~/.gdbinit`：

```bash
python3 setup.py
```

也可以手动添加：

```gdb
source /absolute/path/to/pwndbg-mcp/pwndbg_mcp.py
```

### 安装并启动 Gateway 服务

仅本机访问：

```bash
python3 setup.py --install-service
```

允许远程客户端连接：

```bash
python3 setup.py --install-service --gateway-host 0.0.0.0 --gateway-port 22334
```

安装脚本会生成 `~/.config/systemd/user/pwndbg-mcp-gateway.service`，校验 unit，执行 `daemon-reload`、`enable` 和 `restart`，最后确认服务为 active。重复执行会立即应用新的 host、port、Python 路径和项目路径。

服务管理：

```bash
systemctl --user status pwndbg-mcp-gateway
systemctl --user restart pwndbg-mcp-gateway
journalctl --user -u pwndbg-mcp-gateway -f
```

不使用 systemd 时可以前台启动：

```bash
python3 -m gateway.server --host 127.0.0.1 --port 22334
```

## MCP 客户端配置

本机客户端：

```json
{
  "mcpServers": {
    "pwndbg-mcp": {
      "url": "http://127.0.0.1:22334/mcp"
    }
  }
}
```

远程客户端应将 `127.0.0.1` 替换为 Gateway 主机的实际 IP。

## 使用方式

### Agent 全自动调试

创建 managed/headless session：

```json
{
  "name": "debug_session_start",
  "arguments": {
    "program": "/absolute/path/to/program",
    "cwd": "/optional/working/directory",
    "environment": {
      "LD_LIBRARY_PATH": "/optional/library/path"
    }
  }
}
```

`debug_session_start` 不接受 mode；Gateway 启动的会话永远为 headless。创建成功后自动成为默认会话，后续直接调用 `gdb_run`、`gdb_read_output`、`gdb_write_input` 等工具。

### 用户协作调试

```bash
pwndbg ./program
```

插件会启动回环后端并向 Gateway 注册 attached/collaborative session。Gateway 暂时不可用时会自动重试。Agent 操作会在用户终端显示为正常 pwndbg 命令：

```text
pwndbg> break main
Breakpoint 1 ...
pwndbg> run
Starting program: ...
...
[ REGISTERS ] [ DISASM ] [ STACK ] [ BACKTRACE ]
pwndbg>
```

命令回显只写入控制台，不进入 inferior stdin，不会被 `read`、`fgets`、`gets` 或 `scanf` 读取。

### 多会话与默认会话

```text
debug_session_list    列出会话及 default_session_id
debug_session_select  切换默认会话
debug_session_get     查看指定会话
debug_session_stop    停止 managed session 或分离 attached session
```

managed session 创建后自动成为默认。新 attached session 仅在当前没有默认会话时成为默认。默认会话退出或断开后，Gateway 自动选择剩余最新的 ready session。

## 调试工具

| 类别 | 工具 |
|---|---|
| 运行控制 | `gdb_run`, `gdb_start`, `gdb_continue`, `gdb_interrupt`, `gdb_kill` |
| 单步控制 | `gdb_step`, `gdb_stepi`, `gdb_next`, `gdb_nexti`, `gdb_finish`, `gdb_until` |
| execution | `gdb_get_execution`, `gdb_wait`, `gdb_get_events` |
| 输入输出 | `gdb_read_output`, `gdb_write_input` |
| 状态查询 | `gdb_get_state`, `gdb_get_info`, `gdb_get_registers`, `gdb_get_backtrace` |
| 数据访问 | `gdb_get_memory`, `gdb_evaluate`, `gdb_disassemble` |
| 断点 | `gdb_set_breakpoint`, `gdb_set_breakpoints`, `gdb_delete_breakpoint`, `gdb_delete_breakpoints`, `gdb_get_breakpoints` |
| 高级查询 | `gdb_execute`（拒绝运行控制命令） |

批量断点支持普通、地址、临时、硬件、条件和禁用断点，并可在失败时回滚。裸十六进制地址会自动转换为 GDB 的 `*0x...` 地址语法。

运行工具返回 `execution_id`。Agent 可使用游标增量读取带 stream 类型的输出；每个 execution 最多保留 8 MiB，并在旧 cursor 失效时返回 `cursor_expired`。

## 插件内管理命令

```text
mcp-status                    查看后端地址、模式和当前 execution
mcp-mode collaborative       切换到终端协作输出
mcp-mode headless            切换到无界面输出（inferior 运行时禁止切换）
mcp-stop                     停止当前 pwndbg 内部后端
```

通常不需要手动改变插件后端地址；Gateway 使用动态端口完成注册和路由。

## 安全

- 插件后端只监听 `127.0.0.1`。
- Gateway `/internal/register` 只接受回环连接。
- managed 后端使用每会话随机 token。
- Gateway 当前未实现客户端认证。监听 `0.0.0.0` 时必须使用防火墙、可信网络或反向代理认证限制 22334 端口。

## 故障排查

检查 Gateway：

```bash
systemctl --user status pwndbg-mcp-gateway
journalctl --user -u pwndbg-mcp-gateway -n 100 --no-pager
ss -ltnp 'sport = :22334'
```

检查 MCP 初始化：

```bash
curl -X POST http://127.0.0.1:22334/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
```

检查手动 pwndbg 后端：

```text
pwndbg> mcp-status
```

## 开发与测试

共享工具 schema 位于 `pwndbg_plugin/tool_schema.py`；Gateway 在 schema 上增加会话管理工具，插件负责 GDB 主线程内的实际执行。

```bash
python3 -m unittest discover -s tests -v
python3 -m compileall -q gateway pwndbg_plugin tests
```

示例程序包含 stdin 读取路径，用于验证 headless PTY：

```bash
cd examples
./compile.sh
pwndbg ./test_program
```

## License

MIT