SuperGhidra

Python tools that make Ghidra faster to script against, plus a few analyses it doesn't do out of the box: MFC/C++ class recovery, Serialize() layout tracing, cross-version function matching, and a Z3 equivalence checker for P-code.

Why

Ghidra's analysis is excellent, but driving it from scripts is slow. Each headless run pays 5–15 seconds of JVM startup. A project lock stops a second process from reading. Bulk jobs such as sweeping a 20 MB ARM64 .text section or matching 45,000 functions between two builds run on a single CPU thread.

SuperGhidra keeps one read-only Ghidra project loaded in a background daemon and caches its answers. Bulk work moves into plain Python, NumPy or GPU compute shaders. Much of the format and class-recovery work doesn't need Ghidra at all.

What's inside

Each package has its own README under superghidra/.

Results so far

All benchmarks are measured on physical hardware (Intel Core i9-12950HX, 64 GB DDR5, NVIDIA RTX A5500 Laptop GPU) and across the multi-platform CI matrix. Full empirical data and logs are in docs/benchmarks/.

Hardware & Throughput Matrix

Decompiler Pass Rate: HumanEval-Decompile (1,296 Evaluated Functions)

Evaluated under gcc -O0 -lm across optimization levels O0–O3. Functions must compile cleanly and pass their test suite:

• Overlap: 170 functions pass in both IDA Pro and SuperGhidra; 124 functions pass in SuperGhidra where IDA Pro failed.
• Refinement regressions: 0 regressions across all 1,296 functions.

Dual-OS Test Matrix (GitHub Actions CI)

Full 6-job matrix passing on every commit (Run #39691442336):

Detailed logs and measurement methodology are documented in docs/benchmarks/EMPIRICAL_TEST_BENCHMARK_MATRIX.md.

Installation

From PyPI:

pip install superghidra

Optional acceleration and integration extras:

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

From source (development):

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

Unified CLI:

SuperGhidra ships with an integrated standalone command-line executable 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

Inspect a Windows binary (no Ghidra needed):

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

From 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)

Query a Ghidra project through the daemon (needs JDK 21, Ghidra 11+ and 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

Run python ghidra_oracle.py --help to list every command.

Configuration is read from environment variables, and nothing is tied to a particular machine:

MCP

Most modules are also exposed as MCP tools through a pyghidra-mcp fork, including recover_cpp_classes, trace_serialize, decode_carchive, diff_binaries, verify_smt_equivalence and gpu_adrp_scan. This lets an AI agent drive them directly.

Known limitations

• The Java codec doesn't compress Ghidra projects transparently. Ghidra has no hook for replacing its buffer file, so you have to call the codec explicitly.
• PDB export is experimental, and MSVC/LLVM tools may not load the output. Use DWARF export instead.
• The SMT checker is sound but incomplete. Floats, calls, unhandled ops and long loops return UNKNOWN.
• The ARM64 lifter covers integer instructions only. Atomics lift as UNIMPLEMENTED.
• The LLM naming stage needs a real endpoint. Without one, it falls back to neutral names such as sub_<addr>, labelled heuristic-fallback.

More detail is in PLAN.md.

Repository layout

superghidra/   the package, split into the seven areas above
tests/         pytest suites, one folder per area
docs/          benchmark reports and design notes
ghidra_extension_skeleton/   Java BufferFile codec
*.py           thin shims so `import binary_loader` etc. keep working for older callers

If you're an AI agent, start with AGENTS.md.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for the test workflow and the safety rules: read-only projects, verified symbol commits and the emulator allow-list. Report security issues as described in SECURITY.md.

License

SuperGhidra is licensed under the GNU AGPL-3.0-or-later. If you modify it and let other people use it over a network, for example as a hosted MCP server, you have to offer them your modified source.

If the AGPL doesn't fit your use, a commercial license is available. See COMMERCIAL-LICENSE.md.

Releases up to and including 0.2.0, and commits before the license change, were published under Apache-2.0. Those versions stay under Apache-2.0 and the text is kept in LICENSES/Apache-2.0.txt.

© 2026 yuatemycat and contributors.