Pwndbg 命令全景指南:从命令分类到源码级解析(docs/commands 索引)

原创2026-09-15 19:35:121,892 阅读
文章标签:开发工具调试器逆向工程网络安全应用安全CLI

Pwndbg 命令全景指南:从命令分类到源码级解析(docs/commands 索引)

Pwndbg 是运行在 GDB 与 LLDB 之上的渗透调试插件集合,其全部功能都以"命令"的形式暴露给用户。本文以仓库中的 docs/commands/index.md 命令索引为骨架,系统梳理 Pwndbg 命令的分类体系、典型用法与文档自动生成机制,并结合 pwndbg/commands/init.py 等源码解释命令注册、参数解析与文档同步的实现原理,帮助你快速建立"命令地图",学会查阅任意命令的完整帮助与实战示例。

Pwndbg 上下文展示界面,命令输出整合了寄存器、反汇编与栈信息

一、命令总览与分类体系

Pwndbg 的命令按功能划分为 20 个分类,每个分类对应一个独立文档目录。以下为完整分类清单及对应文档位置:

分类(Category) 目录 命令数 覆盖范围
Allocators docs/commands/allocators 2 jemalloc、mallocng(musl)分配器
Breakpoint docs/commands/breakpoint 4 分支断点、RVA 断点、忽略计数
Context docs/commands/context 7 上下文输出、历史、watch 表达式
Darwin/libsystem/Mach-O docs/commands/darwin_libsystem_mach-o 1 macOS commpage
Developer docs/commands/developer 6 日志级别、memoize、profiler、reload
Disassemble docs/commands/disassemble 2 nearpc、emulate 模拟执行
GLibc Heap docs/commands/glibc_heap 17 arena、bins、tcache、chunk 可视化
Integrations docs/commands/integrations 8 AI、反编译器、radare2/rizin、ROP 工具
Kernel docs/commands/kernel 31 内核内存、页表、SLUB、BPF、MSR
Linux/libc/ELF docs/commands/linux_libc_elf 23 GOT/PLT、auxv、envp、TLS、one_gadget
Memory docs/commands/memory 18 vmmap、search、telescope、leakfind
Misc docs/commands/misc 23 checksec、cyclic、patch、dt、spray
Process docs/commands/process 3 pid、procinfo、killthreads
Pwndbg docs/commands/pwndbg 6 config、theme、version、bugreport
Register docs/commands/register 4 CPSR、FS/GS base、setflag
Stack docs/commands/stack 6 stack、canary、retaddr、栈帧可视化
Start docs/commands/start 4 start、entry、sstart、attachp
Step/Next/Continue docs/commands/step_next_continue 11 nextcall、nextjmp、nextsyscall、xuntil
WinDbg docs/commands/windbg 24 WinDbg 兼容命令(bp/bd/be/eb/...)
Developer docs/commands/developer 6 上表已列,此处为索引重复归类

分类枚举定义于源码 pwndbg/commands/init.py 的 CommandCategory 类中,文档目录名由 category_to_folder_name() 将分类名小写化并把空格与 / 替换为 _ 生成(见 scripts/_docs/command_docs_common.py),例如 Linux/libc/ELF → linux_libc_elf。

二、快速定位命令:pwndbg 命令与 help function

在 GDB 会话中输入 pwndbg(等价于旧版 Pwndbg 中常用的命令列表功能),即可查看全部已注册命令,按分类以表格形式输出,每行包含命令名、别名(Aliases)与一行描述。

usage: pwndbg [-h] [-c CATEGORY_ | --list-categories] [filter_pattern]

位置参数与可选参数(定义见 docs/commands/pwndbg/pwndbg.md):

参数 类型 说明
filter_pattern 位置参数(可选) 按命令名或描述过滤,不区分大小写,子串匹配
-c, --category CATEGORY_ 可选 只显示指定分类的命令
--list-categories 可选标志 仅列出全部分类名,不显示命令

参数之间互斥(-c 与 --list-categories 不能同时使用),其实现位于 pwndbg/commands/pwndbg_.py,底层由 list_and_filter_commands() 遍历 pwndbg.commands.commands 全局列表,取每个命令 description 的首行作为表格描述,并支持别名高亮。典型用法:

pwndbg> pwndbg --list-categories
pwndbg> pwndbg -c heap          # 只看堆相关分类
pwndbg> pwndbg tcache           # 按名字/描述过滤

