Pwndbg 命令全景指南：从命令分类到源码级解析（docs/commands 索引）

Pwndbg 命令全景指南：从命令分类到源码级解析（docs/commands 索引）

【免费下载链接】pwndbgExploit Development and Reverse Engineering with GDB & LLDB Made Easy项目地址: https://gitcode.com/GitHub_Trending/pw/pwndbg

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

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

一、命令总览与分类体系

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

分类枚举定义于源码 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）：

参数之间互斥（-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 动态内存分配器的全部分区：

• 概览类：heap（迭代打印堆上 chunk）、vis-heap-chunks（可视化 chunk 布局）、hi（判断地址属于哪个 chunk）；
• 结构类：arena / arenas、mp（打印mp_结构）、malloc-chunk、top-chunk；
• 分区类：fastbins、smallbins、largebins、unsortedbin、bins（一次性打印所有 bin 与 tcache）、tcache、tcachebins；
• 高级工具：find-fake-fast（在指定地址附近寻找可用的 fake fast/tcache chunk）、try-free（模拟若对某地址调用 free 会发生什么）。

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

3.4 Linux 运行环境与 ELF（Linux/libc/ELF）

• got / gotplt / plt：查看 GOT/PLT 状态，配合 track-got 可跟踪 GOT 改写；
• piebase / breakrva：PIE 基址换算与按 RVA 下断点；
• aslr：查看/开关 ASLR；one_gadget：寻找一箭双雕的 execve gadget；
• auxv / auxv-explore、envp、tls、linkmap：剖析进程运行时环境。

3.5 内核调试（Kernel）

内核命令族用于分析 Linux 内核（常用于内核漏洞研究）：

• 地址换算：v2p / p2v（虚拟地址与 physmap 地址互转）、pagewalk（页表遍历）、pageinfo；
• 内核对象：ktask（内核 task）、kbase（内核虚拟基址）、kmod（已加载模块）、kfile（task 的文件描述符）、kstack、ksyscalls；
• 分配器与追踪：slab（SLUB）、buddydump（buddy 分配器）、kmem-trace（SLUB/buddy 分配与释放追踪）；
• 安全配置：kchecksec（内核加固选项）、kseccomp、ksighand。

实现分散于 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同步文档。

【免费下载链接】pwndbgExploit Development and Reverse Engineering with GDB & LLDB Made Easy项目地址: https://gitcode.com/GitHub_Trending/pw/pwndbg