SuperGhidra

SuperGhidra: Compilable C Rewriter & Guardrailed Agent MCP Suite.

Python tools that make Ghidra faster to script against, rewrite raw decompiler output into compilable C, and run static binary analyses Ghidra does not include out of the box: MSVC RTTI and MFC CRuntimeClass recovery, Serialize() archive layout tracing, cross-version function and struct-shift matching, and a Z3 equivalence checker for P-code.

Instead of paying 5–15 seconds of JVM startup per headless run or fighting .rep project lock contention while the Ghidra GUI is open, SuperGhidra keeps a single read-only Ghidra instance warm in a background daemon (127.0.0.1:5073) backed by an L2 SQLite cache and a non-destructive JSON write overlay. Heavy binary sweeps and class-layout recovery run in pure Python, NumPy SIMD, or WGPU compute shaders without touching the JVM.

No Ghidra needed, just Python. Recover MSVC RTTI classes and MFC Serialize() layouts straight from a PE file:

pip install superghidra
superghidra rtti-recover target.dll -o classes.json
python -m superghidra.formats.serialize_trace target.dll CMyDoc

Want an AI agent (Claude Desktop, Claude Code, Cursor, Antigravity) driving Ghidra without GUI lockups? Install the MCP server and point it at your project; see Agent & MCP Configuration for the config block. GHIDRA_INSTALL_DIR and JAVA_HOME must be set (Ghidra 11/12 + OpenJDK 21):

pip install git+https://github.com/yuatemycat/SuperGhidraMCP.git
claude mcp add superghidra -- superghidra-mcp -t stdio --project-path <path_to_gpr_or_binary>

SuperGhidra spans four distinct execution paths. Pick the entry point that matches your task before running commands:

python ghidra_oracle.py decompile <addr>

Most Ghidra automation scripts and MCP servers either pay a 5–15 second JVM cold-start penalty per invocation or bind directly to a single mutable GUI session where concurrent agent edits can corrupt the .rep database or trigger LockException. SuperGhidra separates read-only oracle queries (127.0.0.1:5073) from non-destructive overlay writes (ghidra_overlay.json), while executing bulk binary sweeps and C++/MFC recovery in pure Python, NumPy SIMD, and WGPU without touching the JVM.

Ghidra locks .rep projects exclusively, meaning standard headless scripts fail whenever the project is open in the Ghidra GUI. SuperGhidra avoids lock contention by separating reads (served from a warm daemon or read-only session) from writes (recorded in a JSON overlay and transaction journal):

Recover MSVC RTTI hierarchies, MFC CRuntimeClass descriptors, and virtual function tables directly from raw PE binaries without requiring Ghidra or a JVM:

# Direct module execution
python -m superghidra.formats.msvc_class_recovery target.dll

# Or recover classes and export to JSON via unified CLI
superghidra rtti-recover target.dll -o classes.json

# Trace MFC Serialize() archive field layouts
python -m superghidra.formats.serialize_trace target.dll CMyDoc

Point SuperGhidra to NSA Ghidra (11.x or 12.x) and OpenJDK 21:

# Linux / macOS
export GHIDRA_INSTALL_DIR="/opt/ghidra"
export JAVA_HOME="/usr/lib/jvm/java-21-openjdk"

# Windows (PowerShell)
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra"
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21"

Verify the daemon status or launch it with project coordinates:

# Check daemon status (auto-reports uptime, cache hit rate, and loaded binary)
python ghidra_oracle.py status

# Run daemon with explicit project paths
python ghidra_oracle.py --project-dir ~/re/proj --project-name game --program-name libgame.so status

# Or launch as a dedicated background server on port 5073
python ghidra_oracle.py serve --project-dir ~/re/proj --project-name game --program-name libgame.so --mode balanced

You can also define candidate projects globally via SUPERGHIDRA_PROJECTS="dir,name[,program]".

Subsequent queries execute in < 0.01 ms when served from the SQLite L2 cache:

# Decompile target function by virtual address
python ghidra_oracle.py decompile 0x140001000

# Propose function rename (committed safely to the JSON write overlay)
python ghidra_oracle.py rename 0x140001000 ProcessPacketHeader

# Add an address comment
python ghidra_oracle.py comment 0x140001000 "Validated packet parser entry point"

Mutations are recorded in ghidra_overlay.json to prevent .rep lock collisions. Sync them back into the Ghidra GUI session:

• Option 1 — Live Ghidra GUI Sync (ghidra_gui_overlay_sync.py):

  1. Generate a one-shot sync script or a live background watcher (--watch):

     # One-shot atomic transaction script
     superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py
     
     # Or generate a continuous background watcher script (polls every 1000 ms)
     superghidra overlay-sync --overlay ghidra_overlay.json --watch --poll-ms 1000 --out ghidra_gui_overlay_sync.py

  2. In Ghidra's CodeBrowser, navigate to Window → Script Manager.
  3. Add the output directory to Script Paths and run ghidra_gui_overlay_sync.py. All renames, comments, and type definitions apply atomically inside your active GUI session.