所有命令均可在 GDB 中通过 help <命令名> 查看完整用法,也可以 help function 查看 Pwndbg 提供的便捷函数。

三、按场景挑重点:五大高频命令族实战

3.1 启动与调试流程控制(Start / Step/Next/Continue)

  • start:在第一个方便的位置停止程序;
  • entry:停在程序入口地址;
  • sstart:等价于 tbreak __libc_start_main; run;
  • attachp:按 pid、进程名、argv 部分匹配或设备文件附加进程;
  • 步进类:nextcall(下一个 call)、nextret(下一个 ret 类指令)、nextsyscall(下一个不经过分支的 syscall)、stepsyscall(经过分支走到 syscall)、stepuntilasm(步进到指定指令)、xuntil(继续执行直到地址/表达式)。nextsyscall 与 stepsyscall 的差异在于后者会"走"过分支指令,适用于分析被 jcc 保护的系统调用路径。

3.2 内存与虚拟地址空间(Memory)

  • vmmap:打印虚拟内存映射页,支持过滤与上下文显示(见下文详解);
  • search:在可读内存页中搜索字节序列、字符串、指针与整数值;
  • telescope:从指定地址递归解引用指针,默认从 $sp 开始显示 8 行;
  • leakfind:从给定地址尝试寻找泄露链;
  • probeleak:指针扫描,寻找可能的偏移泄露;
  • hexdump、xor、memfrob、mmap、mprotect 等提供底层内存操作能力。

其中 telescope 是分析栈与堆指针链最常用的命令:

usage: telescope [-h] [-r] [-f] [-i] [address] [count]
  • address:起始地址,默认 $sp;count:显示行数,默认 8;
  • -r/--reverse:显示之前 count 个地址;-f/--frame:显示从 rsp 到 rbp 的栈帧;-i/--inverse:逆栈增长方向显示。

3.3 GLibc 堆调试(GLibc Heap)

堆分类是 Pwndbg 最具标志性的能力,覆盖 glibc 动态内存分配器的全部分区:

对应的实现位于 pwndbg/commands/glibc_malloc.py,堆元数据读取依赖 pwndbg/aglib/heap 下的 glibc 结构定义。

3.4 Linux 运行环境与 ELF(Linux/libc/ELF)

3.5 内核调试(Kernel)

内核命令族用于分析 Linux 内核(常用于内核漏洞研究):

实现分散于 pwndbg/commands 下的 k*.py 文件,底层内核结构解析依赖 pwndbg/aglib/kernel 与 pwndbg/lib/kernel/structs.py。

四、命令文档的自动生成机制(进阶)

docs/commands/ 下所有 .md 文件都由仓库工具自动生成,index.md 顶部标注:

THIS FILE IS AUTOGENERATED. DO NOT EDIT IT. See scripts/generate-docs.sh

生成流程由 scripts/generate-docs.sh 驱动,分两步:

  1. 提取(extract):执行 scripts/_docs/extract-all-docs.sh,对 GDB 与 LLDB 分别运行 scripts/_docs/extract_command_docs.py,遍历 pwndbg.commands 模块下所有 CommandObj 实例,用 argparse 的 formatter 抽取 usage、位置参数、可选参数、示例、notes 与子命令,并序列化为临时 JSON;
  2. 构建(build):执行 scripts/_docs/build_command_docs.py,读取 JSON 生成每个命令的 Markdown 页与 index.md 索引;设置环境变量 PWNDBG_DOCGEN_VERIFY=1 时则进入"校验模式",逐行比对现有文档与应生成内容,不一致即报错退出。

索引页的生成逻辑(scripts/_docs/build_command_docs.py)正是本文第一节表格的数据来源:按分类排序、命令名排序,取描述首行作为列表摘要,链接指向 分类目录/命令名.md。

命令注册与参数解析的源码级细节(pwndbg/commands/init.py):

  • 每条命令通过 @pwndbg.commands.Command(parser, category=...) 装饰器注册,最终生成 CommandObj 实例并加入全局 commands 列表与 command_names 集合(L147-L253);
  • 命令名由函数名中的 _ 替换为 - 得到(如 pwndbg_ → pwndbg),并断言命令名中不得含 _;
  • 允许覆盖白名单内置命令 up/down/search/pwd/start/starti/ignore,其余 GDB 内置命令不可覆盖(L153-L161);
  • 所有命令强制使用统一的 CommandFormatter(继承 argparse.RawDescriptionHelpFormatter),并把帮助文本重排为"描述在前、usage 在后",便于 GDB 的 apropos 取首行描述(L83-L121);
  • 整数类型参数会被替换为 fix_int_reraise_arg,它调用 fix() 将 $rax、0xdeadbeef、寄存器名等表达式解析为调试器 Value;任意位置参数若未显式声明 type 会直接断言报错,以此规避类型解析漏洞(L376-L383)。

