Architettura

Il plugin avvia un sottoprocesso Java (il "bridge") al caricamento. Il bridge mantiene la connessione RMI al Ghidra Server e parla un semplice protocollo JSON verso il plugin tramite un socket TCP locale. Questo tiene tutto il codice Java/RMI fuori dal processo C++ e permette alla JVM di avviarsi in background mentre BN termina il caricamento.

La JVM del bridge inizializza anche il framework Application di Ghidra all'avvio, così il percorso di scrittura può usare le API di alto livello del program-model di Ghidra (ProgramDB, DataTypeManager, SymbolTable, FunctionManager) invece delle scritture grezze db.Table.putRecord() — vedi Checkin write path sotto.

Componenti

Plugin (C++):

• plugin.cpp — registra le impostazioni e il widget della sidebar; avvia subito la JVM del bridge al caricamento
• GhidraConnection.cpp — singleton; gestisce il ciclo di vita del bridge e tutte le operazioni basate su RMI
• BridgeProcess.cpp — lancia il JAR del bridge come sottoprocesso con pipe stdout/stderr; legge la riga di handshake READY port=N
• BridgeClient.cpp — client TCP; invia richieste JSON, riceve risposte, smista eventi asincroni
• SyncEngine.cpp — applica un GhidraDbExport a una BinaryView (simboli, commenti, flag)
• ui/ProjectPanel.cpp — widget della sidebar: albero dei repo, dialog di connessione, log delle attività
• ui/ConnectDialog.cpp — dialog host/porta/utente/password

Bridge (Java):

• BridgeMain.java — parsing degli argomenti; inizializza UniversalIdGenerator e il framework Application di Ghidra; avvia il server TCP; stampa READY port=N su stdout
• BridgeServer.java — accetta una connessione client TCP e le assegna una BridgeConnection
• BridgeConnection.java — dispatcher delle richieste JSON; serializza le risposte delle API Ghidra in JSON; gestisce opCheckin (crea una nuova versione del programma sul server)
• GhidraSession.java — sessione RMI autenticata; incapsula RemoteRepositoryServerHandle
• EventStreamer.java — thread in background per ogni repo aperto; invia RepositoryChangeEvent al plugin come eventi JSON asincroni
• DatabaseExporter.java — percorso di lettura: estrae le tabelle di simboli/commenti/flag di funzione/tipi di dato/equate/segnalibri da un ManagedBufferFileHandle (il buffer DB remoto di Ghidra) tramite accesso grezzo a db.jar
• ProgramApplier.java — percorso di scrittura: apre il file buffer come un vero ProgramDB e applica tutte le modifiche lato BN tramite le API di alto livello di Ghidra (vedi Checkin write path sotto)
• DatabaseImporter.java — helper legacy di scrittura grezza mantenuti solo come seam di test; la apply(...) di produzione delega a ProgramApplier

Checkin write path

opCheckin apre il file buffer gestito del programma in modalità scrittura, costruisce un ProgramDB sopra di esso e applica le modifiche lato BN tramite le API del program-model di Ghidra. Le scritture grezze db.Table.putRecord() sono evitate — erano la fonte di ogni bug di corruzione al checkin che abbiamo mai incontrato:

ProgramApplier non ha queste trappole perché passa attraverso DataTypeManager.addDataType, SymbolTable.createLabel, Listing.setComment, Function.setReturnType, ecc. — API che mantengono automaticamente gli invarianti delle tabelle interconnesse di Ghidra. Esegue anche un passaggio cleanupBadVariableSymbols all'inizio di ogni checkin per eliminare la corruzione lasciata nel database dalle versioni precedenti del bridge.

server-package/CleanupBadVariableSymbols.java è un GhidraScript standalone che esegue la stessa pulizia tramite analyzeHeadless — utile quando un file è troppo corrotto per essere aperto nella GUI di Ghidra.

Testing

La suite è organizzata in cinque tier. I tier 2–4 esistono per dimostrare una proprietà: gli stessi dati compatibili finiscono per essere memorizzati sia nel .bndb sia nel program database di Ghidra (la matrice di compatibilità in cima a questo README).