• Option 2 — Headless Journal Replay & Auto-Discard (merge_fork): Close the project in the Ghidra GUI to release the .rep lock, then replay the journal or merge session forks using merge_fork(fork_id, auto_discard=True). When auto_discard=True, once all operations merge cleanly with zero pending conflicts (pending_ops == 0), SuperGhidra automatically deletes the fork's isolated directory and transaction journal to reclaim disk storage. Unneeded or stale forks can also be deleted directly via discard_fork(fork_id).

SuperGhidra exposes 38 specialized reverse-engineering tools via the Model Context Protocol (MCP) using SuperghidraMCP (including recover_cpp_classes, trace_serialize, diff_binaries, verify_smt_equivalence, and gpu_adrp_scan). This enables AI coding agents to inspect binaries, query call graphs, and propose validated renames autonomously.

Install the MCP server from source:

pip install git+https://github.com/yuatemycat/SuperGhidraMCP.git

{
  "mcpServers": {
    "superghidra": {
      "command": "superghidra-mcp",
      "args": [
        "-t",
        "stdio",
        "--project-path",
        "<path_to_gpr_or_binary>"
      ],
      "env": {
        "GHIDRA_INSTALL_DIR": "/opt/ghidra",
        "JAVA_HOME": "/path/to/jdk-21"
      }
    }
  }
}

Alternative using uvx: Replace "command": "superghidra-mcp" with "command": "uvx" and set "args" to:

["--from", "git+https://github.com/yuatemycat/SuperGhidraMCP.git", "superghidra-mcp", "-t", "stdio", "--project-path", "<path_to_gpr_or_binary>"]

Both Cursor and Antigravity use standard JSON mcpServers configuration:

{
  "mcpServers": {
    "superghidra": {
      "command": "superghidra-mcp",
      "args": [
        "-t",
        "stdio",
        "--project-path",
        "<path_to_gpr_or_binary>"
      ],
      "env": {
        "GHIDRA_INSTALL_DIR": "/opt/ghidra",
        "JAVA_HOME": "/path/to/jdk-21"
      }
    }
  }
}

If running the server via HTTP (superghidra-mcp --transport streamable-http --port 8000):

• Claude Code CLI:

  claude mcp add --transport http superghidra http://127.0.0.1:8000/mcp

• HTTP URL Config (Antigravity / Cursor / Claude Desktop):

  {
    "mcpServers": {
      "superghidra": {
        "url": "http://127.0.0.1:8000/mcp"
      }
    }
  }

These subsystems form the daily-driver reverse-engineering, C rewriting, and agent-guardrail workflow:

These modules target specific scale bottlenecks or standalone verification tasks and have explicit scope boundaries:

Each package has its own README under superghidra/.

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/.

Benchmark Caveats:

• CPU SIMD vs. WGPU Crossover: Below ~5–10 MB, NumPy CPU SIMD (143.95 M insn/s on 4 MB blocks) outperforms WGPU DirectX 12 (127.25 M insn/s on 20 MB blocks) because PCIe host-to-device transfer overhead exceeds shader execution time. gpu_adrp_scanner automatically routes < 5 MB inputs to the CPU SIMD path.
• Synthetic Storage Pages: The 16 KB BufferFile compression figures (442.9 MB/s LZ4, 206.5 MB/s Zstd) are measured on 1,000 synthetic pages generated by GhidraPageSimulator, not on live .rep .gbf databases (Ghidra hardcodes LocalManagedBufferFile without an SPI hook).

Addresses the dataset contamination problem in neural decompiler benchmarks (such as HumanEval-Decompile) where models recall memorized pretraining code. Evaluated under MSVC 14.44 cl.exe / MinGW GCC 16.2.0 via differential co-execution:

• Finding: Raw LLM predictions achieved a 100% compilation rate but a 0.0% semantic pass rate due to subtle binary logic hallucinations. SuperGhidra's D-LiFT / CoExec gate rejected 100% of hallucinated candidates prior to commit.

• Dataset: LLM4Binary/decompile-eval@b9271fae3c556e46948559f4176ffa6f8b4f9491 (1300 evaluable functions from binaries compiled at O0–O3).
• Compiler & Host: Evaluated on Windows AMD64 by recompiling recovered C/C++ with gcc.EXE (MinGW-W64 x86_64-ucrt-posix-seh, built by Brecht Sanders, r3) 16.2.0 under gcc -O0 -lm.
• Host ABI Note: Single-host evaluation. Linux ELF binaries recompiled on Windows (LLP64) experience 32-bit long truncation on raw Ghidra emissions (8.23%). On Linux (LP64), raw Ghidra achieves 21.46% (279/1300), exceeding raw IDA.
• Methodology & Scope Caveat: Measures syntactic recompilability (gcc -O0 -lm) + unit test pass rate via deterministic AST/token rewriting (CompilableDecompilerFilter + defs.h compatibility macros), not neural LLM weight generation.
• 70/30 Held-Out Split: Splitting by unique function body (seed 42, all O0–O3 variants of a function kept together) confirms out-of-sample generalization on the held-out 30% test split (43/388 -> 98/388, +55 gains) with zero regressions.

