SuperGhidra

让 Ghidra 脚本编写更快的 Python 工具，外加一些它开箱即用并不提供的分析能力：MFC/C++ 类恢复、Serialize() 布局追踪、跨版本函数匹配，以及针对 P-code 的 Z3 等价性检查器。

为什么

Ghidra 的分析能力非常出色，但通过脚本驱动它却很慢。每次无头运行都要付出 5–15 秒的 JVM 启动开销。项目锁会阻止第二个进程读取。诸如扫描 20 MB 的 ARM64 .text 段或在两个构建之间匹配 45,000 个函数这类批量任务，只能跑在单个 CPU 线程上。

SuperGhidra 在后台守护进程中保持一个只读的 Ghidra 项目常驻加载，并缓存其查询结果。批量工作转移到纯 Python、NumPy 或 GPU 计算着色器中执行。许多格式解析和类恢复工作根本不需要 Ghidra。

包含内容

包	功能
core	运行在 127.0.0.1:5073 上的守护进程，带 SQLite 缓存。重命名和注释写入 JSON 覆盖层，绝不写入 .rep。还包括资源调控器（eco / balanced / turbo / auto）和共享内存 IPC。
formats	ELF / PE / Mach-O 加载器、MSVC RTTI 与 MFC CRuntimeClass 恢复、Serialize() 追踪、CArchive 解码器，以及 DWARF 5 / Breakpad / map 导出。这些都不需要 Ghidra。
lifters	ARM64 → P-code 提升器（整数子集）、x86 与 ARM/Thumb 解码器，以及一个 Z3 检查器，可证明两段代码等价或返回 UNKNOWN。
diff	使用 CFG 特征向量跨版本匹配函数，然后找出偏移发生变化的结构体字段并重写其访问代码。
acceleration	WGPU 着色器，用于在 ARM64 中扫描 ADRP+ADD/LDR 指令对和函数序言，并带有 SIMD CPU 回退。
storage	用于 Ghidra 16 KB 缓冲页的 LZ4 / Zstd 编解码器，外加一个独立的 Java BufferFile 编解码器。
integrations	APK ↔ JNI 交叉引用器、带设备允许列表的 Android 模拟器内存读取器，以及 LLM 命名流水线。

每个包在 superghidra/ 下都有自己的 README。

目前结果

所有基准测试均在物理硬件（Intel Core i9-12950HX、64 GB DDR5、NVIDIA RTX A5500 Laptop GPU）上测量，并覆盖多平台 CI 矩阵。完整的实测数据和日志位于 docs/benchmarks/。

硬件与吞吐量矩阵

工作负载 / 基准测试	输入大小 / 目标	引擎 / 后端	实测时间	实测吞吐量 / 结果	状态
ARM64 ADRP + ADD/LDR 扫描	4.0 MB ARM64 块（1,048,576 条指令）	NumPy SIMD	7.28 ms	143.95 M 指令/秒	识别出 1,049 对
ARM64 函数播种器	4.0 MB ARM64 块（1,048,576 条指令）	NumPy SIMD	8.31 ms	126.19 M 指令/秒	识别出 1,049 个序言
大规模 GPU ADRP 扫描	20.0 MB ARM64 块（5,242,880 条指令）	WGPU DirectX 12	41.20 ms	127.25 M 指令/秒	与 CPU 结果逐位一致
缓冲文件压缩（LZ4）	1,000 个合成 16 KB 页（16.0 MB）	LZ4 block	36.12 ms	442.9 MB/s（4.84 倍压缩比）	节省 79.32% 磁盘空间
缓冲文件压缩（Zstd）	1,000 个合成 16 KB 页（16.0 MB）	Zstd Level 3	77.48 ms	206.5 MB/s（7.39 倍压缩比）	节省 86.47% 磁盘空间
反编译查询缓存	实时 Ghidra 守护进程 RPC	SQLite L2 缓存	< 0.01 ms	> 100,000 请求/秒	内存覆盖层命中
SHM 通道 IPC 往返	64 KB 内存映射环形缓冲区	Windows SHM IPC	5.12 µs	195,300 消息/秒	零拷贝共享内存

反编译器通过率：HumanEval-Decompile（评估 1,296 个函数）

在 gcc -O0 -lm 下，跨优化级别 O0–O3 进行评估。函数必须能够干净地编译并通过其测试套件：

反编译器流水线	可编译通过数	通过率 (%)	相对原始 Ghidra 的差值	相对 IDA Pro 的差值
原版 NSA Ghidra	107 / 1,296	8.26%	基线	-8.64%
商业版 IDA Pro	219 / 1,296	16.90%	+8.64%	基线
SuperGhidra 可编译过滤器	294 / 1,296	22.69%	+14.43%	+5.79%

• 重叠情况： 170 个函数在 IDA Pro 和 SuperGhidra 中均通过；124 个函数在 SuperGhidra 中通过而 IDA Pro 失败。
• 精化回归： 全部 1,296 个函数中 0 回归。

双操作系统测试矩阵（GitHub Actions CI）

完整的 6 作业矩阵在每次提交时均通过（运行 #39691442336）：