Parity oracle (tier 3). Entrambi i lati verificano indipendentemente contro lo stesso JSON canonico versionato (la forma del DatabaseExporter del bridge). Direzione di import: il golden viene caricato in un ProgramDB (Java) e in una BinaryView tramite SyncEngine (C++), e ogni re-export deve essere uguale al golden. Direzione di checkin: le modifiche BN scriptate devono produrre esattamente fixtures/checkin/*/expected-preview.json (C++), e l'applicazione di quella preview tramite ProgramApplier deve re-esportare come expected-after.json (Java). Se entrambi i lati corrispondono ai golden condivisi, i due database concordano per transitività. Le modalità di confronto dei campi e la tabella di normalizzazione dei nomi di tipo si trovano in testdata/parity/RULES.md; il binario di test è testdata/bin/parity_x64.bin (layout in parity_x64.md).

Regression pin di lunga data sul lato Java:

• DataTypesRoundTripTest.struct_cloneSettings_doesNotThrow — le impostazioni composite devono rimanere coerenti con l'header (crash di cloneAllComponentSettings)
• FunctionSignaturesRoundTripTest.returnType_doesNotCorruptStackPurge — troncamento di IntField
• ParametersRoundTripTest.noParameterSymbol_endsUpAtRamAddress — invariante VariableAddress

I test di round-trip e parità richiedono un'installazione di Ghidra (usata a runtime per i language services). Il percorso viene letto dalla proprietà di sistema Gradle ghidra.home o dalla variabile d'ambiente GHIDRA_HOME; build.gradle passa ghidraHome per default. I test C++ dei tier 2/3 richiedono inoltre che binaryninjacore sia caricabile (gli script mettono la dir di installazione di BN nel PATH).

Prerequisiti

Qt setup

Il plugin si collega alla stessa build di Qt 6 usata da Binary Ninja. Hai due opzioni:

Opzione A — Usa un'installazione Qt esistente (la più veloce se hai già Qt)

Passa Qt6_DIR puntando alla tua directory CMake di Qt:

Su macOS lo script di build rileva automaticamente Qt se è stato installato dal Qt online installer sotto /usr/local/Qt*.

Opzione B — Compila Qt dal submodule qt-build (~1-2 ore, una volta per macchina)

Il submodule qt-build (gli script di build di Qt di Vector35) compila Qt 6 con le patch di Binary Ninja. Richiede Poetry e libclang 19 (vedi Prerequisiti sopra e qt-build/README.md).

Qt viene installato in qt/<version>/<compiler>/ all'interno del repo:

Il passaggio qt è necessario solo una volta. CMake e gli script di build rilevano il Qt compilato in qt/ a ogni esecuzione successiva e saltano completamente il submodule. La directory qt/ è in gitignore.

Building

Fresh checkout

Poi segui il Qt setup sopra (Opzione A o B), ed esegui:

macOS / Linux

Variabili d'ambiente (tutte opzionali — lo script imposta default sensati):

Windows

Modifica i percorsi in cima a build.bat per adattarli al tuo ambiente prima del primo utilizzo:

La build C++ usa CMake FetchContent per clonare binaryninja-api al commit esatto registrato in api_REVISION.txt, così l'ABI del plugin corrisponde sempre alla versione BN installata. Ghidra viene scaricato automaticamente da CMake alla prima configurazione se GHIDRA_HOME non è impostata.

Configurazione

Dopo l'installazione, imposta questi valori nelle impostazioni di Binary Ninja (Edit → Preferences → Settings, cerca "Ghidra"):

Utilizzo

1. Apri un binario in Binary Ninja.
2. Apri la sidebar Ghidra (l'icona "G" rossa).
3. Clicca Connect… e inserisci le credenziali del server.
4. L'albero dei repository si popola. Clicca la freccia di espansione (▶) su un repository per rivelare le sue cartelle e i file di progetto.
5. I file di progetto appaiono in grassetto e blu. Fai doppio clic su uno per importare la sua analisi nella binary view attualmente aperta.
6. Il log delle attività mostra il progresso dell'import e l'intervallo di indirizzi dei simboli applicati.

Prerequisito per il passaggio 5: il file del programma deve essere committato nel repository del Ghidra Server (non solo aperto localmente in Ghidra). In Ghidra: fai clic destro sul file nella finestra Project → Version Control → Add to Version Control….

Protocollo del bridge

Il plugin e il bridge comunicano tramite un socket TCP locale usando JSON delimitato da newline. Ogni richiesta porta un id intero e una stringa op; ogni risposta ripete l'id. Gli eventi asincroni (modifiche ai repository lato server) portano invece una chiave "event".

Continuare su un'altra macchina

Il repository contiene tutto il necessario per ricostruire da zero. Setup per sviluppatore che non è in git:

1. Clone + submodule:
   root@kitploit:~

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

2. Percorso Ghidra locale: crea bridge/gradle.properties:
   root@kitploit:~

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

   (Le barre in avanti funzionano anche su Windows — Gradle le preferisce.)
3. Installazioni Ghidra + Binary Ninja: stesso setup delle tue altre macchine.
4. Qt: punta Qt6_DIR a un'installazione esistente oppure esegui ./build.sh qt (Windows: build.bat qt) una volta.
5. Canale di rilascio di Binary Ninja: l'ABI del plugin deve corrispondere alla BN che esegui. Seleziona il canale al momento della build; lo script recupera il commit binaryninja-api corrispondente da 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 e --bn-api sono mutuamente esclusivi; senza nessuno dei due, viene usato il canale stable. --channel interroga GitHub Vector35/binaryninja-api (l'ultima release stable/*, o la testa del branch dev) quindi richiede accesso alla rete. Se la tua BN installata è indietro rispetto all'ultima release, passa --bn-api con lo SHA esatto dal api_REVISION.txt di quell'installazione.

Quando apri una nuova sessione di Claude Code, i migliori punti di onboarding sono questo README più lo stato attuale su dev:

• Architettura e invarianti del write-path: questo file
• Percorso di scrittura di produzione: bridge/src/main/java/com/ghidra_svr/bridge/ProgramApplier.java
• Test harness: bridge/src/test/java/com/ghidra_svr/bridge/ProgramTestBase.java
• Suite di round-trip: bridge/src/test/java/com/ghidra_svr/bridge/*RoundTripTest.java
• Commit recenti: git log --oneline — ogni riga di oggetto dice cosa è cambiato e perché

Limitazioni note / lavoro in sospeso

• Storage delle variabili locali: ProgramApplier salta le voci di parametro is_local perché mappare gli indici dei registri BN allo storage di Ghidra richiede una traduzione della register-table per architettura. I parametri funzionano; le locali non si sincronizzano ancora.
• Autenticazione: solo username + password. I callback PKI e SSH-key non sono ancora gestiti.
• Spazio di indirizzamento singolo: DatabaseExporter assume un singolo spazio di indirizzamento RAM. Gli spazi overlay o le architetture Harvard possono produrre indirizzi errati.
• Merge dei change-set: il bridge scrive un DBChangeSet vuoto per mantenere funzionanti i checkout. La macchina di merge-on-checkout di Ghidra quindi non può risolvere automaticamente le modifiche concorrenti tra utenti BN e Ghidra — vince l'ultimo che scrive.