Architecture

The plugin spawns a Java subprocess (the "bridge") on load. The bridge holds the RMI connection to the Ghidra Server and speaks a simple JSON protocol back to the plugin over a local TCP socket. This keeps all Java/RMI code out of the C++ process and lets the JVM start in the background while BN finishes loading.

The bridge JVM also initialises Ghidra's Application framework at startup so the write path can use Ghidra's high-level program-model APIs (ProgramDB, DataTypeManager, SymbolTable, FunctionManager) rather than raw db.Table.putRecord() writes — see Checkin write path below.

Components

Plugin (C++):

• plugin.cpp — registers settings and the sidebar widget; eagerly starts the bridge JVM on load
• GhidraConnection.cpp — singleton; manages bridge lifecycle and all RMI-backed operations
• BridgeProcess.cpp — launches the bridge JAR as a subprocess with stdout/stderr pipes; reads the READY port=N handshake line
• BridgeClient.cpp — TCP client; sends JSON requests, receives responses, dispatches async events
• SyncEngine.cpp — applies a GhidraDbExport to a BinaryView (symbols, comments, flags)
• ui/ProjectPanel.cpp — sidebar widget: repo tree, connect dialog, activity log
• ui/ConnectDialog.cpp — host/port/user/password dialog

Bridge (Java):