操作系统	Python 3.10	Python 3.11	Python 3.12	Pytest 测试数量	通过率
Ubuntu Linux (ubuntu-latest)	32s	26s	25s	626 收集（572 通过，42 跳过，11 取消选择）	100%
Windows Server (windows-latest)	1m 25s	1m 06s	53s	626 收集（583 通过，32 跳过，11 取消选择）	100%

详细日志和测量方法记录在 docs/benchmarks/EMPIRICAL_TEST_BENCHMARK_MATRIX.md 中。

安装

从 PyPI 安装：

pip install superghidra

可选的加速与集成附加项：

pip install "superghidra[all]"       # all optional backends
pip install "superghidra[smt]"       # Z3 P-code equivalence checker
pip install "superghidra[gpu]"       # WGPU compute shaders (ADRP/prologue sweeps)
pip install "superghidra[storage]"   # LZ4 & Zstandard 16 KB page compression
pip install "superghidra[ghidra]"    # PyGhidra bridge & JVM headless bindings
pip install "superghidra[frida]"     # Live emulator runtime inspection

来自源码（开发）：

git clone https://github.com/yuatemycat/SuperGhidra
cd SuperGhidra
pip install -e ".[all]"
python -m pytest -q

统一 CLI：

SuperGhidra 附带一个集成的独立命令行可执行文件 superghidra：

# Display version and hardware acceleration telemetry
superghidra version

# Staged P-code decompiler (MBA simplification, opaque branch pruning, goto-free C)
superghidra decompile target.dll --rva 0x140001000 --arch x86_64 -o decompiled.c

# Import IDA Pro .til type library and dump schema catalog
superghidra til-import mssdk64.til -o catalog.json

# Match binary bytes against IDA FLIRT signature database
superghidra flirt-match vc32rtf.sig target.exe --rva 0x1000

# Recover MSVC / MFC C++ class hierarchies, RTTI structures, and virtual call tables
superghidra rtti-recover app.dll -o classes.json

# Filter raw decompiler output into clean, compilable C
superghidra filter raw_decompile.c -o clean.c

检查 Windows 二进制文件（无需 Ghidra）：

python -m superghidra.formats.binary_loader app.dll          # sections, imports, exports
python -m superghidra.formats.msvc_class_recovery app.dll    # RTTI + MFC classes
python -m superghidra.formats.serialize_trace app.dll CMyDoc # Serialize() field layout

从 Python 调用：

from superghidra.formats.binary_loader import load_binary
from superghidra.formats.msvc_class_recovery import recover_classes
import superghidra as sg

img = load_binary("app.dll")
print(img.format, img.arch, len(img.sections))

report = recover_classes("app.dll")
print(len(report.mfc_classes), "MFC classes")

# Lift one ARM64 instruction and check it against itself with Z3
ops = sg.ARM64PcodeLifter().lift_instruction(0x1000, 0x91008041)  # add x1, x2, #0x20
print(sg.SMTPcodeVerifier().verify_equivalence(ops, ops).equivalent)

通过守护进程查询 Ghidra 项目（需要 JDK 21、Ghidra 11+ 和 pyghidra）：

export GHIDRA_INSTALL_DIR=/path/to/ghidra
python ghidra_oracle.py --project-dir ~/re/proj --project-name game --program-name libgame.so status
python ghidra_oracle.py decompile 0x00CF2D84   # first call boots Ghidra, later calls hit the cache
python ghidra_oracle.py rename 0x00CF2D84 World_tick
python ghidra_oracle.py mode eco               # throttle CPU use
python ghidra_oracle.py stop

运行 python ghidra_oracle.py --help 可列出所有命令。

配置从环境变量读取，不绑定任何特定机器：

变量	用途
GHIDRA_INSTALL_DIR、JAVA_HOME	Ghidra 和 JDK 的位置（守护进程、无头运行、Java 编解码器构建）
SUPERGHIDRA_PROJECTS	守护进程的默认项目：以 ; 连接的 dir,name[,program] 条目
SUPERGHIDRA_MSVC_ROOT	便携式 MSVC 文件夹，当 gcc/clang 不在 PATH 中时使用
SUPERGHIDRA_TEST_ARM64_ELF、SUPERGHIDRA_TEST_SWDM、SUPERGHIDRA_TEST_SW_ROOT	用于集成测试的可选真实二进制文件 / SOLIDWORKS 安装。未设置时这些测试会被跳过。

MCP

大多数模块也通过 pyghidra-mcp 的一个分支以 MCP 工具的形式暴露，包括 recover_cpp_classes、trace_serialize、decode_carchive、diff_binaries、verify_smt_equivalence 和 gpu_adrp_scan。这让 AI 智能体可以直接驱动它们。

已知限制

• Java 编解码器无法透明地压缩 Ghidra 项目。Ghidra 没有用于替换其缓冲区文件的钩子，因此必须显式调用编解码器。
• PDB 导出是实验性的，MSVC/LLVM 工具可能无法加载输出。请改用 DWARF 导出。
• SMT 检查器是可靠的，但不完备。浮点数、调用、未处理的操作和长循环会返回 UNKNOWN。
• ARM64 提升器仅覆盖整数指令。原子操作提升为 UNIMPLEMENTED。
• LLM 命名阶段需要真实的端点。没有端点时，它会回退到中性名称，如 sub_<addr>，并标记为 heuristic-fallback。

更多细节见 PLAN.md。

仓库布局