nccgroup/libmempoolHeap analysis tooling for mempool
初步说明：我们建议您将其作为 asatools 的一部分使用，但它也可以 独立使用。
libmempool 是一个 Python 脚本和 GDB 分析工具，用于辅助分析在 Cisco ASA 设备的各种堆中发现的与内存池（mempool）相关的数据结构。通常，这些信息嵌入在堆块（heap chunk）中，或者是对其他常见堆结构（如 dlmalloc mstate 结构）的自定义扩展。
Cisco 使用“mempool”一词来描述为各种目的（如常规分配、DMA 等）映射的内存区域。这些区域通常包含自己的堆，例如 dlmalloc。这些内存池上的分配例程通常使用围绕底层堆分配器的包装器来完成，这些包装器会将特定于内存池的元数据注入到最终的分配中。我们将这些元数据称为 mempool header（内存池头部）或简称 mh。同样地，我们经常会用 mp 来指代 mempool。使用 mh 来描述 mempool header 也与 Cisco ASA lina 二进制文件中发现的各种字符串一致。
尽管 libmempool 可以作为独立工具用于分析与内存池头和数据结构相关的某些内容，但其最大价值在于作为其他库（如 libdlmalloc 或 libptmalloc）的回调使用。
值得注意的是，内存池的某些方面（例如用于跟踪使用中块（inuse chunks）的 bins）被嵌入在 dlmalloc 2.8.x 的 mstate 结构中，并遵循相同的 bin 大小规则。这意味着几乎不可避免地，您至少需要使用 libdlmalloc 来探查封装了内存池数据的 mstate。
libmempool 已在使用 dlmalloc2.8 或基于 glibc 的 ptmalloc2 分配器的 32 位/64 位 Cisco ASA 版本（包括 ASA5500-X 系列和 GNS3）上进行了测试。它已在众多 ASA 版本（包括多个 8.x.y 和 9.x.y 分支）上进行了测试。但是，它在某些版本上完全有可能失效（break）。
要独立使用 libmempool，您只需将 libmempool.py 文件导入到您的项目中。这使您可以执行一些有限的操作，例如注册 mpcallback 对象等。如果您正在对记录的堆功能进行离线分析，这会很有用。
要导入到 GDB 中，该脚本只需要带有 python 支持的 GDB。虽然大多数现代 GDB 版本已转向 python 3，但有些版本仍期望使用 2.7。该脚本已在两者上进行了测试，但主要的开发和测试都是使用 python 3 完成的。
(gdb) source libmempool_gdb.py
我们将大部分与 gdb 相关的逻辑从 libmempool.py 中分离出来，放入 libmempool_gdb.py，只是为了测试抽象化，并让您可以轻松地在 GDB 之外使用 libmempool.py。这种情况将来可能会改变，因为我们最终希望实现类似于 libheap 和 shadow 等其他堆分析工具所使用的调试引擎抽象。
虽然 libmempool 的很大一部分价值来自于它公开的 mpcallback 回调函数，但我们还可以查看许多内置的 GDB 命令。
(gdb) mphelp
[libmempool] mempool commands for gdb
[libmempool] mpheader -v -x <addr> : show chunk contents (-v for verbose, -x for data dump)
[libmempool] mpbinwalk [-v] [-p <addr>] <sz> : walk an mpbin and operate on each chunk in a bin
[libmempool] mpbin <addr> : determine to which bin an mp_header is associated to
[libmempool] mpmstate <addr> : display and cache a mempool mstate address
[libmempool] mphelp
假设我们知道某个 mempool 头的地址，我们就可以分析它的数据。请注意，这必须是 mempool 头本身的地址，而不是核心分配器块元数据的地址。因此，我们可以如下转储内容：
(gdb) mpheader 0x7fffbc1c1ca0
struct mp_header @ 0x7fffbc1c1ca0 {
mh_magic = 0xa11c0123
mh_len = 0x3
mh_refcount = 0x10000
mh_unused = 0x0
mh_fd_link = 0x7fffbc1c19e0 (OK)
mh_bk_link = 0x7ffff7ff7540 (-)
alloc_pc = 0x55555849e260 (-)
free_pc = 0x0 (-)
我们还可以使用 -x 转储该块的十六进制内容。
(gdb) mpheader -x 0x7fffbc1c1ca0
struct mp_header @ 0x7fffbc1c1ca0 {
mh_magic = 0xa11c0123
mh_len = 0x3
mh_refcount = 0x10000
mh_unused = 0x0
mh_fd_link = 0x7fffbc1c19e0 (OK)
mh_bk_link = 0x7ffff7ff7540 (-)
alloc_pc = 0x55555849e260 (-)
free_pc = 0x0 (-)
0x3 bytes of chunk data:
0x7fffbc1c1cd0: 0x55 0x04 0x03
内存池具有 bins 的概念，它是由双向链表组成，大小与 dlmalloc 的 bins 相同，但用于跟踪使用中的块（inuse chunks）而不是空闲块（free chunks）。这样做是为了在 Cisco 设备上进行内存使用记账。很多时候，您可能会找到一个包含 mempool 头的块，但您还不知道堆上的 mstate 结构位于何处。为了确定方位，您可以使用 mpbin 命令，它会告诉您一个使用中的块当前所在的 mempool bin 的地址。例如：
(gdb) mpbin 0x7fffbc1c1ca0
[libmempool] Found bin start at 0x7ffff7ff7540
[libmempool] Cached new mp_mstate @ 0x7ffff7ff73c0
[libmempool] mp_smallbin[08] - sz: 0x00000040 cnt: 0x00d3, mh_fd_link: 0x7fffbc1c1ca0
这不仅找到了 mstate 中 mempool 部分的起始地址，而且还将它缓存，并列出该块所在的特定 bin。我们还可以选择使用 mpbinwalk 命令列出该 bin 中的所有 0xd3 个块，或者仅列出到特定数量：
(gdb) mpbinwalk 0x40
[libmempool] mp_header @ 0x7ffff7ff7540 - mh_len: 0x00000000, alloc_pc: 0x00000000 [BIN HEAD]
[libmempool] mp_header @ 0x7fffbc1c1ca0 - mh_len: 0x00000003, alloc_pc: 0x55555849e260
[libmempool] mp_header @ 0x7fffbc1c19e0 - mh_len: 0x00000003, alloc_pc: 0x55555849e260
[libmempool] mp_header @ 0x7fffbc1c1750 - mh_len: 0x00000003, alloc_pc: 0x55555849e260
[libmempool] mp_header @ 0x7fffbc1bffa0 - mh_len: 0x00000003, alloc_pc: 0x55555849e260
[libmempool] mp_header @ 0x7fffbc1bff60 - mh_len: 0x00000003, alloc_pc: 0x5555584a1288
[libmempool] mp_header @ 0x7fffbc1c0050 - mh_len: 0x00000003, alloc_pc: 0x55555849e260
[...]
现在，如果我们想要转储 mstate 结构的整个 mempool 部分（即所有 bins 及相关统计信息），我们可以使用 mpmstate 命令：
(gdb) mpmstate 0x7ffff7ff73c0
struct mp_mstate @ 0x7ffff7ff73c0 {
mp_smallbin[00] - sz: 0x00000000 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[01] - sz: 0x00000008 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[02] - sz: 0x00000010 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[03] - sz: 0x00000018 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[04] - sz: 0x00000020 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[05] - sz: 0x00000028 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[06] - sz: 0x00000030 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[07] - sz: 0x00000038 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[08] - sz: 0x00000040 cnt: 0x00d3, mh_fd_link: 0x7fffbc1c1ca0
mp_smallbin[09] - sz: 0x00000048 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[10] - sz: 0x00000050 cnt: 0x0429, mh_fd_link: 0x7fffa4000d10
mp_smallbin[11] - sz: 0x00000058 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[12] - sz: 0x00000060 cnt: 0x335d, mh_fd_link: 0x7fffb80064b0
mp_smallbin[13] - sz: 0x00000068 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[14] - sz: 0x00000070 cnt: 0x073a, mh_fd_link: 0x7fffbc1c7260
mp_smallbin[15] - sz: 0x00000078 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[16] - sz: 0x00000080 cnt: 0x0301, mh_fd_link: 0x7fffbc1c72d0
mp_smallbin[17] - sz: 0x00000088 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[18] - sz: 0x00000090 cnt: 0x0c98, mh_fd_link: 0x7fffc9488920
mp_smallbin[19] - sz: 0x00000098 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[20] - sz: 0x000000a0 cnt: 0x0161, mh_fd_link: 0x7fffa40009a0
mp_smallbin[21] - sz: 0x000000a8 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[22] - sz: 0x000000b0 cnt: 0x0092, mh_fd_link: 0x7fffa4000a40
mp_smallbin[23] - sz: 0x000000b8 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[24] - sz: 0x000000c0 cnt: 0x0120, mh_fd_link: 0x7fffbc1c1270
mp_smallbin[25] - sz: 0x000000c8 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[26] - sz: 0x000000d0 cnt: 0x00ba, mh_fd_link: 0x7fffbc1b51a0
mp_smallbin[27] - sz: 0x000000d8 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[28] - sz: 0x000000e0 cnt: 0x005b, mh_fd_link: 0x7fffc9485020
mp_smallbin[29] - sz: 0x000000e8 cnt: 0x0000, mh_fd_link: 0x0
mp_smallbin[30] - sz: 0x000000f0 cnt: 0x016e, mh_fd_link: 0x7fffbc1c7040
mp_smallbin[31] - sz: 0x000000f8 cnt: 0x0000, mh_fd_link: 0x0
mp_treebin[00] - sz: 0x00000180 cnt: 0x050f, mh_fd_link: 0x7fffbc1c7130
mp_treebin[01] - sz: 0x00000200 cnt: 0x00ce, mh_fd_link: 0x7fffbc1c2610
mp_treebin[02] - sz: 0x00000300 cnt: 0x011a, mh_fd_link: 0x7fffa40053c0
mp_treebin[03] - sz: 0x00000400 cnt: 0x013e, mh_fd_link: 0x7fffa4000f80
mp_treebin[04] - sz: 0x00000600 cnt: 0x016f, mh_fd_link: 0x7fffbc1c2a80
mp_treebin[05] - sz: 0x00000800 cnt: 0x009a, mh_fd_link: 0x7fffbc1b4880
mp_treebin[06] - sz: 0x00000c00 cnt: 0x0081, mh_fd_link: 0x7fffbc1b38b0
mp_treebin[07] - sz: 0x00001000 cnt: 0x002b, mh_fd_link: 0x7fffbc1b2330
mp_treebin[08] - sz: 0x00001800 cnt: 0x0326, mh_fd_link: 0x7fffc9368e10
mp_treebin[09] - sz: 0x00002000 cnt: 0x0038, mh_fd_link: 0x7fffc92e9c60
mp_treebin[10] - sz: 0x00003000 cnt: 0x00b9, mh_fd_link: 0x7fffa4003380
mp_treebin[11] - sz: 0x00004000 cnt: 0x006d, mh_fd_link: 0x7fffc9457720
mp_treebin[12] - sz: 0x00006000 cnt: 0x023b, mh_fd_link: 0x7fffbc1ac000
mp_treebin[13] - sz: 0x00008000 cnt: 0x0018, mh_fd_link: 0x7fffc946f850
mp_treebin[14] - sz: 0x0000c000 cnt: 0x0030, mh_fd_link: 0x7fffc935fcc0
mp_treebin[15] - sz: 0x00010000 cnt: 0x0019, mh_fd_link: 0x7fffb44262b0
mp_treebin[16] - sz: 0x00018000 cnt: 0x0073, mh_fd_link: 0x7fffc93fe020
mp_treebin[17] - sz: 0x00020000 cnt: 0x0018, mh_fd_link: 0x7fffc94368f0
mp_treebin[18] - sz: 0x00030000 cnt: 0x000c, mh_fd_link: 0x7fffb0665010
mp_treebin[19] - sz: 0x00040000 cnt: 0x001c, mh_fd_link: 0x7fffa836d010
mp_treebin[20] - sz: 0x00060000 cnt: 0x000d, mh_fd_link: 0x7fffa8c55010
mp_treebin[21] - sz: 0x00080000 cnt: 0x001d, mh_fd_link: 0x7fffa9009010
mp_treebin[22] - sz: 0x000c0000 cnt: 0x0006, mh_fd_link: 0x7fffa9081010
mp_treebin[23] - sz: 0x00100000 cnt: 0x000a, mh_fd_link: 0x7fffb025f010
mp_treebin[24] - sz: 0x00180000 cnt: 0x000b, mh_fd_link: 0x7fffa8b38010
mp_treebin[25] - sz: 0x00200000 cnt: 0x000e, mh_fd_link: 0x7fffb008a010
mp_treebin[26] - sz: 0x00300000 cnt: 0x0007, mh_fd_link: 0x7fffb0323010
mp_treebin[27] - sz: 0x00400000 cnt: 0x0002, mh_fd_link: 0x7fffa87f5010
mp_treebin[28] - sz: 0x00600000 cnt: 0x0003, mh_fd_link: 0x7fffa83e9010
mp_treebin[29] - sz: 0x00800000 cnt: 0x0001, mh_fd_link: 0x7fffab328010
mp_treebin[30] - sz: 0x00c00000 cnt: 0x0001, mh_fd_link: 0x7fffd706d010
mp_treebin[31] - sz: 0xffffffff cnt: 0x0003, mh_fd_link: 0x7fffa9326010 [UNSORTED]
我们在 libmempool 内部实现了一个「感知」dlmalloc 和 ptmalloc 的回调，旨在由 libdlmalloc 或 libptmalloc 调用，以使用额外的内存池特定数据来增强它们的块注释。例如，如果使用 libdlmalloc 打印某个 dlmalloc 块的详细列表，并且该块内部包含一个 mempool 头，那么 mempool 回调会将其打印出来。
有关通过其他工具使用时的效果信息，请参阅 libdlmalloc 和 libptmalloc 中的 README 文件。
我们可能会在需要时或在进行未来 Cisco ASA 研究时为 libmempool 添加功能。当前计划增加的内容包括：
我们非常乐意听取关于此工具的反馈，也欢迎提交 pull request。
Aaron Adams
aaron<dot>adams<at>nccgroup<dot>trustCedric Halbronn
cedric<dot>halbronn<at>nccgroup<dot>trust