• BridgeMain.java — argument parsing; initialises UniversalIdGenerator and the Ghidra Application framework; starts the TCP server; prints READY port=N to stdout
• BridgeServer.java — accepts one TCP client connection and hands it a BridgeConnection
• BridgeConnection.java — JSON request dispatcher; serialises Ghidra API responses to JSON; handles opCheckin (creates a new program version on the server)
• GhidraSession.java — authenticated RMI session; wraps RemoteRepositoryServerHandle
• EventStreamer.java — background thread per open repo; pushes RepositoryChangeEvents to the plugin as async JSON events
• DatabaseExporter.java — read path: extracts symbol/comment/function-flag/data-type/equate/bookmark tables from a ManagedBufferFileHandle (Ghidra's remote DB buffer) via raw db.jar access
• ProgramApplier.java — write path: opens the buffer file as a real ProgramDB and applies all BN-side changes through Ghidra's high-level APIs (see Checkin write path below)
• DatabaseImporter.java — legacy raw-write helpers kept only as a test seam; production apply(...) delegates to ProgramApplier

Checkin write path

opCheckin opens the program's managed buffer file in write mode, constructs a ProgramDB over it, and applies BN-side changes through Ghidra's program-model APIs. Raw db.Table.putRecord() writes are avoided — they were the source of every checkin-corruption bug we ever hit:

ProgramApplier doesn't have these traps because it routes through DataTypeManager.addDataType, SymbolTable.createLabel, Listing.setComment, Function.setReturnType, etc. — APIs that maintain Ghidra's interlocking-table invariants automatically. It also runs a cleanupBadVariableSymbols pass at the start of every checkin to purge corruption left in the database by older bridge versions.

server-package/CleanupBadVariableSymbols.java is a standalone GhidraScript that runs the same cleanup via analyzeHeadless — useful when a file is too corrupted to open in the Ghidra GUI.

Testing

The suite is organised in five tiers. Tiers 2–4 exist to prove one property: the same compatible data ends up stored in both the .bndb and the Ghidra program database (the compatibility matrix at the top of this README).

Parity oracle (tier 3). Both sides independently verify against the same checked-in canonical JSON (the bridge DatabaseExporter shape). Import direction: the golden loads into a ProgramDB (Java) and into a BinaryView via SyncEngine (C++), and each re-export must equal the golden. Checkin direction: scripted BN edits must produce exactly fixtures/checkin/*/expected-preview.json (C++), and applying that preview via ProgramApplier must re-export as expected-after.json (Java). If both sides match the shared goldens, the two databases agree by transitivity. Field compare modes and the type-name normalization table live in testdata/parity/RULES.md; the test binary is testdata/bin/parity_x64.bin (layout in parity_x64.md).

Long-standing regression pins on the Java side:

• DataTypesRoundTripTest.struct_cloneSettings_doesNotThrow — composite settings must stay consistent with header (cloneAllComponentSettings crash)
• FunctionSignaturesRoundTripTest.returnType_doesNotCorruptStackPurge — IntField truncation
• ParametersRoundTripTest.noParameterSymbol_endsUpAtRamAddress — VariableAddress invariant

Round-trip and parity tests require a Ghidra install (used at runtime for language services). The path is read from the ghidra.home Gradle system property or GHIDRA_HOME env var; build.gradle passes ghidraHome through by default. Tier-2/3 C++ tests additionally need binaryninjacore loadable (the scripts put the BN install dir on PATH).

Prerequisites

Qt setup

The plugin links against the same Qt 6 build that Binary Ninja uses. You have two options:

Option A — Use an existing Qt install (fastest if you already have Qt)

Pass Qt6_DIR pointing at your Qt CMake directory:

On macOS the build script auto-detects Qt if it was installed by the Qt online installer under /usr/local/Qt*.

Option B — Build Qt from the qt-build submodule (~1-2 hours, once per machine)

The qt-build submodule (Vector35's Qt build scripts) compiles Qt 6 with Binary Ninja's patches. It requires Poetry and libclang 19 (see Prerequisites above and qt-build/README.md).

Qt is installed to qt/<version>/<compiler>/ inside the repo:

The qt step is only needed once. CMake and the build scripts detect the built Qt in qt/ on every subsequent run and skip the submodule entirely. The qt/ directory is gitignored.

Building

Fresh checkout

Then follow the Qt setup above (Option A or B), and run:

macOS / Linux

Environment variables (all optional — the script sets sensible defaults):

Windows

Edit the paths at the top of build.bat to match your environment before first use:

The C++ build uses CMake FetchContent to clone binaryninja-api at the exact commit recorded in api_REVISION.txt, so the plugin ABI always matches the installed BN version. Ghidra is downloaded automatically by CMake on first configure if GHIDRA_HOME is not set.

Configuration

After installing, set these in Binary Ninja's settings (Edit → Preferences → Settings, search "Ghidra"):

Usage

1. Open a binary in Binary Ninja.
2. Open the Ghidra sidebar (the red "G" icon).
3. Click Connect… and enter your server credentials.
4. The repository tree populates. Click the expand arrow (▶) on a repository to reveal its folders and project files.
5. Project files appear bold and blue. Double-click one to import its analysis into the currently open binary view.
6. The activity log shows import progress and the address range of applied symbols.

Prerequisite for step 5: the program file must be committed to the Ghidra Server repository (not just open locally in Ghidra). In Ghidra: right-click the file in the Project window → Version Control → Add to Version Control….

Bridge protocol

The plugin and bridge communicate over a local TCP socket using newline-delimited JSON. Every request carries an integer id and a string op; every response echoes the id. Async events (server-side repository changes) carry an "event" key instead.

Continuing on another machine

The repository contains everything needed to rebuild from scratch. Per-developer setup that isn't in git:

1. Clone + submodules:
   root@kitploit:~

   git clone https://github.com/mutinylaboratories/ghidra_svr_bridge.git
   cd ghidra_svr_bridge
   git submodule update --init --recursive
   

2. Local Ghidra path: create bridge/gradle.properties:
   root@kitploit:~

   ghidraHome=C:/Users/<you>/ghidra/ghidra_12.0.4_PUBLIC
   

   (Forward slashes work on Windows too — Gradle prefers them.)
3. Ghidra + Binary Ninja installations: same setup as your other machines.
4. Qt: either point Qt6_DIR at an existing install or run ./build.sh qt (Windows: build.bat qt) once.
5. Binary Ninja release channel: the plugin's ABI must match the BN you run. Select the channel when building; the script fetches the matching binaryninja-api commit from GitHub:
   root@kitploit:~

   ./build.sh --channel stable    # default — latest stable release (from GitHub)
   ./build.sh --channel dev        # latest dev (dev branch head, from GitHub)
   ./build.sh --bn-api <commit>   # explicit commit, no GitHub lookup (escape hatch)
   

   --channel and --bn-api are mutually exclusive; with neither, the stable channel is used. --channel queries the Vector35/binaryninja-api GitHub (latest stable/* release, or the dev branch head) so it needs network access. If your installed BN lags the latest release, pass --bn-api with the exact SHA from that install's api_REVISION.txt.

When opening a fresh Claude Code session, the best onboarding pointers are this README plus the current state on dev:

• Architecture and write-path invariants: this file
• Production write path: bridge/src/main/java/com/ghidra_svr/bridge/ProgramApplier.java
• Test harness: bridge/src/test/java/com/ghidra_svr/bridge/ProgramTestBase.java
• Round-trip suites: bridge/src/test/java/com/ghidra_svr/bridge/*RoundTripTest.java
• Recent commits: git log --oneline — each subject line says what changed and why

Known limitations / pending work

• Local variable storage: ProgramApplier skips is_local parameter entries because mapping BN register indices to Ghidra storage requires a per-architecture register-table translation. Parameters work; locals don't sync yet.
• Authentication: only username + password. PKI and SSH-key callbacks are not yet handled.
• Single address space: DatabaseExporter assumes a single RAM address space. Overlay spaces or Harvard architectures may produce incorrect addresses.
• Change-set merge: the bridge writes an empty DBChangeSet to keep checkouts working. Ghidra's merge-on-checkout machinery therefore can't auto-resolve concurrent edits between BN and Ghidra users — last writer wins.