这意味着:文档中的 usage、参数表与示例,本质上就是每条命令 argparse 定义的权威镜像——想给命令加参数,改源码后运行 ./scripts/generate-docs.sh 即可同步刷新文档。

五、深入案例:vmmap 与 checksec 的文档-实现对照

5.1 vmmap:内存地图命令的边界情况

vmmap 的文档除了参数表,还记录了该命令在特殊场景下的已知问题,这些是理解其实现的重要线索:

  • 未命名映射会被命名为 [anon_%#x](取起始地址高位),便于与 search 配合过滤;
  • QEMU user 目标下 gdbstub 不提供内存映射信息,Pwndbg 不解析 QEMU 进程的 /proc/$pid/maps,若兜底失败会退化为整段 [0, 0xffff...] vmmap,导致着色与 search 能力受限;
  • QEMU kernel 场景使用 gdb-pt-dump 从 guest 页表解析,可用配置项 kernel-vmmap-via-page-tables off 回退到 QEMU 的 monitor info mem;
  • coredump 调试时通过 info proc mappings 与 maintenance info sections 尽量恢复映射;
  • 最后兜底:探查 CPU 寄存器中的地址是否可读,生成 <explored> 映射(该法较慢,不会每次 stop 都执行);
  • 支持 vmmap-add、vmmap-clear、vmmap-load 手工添加映射,适用于裸机调试。

其参数包括 -w/--writable、-x/--executable、-A/-B/-C 上下文行数(默认前后各 1 行)、--gaps(显示未映射间隙)与 --refresh(丢弃缓存重新获取,macOS 默认,受 vmmap-cache 配置控制);别名 lm, address, vprot, libs。

vmmap 命令实际输出示例,展示内存页权限与范围

5.2 checksec:二进制安全属性扫描

checksec 调用 checksec 工具打印目标文件安全设置:

usage: checksec [-h] [-f FILE]

唯一可选参数 -f/--file 用于指定文件,缺省时针对当前调试对象。其自带示例展示了输出字段:Arch、RELRO、Stack(Canary)、NX、PIE、SHSTK、IBT,其中 SHSTK/IBT 对应 CET 硬件缓解。封装实现在 pwndbg/wrappers/checksec.py,与 pwndbg/commands/checksec.py 配合,兼容 GDB 与 LLDB。

六、给读者的使用建议

  • 善用 pwndbg <过滤词>:忘记命令名时,用关键字过滤即可;想看某个分类全部命令,用 pwndbg -c <分类>。
  • 每个命令文档都含可运行示例:由于文档自动生成,示例与 Examples:、Notes: 区块直接来自源码中 @pwndbg.commands.Command(examples=..., notes=...) 参数(pwndbg/commands/init.py),因此 docs/commands/ 里的每个页面都是"usage + 参数表 + 示例"三件套,可直接照抄演练。
  • 区分 GDB / LLDB 差异:文档构建时会按调试器比对同一命令的参数差异,不一致的页面用内容标签 === "GDB" / === "LLDB" 分开展示(scripts/_docs/build_command_docs.py);阅读时注意当前使用的调试器。
  • 想理解内核命令、堆命令的实现,直接跳到对应源码文件与 pwndbg/aglib 下的分析模块;想贡献新命令,参考 docs/contributing/adding-a-command.md 与本文第四节描述的文档同步流程。

七、附录:完整命令索引

以下按分类列出 docs/commands/index.md 中的全部命令与一行描述(细节以各命令文档页为准):

Allocators:jemalloc(检查 jemalloc 分配器)、mallocng(检查 mallocng/musl 分配器)

Breakpoint:break-if-not-taken(分支未命中时断下)、break-if-taken(分支命中时断下)、breakrva(按 PIE 基址的 RVA 下断点)、ignore(设置断点忽略计数)

Context:context(打印启用的 context 区块)、contextnext/contextprev(在 context 历史中切换)、contextoutput(设置 context 区块输出)、contextsearch(在 context 历史中搜索)、contextwatch/contextunwatch(增删 watch 表达式)、regs(打印寄存器并增强信息)

Darwin/libsystem/Mach-O:commpage(dump macOS commpage)

Developer:dev-dump-instruction(dump 内部 PwndbgInstruction 属性)、log-level(设置日志级别)、memoize(切换缓存)、profiler(性能分析)、reinit-pwndbg(重新初始化全部状态)、reload(重载 Pwndbg)

Disassemble:emulate(从 $PC 向前模拟执行反汇编)、nearpc(在指定地址附近反汇编)

GLibc Heap:见 3.3 节,共 arena、arenas、bins、fastbins、find-fake-fast、heap、hi、largebins、malloc-chunk、mp、smallbins、tcache、tcachebins、top-chunk、try-free、unsortedbin、vis-heap-chunks

Integrations:ai(向 GPT 提问当前调试上下文)、decomp(反编译指定地址附近代码)、decompiler-integration(控制反编译器集成)、r2(启动 radare2)、r2pipe(经 r2pipe 执行带状态 r2 命令)、rop(用 ROPgadget 导出 ROP gadget)、ropper(用 ropper 搜索 gadget)、rz(启动 rizin)、rzpipe(经 rzpipe 执行 rizin 命令)

Kernel:见 3.5 节,共 binder、buddydump、kbase、kbpf、kchecksec、kcmdline、kconfig、kcurrent、kdmabuf、kdmesg、kfile、klookup、kmem-trace、kmod、knamespace、knft、kseccomp、ksighand、kstack、ksyscalls、ktask、kversion、msr、p2v、pageinfo、pagewalk、slab、v2p

Linux/libc/ELF:见 3.4 节,共 argc、argv、aslr、auxv-explore、auxv、elfsections、envp、errno、exithandlers、got、gotplt、libcinfo、linkmap、onegadget、parse-seccomp、piebase、plt、strings、threads、tls、track-got、track-heap

Memory:见 3.2 节,共 distance、dump-register-frame、gdt、go-dump、go-type、hexdump、leakfind、memfrob、mmap、mprotect、p2p、probeleak、search、telescope、vmmap-add、vmmap-clear、vmmap-explore、vmmap、xinfo、xor

Misc:asm(汇编 shellcode 为字节)、checksec(打印二进制安全设置)、comm(在汇编代码中加注释)、cyclic(循环模式生成/查找)、cymbol(添加自定义 C 结构)、down/up(栈帧切换)、dt(dump 类型信息)、dumpargs(打印 call/syscall 参数)、getfile、hex2ptr(hex 字符串转小端地址)、hijack-fd(替换 fd)、ipi(交互式 IPython)、patch/patch-list/patch-revert(指令补丁)、plist(dump 链表)、sigreturn(显示 SigreturnFrame)、spray(用 cyclic 值喷内存)、tips、valist(dump va_list 参数)、vmmap-load(从 ELF 加载映射)

Process:killthreads、pid、procinfo(进程信息)

Pwndbg:bugreport(生成 bug 报告)、config(查看 Pwndbg 配置)、configfile(生成配置文件)、pwndbg(命令列表)、theme(主题配置)、themefile(生成主题配置)、version(版本与依赖)

Register:cpsr(打印 ARM CPSR/xPSR)、fsbase、gsbase、setflag(修改 flags 寄存器)

Stack:canary、retaddr(栈上返回地址)、stack-explore(多线程栈探索)、stack-vis(栈帧可视化)、stack、stackf

Start:见 3.1 节

Step/Next/Continue:见 3.1 节

WinDbg:bc/bd/be/bl/bp(断点控制)、da/db/dc/dd/dds/dq/ds/dw(内存 dump)、eb/ed/eq/ew/ez/eza(内存写入)、go(continue 别名)、k(backtrace 别名)、ln(最近符号)、pc(nextcall 别名)、peb(提示非 Windows 环境)

结语

docs/commands/index.md 是理解 Pwndbg 能力边界的最佳入口:它既是一份可检索的命令地图,也是命令文档自动生成流水线的输出样本。掌握"命令名 → 分类文档 → 源码实现"这条阅读链路后,无论是日常调试、堆利用研究还是内核逆向,你都能快速找到对应工具并理解其行为边界。如需为某个命令补充参数或示例,请遵循源码注释"DO NOT EDIT"的约定,直接修改命令实现并在根目录运行 ./scripts/generate-docs.sh 同步文档。

登录后查看全文
pwndbg