gdb-mcp

面向二进制安全研究(逆向工程 / PWN)的 GDB MCP 服务器,对 pwndbg 插件的额外功能做了一等公民适配:堆分析、cyclic 模式、checksec、ROP gadget、内存映射、telescope 等。

架构

MCP 客户端 (Kimi Code / Claude Desktop,可运行在 Windows)
   │  stdio(可经 wsl.exe / ssh 桥接)
   ▼
gdb-mcp 服务器(Python,运行在带 gdb+pwndbg 的 Linux/WSL 主机)
   │  pygdbmi(GDB/MI 机器接口)
   ▼
gdb --interpreter=mi2(pwndbg 经 ~/.gdbinit 自动加载)

• 断点、栈帧、寄存器、内存读写等走 GDB/MI,返回结构化 JSON;
• pwndbg 命令经 interpreter-exec console 透传执行,输出统一剥 ANSI 转义、截断后返回文本;
• 未封装的任意 gdb/pwndbg 命令都可经 gdb_command 逃生舱执行。

环境要求

服务器端(调试主机)需要:

• Linux(pwndbg 仅支持 Linux;WSL2 亦可)
• gdb、gcc(仅测试需要)
• pwndbg(已执行过 setup.sh,即 ~/.gdbinit 会加载它)
• Python ≥ 3.10

安装(以 WSL2 kali 为例)

# 在 WSL 内执行;项目目录可放在 Windows 侧,经 /mnt/c 访问
uv venv ~/venv/gdb-mcp
uv pip install --python ~/venv/gdb-mcp/bin/python -e '/mnt/c/Users/<你>/Desktop/Develop/gdb-mcp[dev]'

# 或不用 uv:
python3 -m venv ~/venv/gdb-mcp
~/venv/gdb-mcp/bin/pip install -e '/mnt/c/Users/<你>/Desktop/Develop/gdb-mcp[dev]'

若 pwndbg 不在默认位置,可用环境变量 GDB_MCP_PWNDBG_INIT 指向其 gdbinit.py。

MCP 客户端配置

Kimi Code(Windows 客户端 → WSL 内服务器)

编辑 ~/.kimi-code/mcp.json(用户级)或项目级 .kimi-code/mcp.json:

{
  "mcpServers": {
    "gdb": {
      "command": "wsl.exe",
      "args": ["-d", "kali-linux", "-e", "/root/venv/gdb-mcp/bin/python", "-m", "gdb_mcp"],
      "startupTimeoutMs": 60000
    }
  }
}

在 TUI 里也可用 /mcp-config 交互式添加,/mcp 查看连接状态。

Claude Desktop

claude_desktop_config.json 中同样加上上面的 gdb 条目(同一 JSON 结构)。

原生 Linux(客户端与调试同机)

{
  "mcpServers": {
    "gdb": {
      "command": "/root/venv/gdb-mcp/bin/python",
      "args": ["-m", "gdb_mcp"]
    }
  }
}

配合 pwntools 调试(替代 gdb.attach)

先区分两个容易混淆的概念:

• pwntools 的 gdb.attach(p):由 pwntools 拉起的独立 GDB 进程,与本 MCP 服务器无关;
• 本服务器的 gdb_attach:MCP 内部 GDB 会话对目标进程做 ptrace attach。

同一进程只允许一个 ptrace tracer,二者不能对同一进程同时使用。要让 AI 调试 pwntools 脚本拉起的进程,推荐脚本打印 PID 并暂停,由本服务器 attach:

from pwn import *

p = process('./vuln')
log.info(f'target pid: {p.pid}')
pause()          # 等待调试器 attach + 下好断点;回车后继续发送 payload
p.sendline(payload)
p.interactive()

AI 侧对话流程:

1. gdb_attach(target="./vuln", wait=30) —— 按进程名 attach;脚本还没拉起进程时会等待其出现。也可先 gdb_find_process("./vuln") 找到 PID,再 gdb_attach(target="<pid>")。
2. gdb_breakpoint_set(location="vuln") 等下断。
3. gdb_continue() —— 目标通常正阻塞在 read() 等待输入,continue 让它回到等待状态。
4. 回到 pwntools 脚本按回车发出 payload,断点命中,随后用 pwndbg_context、pwndbg_telescope、pwndbg_heap 等分析。

注意事项:

• 不要对同一进程同时使用 pwntools 的 gdb.attach() 和本服务器 —— 只能有一个 tracer。
• gdb_quit 对 attach 的进程是 detach 而非 kill,进程继续运行,pwntools 脚本恢复控制。
• attach 非子进程受 kernel.yama.ptrace_scope 限制:非 root 且值为 1 时会被拒绝,工具会返回修复提示(echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope)。
• pwntools 脚本必须和本 MCP 服务器跑在同一个 WSL 发行版(共享 /proc);gdb_find_process 找不到进程,通常是进程已退出(僵尸进程 cmdline 为空,会按 comm 匹配并标记 zombie)或跨了发行版/容器。
• 想从程序起点开始调试:改用 gdbserver :1234 ./vuln 起目标,然后 gdb_start(mode="remote", target="localhost:1234", file="./vuln")。

交互式程序(stdin/stdout 对话)

菜单式 CTF 题的典型痛点:程序跑起来后阻塞在 read() 等输入。gdb_start 默认给 inferior 分配一个 pty(pty=true,仅 local 模式),配合两个工具完成对话:

1. gdb_run(timeout=10) —— 程序显示菜单后阻塞,工具返回 "still running" 属正常。
2. gdb_recv() —— 读出菜单文本/提示符。
3. gdb_send_stdin(data="1") —— 发送菜单选项(自动补换行;二进制 payload 用 hex=true,如 data="41424300")。
4. 重复 2-3 推进到漏洞点;若已下断点,gdb_continue 会在命中时返回停止信息。
5. 卡死时 gdb_interrupt() 中断(MI 中断 + SIGINT 兜底)。

pty 同时解决了 stdin 重定向导致的 stdio 全缓冲问题(程序以为自己在终端里跑)。attach/remote 模式没有 pty —— 那时 stdin 归拉起进程的一方(pwntools 脚本)所有。

gdb_recv 直接读 inferior 的 pty,输出只有程序自己的文本,不会混入 pwndbg context 或 GDB 日志。gdb_run/gdb_continue 结果里附带的 context 可用 with_context=false 关闭;pwndbg 每次停止时的自动 context 显示可用 gdb_command("set context-output /dev/null") 彻底静音。

环境变量

变量	默认	说明
GDB_MCP_GDB	gdb	GDB 可执行文件路径
GDB_MCP_GDB_ARGS	空	追加给 GDB 的额外参数(shlex 解析)
GDB_MCP_PWNDBG_INIT	~/pwndbg/gdbinit.py	pwndbg 未自动加载时显式 source 的初始化脚本
GDB_MCP_MAX_OUTPUT	20000	单次工具调用返回的最大字符数

工具清单(39 个)

会话与执行控制

工具	说明
gdb_start	启动会话:file(相对路径按 cwd 解析,缺失即报错)、args、mode=local/attach/remote、cwd(默认取二进制所在目录)、env、pty、starti(local 模式:加载后立即运行并停在入口指令,方便解析 PIE 基址)
gdb_attach	attach 已运行进程:按 PID 或进程名,wait 为轮询等待(每 0.5s 扫一次进程表直到出现或超时,pwntools 场景)
gdb_find_process	按 cmdline/exe/comm 子串查找进程,返回 PID 列表(标记僵尸)
gdb_quit / gdb_status	结束会话(attach 的进程会被 detach)/ 查询状态(含 inferior pid)
gdb_send_stdin / gdb_recv	经 pty 向 inferior 发输入 / 读输出(菜单式交互,支持 hex payload;gdb_recv 只含程序自身输出)
gdb_run gdb_continue gdb_step gdb_next gdb_stepi gdb_nexti gdb_finish gdb_until	执行控制;返回停止原因+位置,并附 pwndbg context(可用 with_context=false 关闭)
gdb_interrupt	中断运行中的目标(MI 中断 + SIGINT 兜底)
gdb_breakpoint_set / gdb_breakpoint_delete / gdb_breakpoint_list	断点管理(条件/临时/硬件)
gdb_breakpoint_pie	按 PIE 偏移下断(base+offset,offset 为 IDA/Ghidra/readelf 里的静态 vaddr;程序未运行时自动 starti 解析基址)
gdb_watchpoint_set	读写/访问观察点

检查与修改

工具	说明
gdb_backtrace	结构化栈回溯(JSON)
gdb_registers	寄存器值(JSON,可过滤)
gdb_read_memory / gdb_write_memory	内存读写(hex)
gdb_disassemble	反汇编(x/i)
gdb_eval	表达式求值 / 调用 inferior 函数
gdb_command	任意 gdb/pwndbg console 命令透传(逃生舱)

pwndbg 封装

工具	对应命令
pwndbg_context	context [sections]
pwndbg_checksec	checksec(NX/PIE/Canary/RELRO)
pwndbg_vmmap	vmmap [filter]
pwndbg_telescope	telescope <addr> <count>(指针解引用+映射标注)
pwndbg_heap	bins/chunk <addr>/arena/tcachebins/vis_heap_chunks 等堆分析子命令
pwndbg_search	search [options] <value>
pwndbg_cyclic / pwndbg_cyclic_lookup	cyclic <n> / cyclic -l <val>(溢出模式生成与偏移定位)
pwndbg_rop	rop [--grep <regex>]
pwndbg_nearpc	nearpc [args]
pwndbg_leakfind	leakfind(指针链泄漏搜索)

其余 pwndbg 功能(got、plt、canary、sigreturn、fmtarg、onegadget……)直接通过 gdb_command 调用。

测试与验证

在调试主机(WSL/Linux)上:

cd /mnt/c/Users/<你>/Desktop/Develop/gdb-mcp
~/venv/gdb-mcp/bin/python -m pytest -q          # 单元 + 集成测试(真实 gdb+pwndbg)
~/venv/gdb-mcp/bin/python scripts/smoke_client.py /tmp/crackme ~/venv/gdb-mcp/bin/python

scripts/smoke_client.py 会以 MCP 客户端身份走一遍 stdio 协议:列出工具 → 启动会话 → checksec → 下断点 main → run → telescope → cyclic 生成/定位 → 退出。

安全警告

本服务器等价于暴露任意命令执行:gdb 内的 shell、python 命令以及 inferior 本身都可执行任意代码。仅供本机 stdio 使用,不要把它包装成网络服务暴露出去,也不要对不可信的目标二进制无防护地使用。

项目结构

src/gdb_mcp/
├── server.py        # FastMCP 入口与工具注册
├── session.py       # GdbSession:pygdbmi 封装、生命周期、console 执行、*stopped 收集
├── util.py          # ANSI 剥离、截断、异常包装
└── tools/
    ├── core.py      # 会话/执行控制/断点/观察点/栈/寄存器/内存/反汇编/求值/透传
    └── pwndbg.py    # pwndbg 专用封装
tests/               # pytest:单元测试 + 真实 gdb+pwndbg 集成测试
scripts/smoke_client.py  # MCP 协议冒烟客户端