HumanEval-Decompile Caveat (Deterministic C Rewriter, Not Neural Inference): The 22.62% (294/1,300 full corpus, plus 25.26% on the 30% function-disjoint held-out test split) score measures syntactic recompilability and unit-test execution pass rate produced by CompilableDecompilerFilter — a deterministic post-processing rewriter that strips stack-canary boilerplate, normalizes Ghidra pseudo-types (undefined8, CONCAT44, SUB84), and injects symmetric Hex-Rays defs.h compatibility macros (__int64, LODWORD, HIDWORD, BYTEn) for IDA Pro baselines. No neural model weights or LLM calls are invoked in this benchmark.

Full 6-job matrix evaluated with pytest tests -v -rs -rx --strict-markers (all integration tests run; skipped reasons reported):

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

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 (handles register-to-register mov/add/xor and ret on x86-64; any other instruction exits non-zero)
superghidra decompile target.dll --va 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

# Sync JSON write overlays and delta logs into an atomic Ghidra GUI Python script (add --watch for live polling)
superghidra overlay-sync --overlay ghidra_overlay.json --watch --out sync_script.py

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)

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

• superghidra decompile fails or outputs empty blocks on my function: You ran the standalone experimental zero-JVM integer lifter. Switch to python ghidra_oracle.py decompile <addr>.
• LockException: Project is locked by another process: Your .rep project is currently open in the Ghidra GUI. The daemon reads from the project without acquiring exclusive locks; if Ghidra holds an exclusive lock or you encounter lock contention, ensure the daemon uses a read-only session or private session fork, and sync changes back via superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py.
• My renamed functions in the daemon don't show up in the Ghidra GUI: Daemon writes go to the JSON overlay (ghidra_overlay.json) to prevent .rep corruption. Run superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py (or pass --watch for continuous background polling) and execute that script inside Ghidra's Script Manager, or close the GUI and run merge_fork.
• Z3 Equivalence Checker returns UNKNOWN: This is expected behavior, not a crash. The prover returns UNKNOWN whenever a block contains floating-point instructions, unmodeled system instructions, or long loops so an agent never commits a false-positive equivalence rewrite.
• WGPU scanner says Using CPU SIMD path even with [gpu] installed: For ARM64 .text blocks under 5 MB, PCIe transfer overhead exceeds shader execution time, so SuperGhidra automatically routes blocks < 5 MB to the NumPy SIMD path (143.95 M insn/s).
• Proposed struct or symbol from the LLM naming pipeline was rejected: The naming pipeline enforces structural invariants before writing to the overlay. Check the daemon log for VtableSlotMismatch, FieldOffsetOutOfBounds, or AllocationSizeConflict.

• The Java codec doesn't compress Ghidra projects transparently. Ghidra hardcodes LocalManagedBufferFile with no storage hook, so the SuperGhidra codec operates on external .sgdb files or requires patching Ghidra's core jar.
• PDB export implements CodeView 7.0 MSF structures with a Global Symbol Index (GSI) 4096-bucket hash table; MSVC and LLVM toolchains can read symbols, while complex type streams remain under active expansion.
• The SMT checker is sound but incomplete. Floats, calls, unhandled ops and long loops return UNKNOWN by design to prevent false equivalence.
• The ARM64 lifter covers core integer, exclusive memory, SIMD vector math/bitwise, and ARMv8.1-A atomics. Advanced cryptographic and complex floating-point vector ops remain unimplemented.
• The LLM naming stage needs a real endpoint. Without one, it falls back to neutral names such as sub_<addr>, labelled heuristic-fallback.
• Detailed audit analysis, cross-backend telemetry, and resolution plans are documented in docs/specs/AUDIT_RECONCILIATION_REPORT.md.

More detail is in PLAN.md.

superghidra/                 the canonical package, split into 7 domain subsystems
tests/                       domain-isolated pytest suites (747+ tests)
benchmarks/                  reproducible benchmark harnesses and measurement scripts
docs/                        benchmark specifications, walkthroughs, and architecture docs
ghidra_extension_skeleton/   Java BufferFile compression extension
templates/                   scaffolds for modules, MCP tools, and test suites
*.py                         zero-overhead backward-compatibility shims for external callers

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

If you find SuperGhidra useful, crypto donations (fast & permissionless) are welcome:

USDT (BEP20 / BNB Smart Chain):

0xd08d47bde441888166b801616754c667672cd502

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.

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.