Architecture

Le plugin lance un sous-processus Java (le « bridge ») au chargement. Le bridge maintient la connexion RMI vers le Ghidra Server et parle un protocole JSON simple au plugin via un socket TCP local. Cela garde tout le code Java/RMI hors du processus C++ et permet à la JVM de démarrer en arrière-plan pendant que BN termine son chargement.

La JVM du bridge initialise également le framework Application de Ghidra au démarrage, afin que le chemin d'écriture puisse utiliser les API de haut niveau du modèle de programme de Ghidra (ProgramDB, DataTypeManager, SymbolTable, FunctionManager) plutôt que des écritures brutes db.Table.putRecord() — voir Checkin write path ci-dessous.

Composants

Plugin (C++) :

• plugin.cpp — enregistre les paramètres et le widget de barre latérale ; démarre la JVM du bridge au chargement
• GhidraConnection.cpp — singleton ; gère le cycle de vie du bridge et toutes les opérations basées sur RMI
• BridgeProcess.cpp — lance le JAR du bridge comme sous-processus avec des pipes stdout/stderr ; lit la ligne de handshake READY port=N
• BridgeClient.cpp — client TCP ; envoie des requêtes JSON, reçoit des réponses, distribue les événements asynchrones
• SyncEngine.cpp — applique un GhidraDbExport à un BinaryView (symboles, commentaires, indicateurs)
• ui/ProjectPanel.cpp — widget de barre latérale : arborescence des dépôts, boîte de dialogue de connexion, journal d'activité
• ui/ConnectDialog.cpp — boîte de dialogue hôte/port/utilisateur/mot de passe

Bridge (Java) :

• BridgeMain.java — analyse des arguments ; initialise UniversalIdGenerator et le framework Application de Ghidra ; démarre le serveur TCP ; affiche READY port=N sur stdout
• BridgeServer.java — accepte une connexion client TCP et lui attribue une BridgeConnection
• BridgeConnection.java — répartiteur de requêtes JSON ; sérialise les réponses de l'API Ghidra en JSON ; gère opCheckin (crée une nouvelle version du programme sur le serveur)
• GhidraSession.java — session RMI authentifiée ; encapsule RemoteRepositoryServerHandle
• EventStreamer.java — thread d'arrière-plan par dépôt ouvert ; pousse les RepositoryChangeEvent vers le plugin sous forme d'événements JSON asynchrones
• DatabaseExporter.java — chemin de lecture : extrait les tables symboles/commentaires/indicateurs de fonctions/types de données/équates/signets d'un ManagedBufferFileHandle (le buffer de base de données distant de Ghidra) via un accès brut à db.jar
• ProgramApplier.java — chemin d'écriture : ouvre le fichier buffer comme un véritable ProgramDB et applique tous les changements côté BN via les API de haut niveau de Ghidra (voir Checkin write path ci-dessous)
• DatabaseImporter.java — helpers d'écriture brute hérités conservés uniquement comme point de test ; la méthode apply(...) de production délègue à ProgramApplier

Checkin write path

opCheckin ouvre le fichier buffer managé du programme en mode écriture, construit un ProgramDB par-dessus, et applique les changements côté BN via les API du modèle de programme de Ghidra. Les écritures brutes db.Table.putRecord() sont évitées — elles étaient la source de tous les bugs de corruption de checkin que nous avons rencontrés :

ProgramApplier n'a pas ces pièges car il passe par DataTypeManager.addDataType, SymbolTable.createLabel, Listing.setComment, Function.setReturnType, etc. — des API qui maintiennent automatiquement les invariants des tables imbriquées de Ghidra. Il exécute également une passe cleanupBadVariableSymbols au début de chaque checkin pour purger la corruption laissée dans la base de données par les anciennes versions du bridge.

server-package/CleanupBadVariableSymbols.java est un GhidraScript autonome qui exécute le même nettoyage via analyzeHeadless — utile quand un fichier est trop corrompu pour être ouvert dans l'interface graphique de Ghidra.

Tests

La suite est organisée en cinq niveaux. Les niveaux 2 à 4 existent pour prouver une propriété : les mêmes données compatibles finissent stockées à la fois dans le .bndb et dans la base de données de programme Ghidra (la matrice de compatibilité en haut de ce README).

Oracle de parité (niveau 3). Les deux côtés vérifient indépendamment contre le même JSON canonique versionné (la forme du DatabaseExporter du bridge). Sens de l'import : le golden se charge dans un ProgramDB (Java) et dans un BinaryView via SyncEngine (C++), et chaque ré-export doit être égal au golden. Sens du checkin : des modifications BN scriptées doivent produire exactement fixtures/checkin/*/expected-preview.json (C++), et l'application de cet aperçu via ProgramApplier doit se ré-exporter en expected-after.json (Java). Si les deux côtés correspondent aux goldens partagés, les deux bases de données concordent par transitivité. Les modes de comparaison de champs et la table de normalisation des noms de types se trouvent dans testdata/parity/RULES.md ; le binaire de test est testdata/bin/parity_x64.bin (disposition dans parity_x64.md).

Pins de régression de longue date côté Java :

• DataTypesRoundTripTest.struct_cloneSettings_doesNotThrow — les paramètres composites doivent rester cohérents avec l'en-tête (crash cloneAllComponentSettings)
• FunctionSignaturesRoundTripTest.returnType_doesNotCorruptStackPurge — troncature IntField
• ParametersRoundTripTest.noParameterSymbol_endsUpAtRamAddress — invariant VariableAddress

Les tests d'aller-retour et de parité nécessitent une installation de Ghidra (utilisée à l'exécution pour les services de langage). Le chemin est lu depuis la propriété système Gradle ghidra.home ou la variable d'env GHIDRA_HOME ; build.gradle transmet ghidraHome par défaut. Les tests C++ des niveaux 2/3 nécessitent en plus que binaryninjacore soit chargeable (les scripts placent le répertoire d'installation de BN dans le PATH).

Prérequis

Qt setup

Le plugin se lie à la même version de Qt 6 que celle utilisée par Binary Ninja. Vous avez deux options :

Option A — Utiliser une installation Qt existante (le plus rapide si vous avez déjà Qt)

Passez Qt6_DIR pointant vers votre répertoire CMake Qt :

Sous macOS, le script de build détecte automatiquement Qt s'il a été installé par l'installateur en ligne de Qt sous /usr/local/Qt*.

Option B — Compiler Qt depuis le sous-module qt-build (~1-2 heures, une fois par machine)

Le sous-module qt-build (scripts de build Qt de Vector35) compile Qt 6 avec les patchs de Binary Ninja. Il nécessite Poetry et libclang 19 (voir Prérequis ci-dessus et qt-build/README.md).

Qt est installé dans qt/<version>/<compiler>/ à l'intérieur du dépôt :

L'étape qt n'est nécessaire qu'une seule fois. CMake et les scripts de build détectent le Qt compilé dans qt/ à chaque exécution suivante et ignorent complètement le sous-module. Le répertoire qt/ est ignoré par git.

Compilation

Checkout frais

Suivez ensuite la configuration Qt ci-dessus (Option A ou B), puis exécutez :

macOS / Linux

Variables d'environnement (toutes optionnelles — le script définit des valeurs par défaut raisonnables) :

Windows

Modifiez les chemins en haut de build.bat pour qu'ils correspondent à votre environnement avant la première utilisation :

La compilation C++ utilise CMake FetchContent pour cloner binaryninja-api au commit exact enregistré dans api_REVISION.txt, de sorte que l'ABI du plugin corresponde toujours à la version BN installée. Ghidra est téléchargé automatiquement par CMake lors de la première configuration si GHIDRA_HOME n'est pas défini.

Configuration

Après l'installation, définissez ces paramètres dans les réglages de Binary Ninja (Edit → Preferences → Settings, recherchez « Ghidra ») :

Utilisation

1. Ouvrez un binaire dans Binary Ninja.
2. Ouvrez la barre latérale Ghidra (l'icône « G » rouge).
3. Cliquez sur Connect… et saisissez vos identifiants de serveur.
4. L'arborescence des dépôts se remplit. Cliquez sur la flèche d'expansion (▶) d'un dépôt pour révéler ses dossiers et fichiers de projet.
5. Les fichiers de projet apparaissent en gras et en bleu. Double-cliquez sur l'un d'eux pour importer son analyse dans la vue binaire actuellement ouverte.
6. Le journal d'activité affiche la progression de l'import et la plage d'adresses des symboles appliqués.

Prérequis pour l'étape 5 : le fichier de programme doit être commité dans le dépôt du Ghidra Server (pas seulement ouvert localement dans Ghidra). Dans Ghidra : clic droit sur le fichier dans la fenêtre Project → Version Control → Add to Version Control….

Protocole du bridge

Le plugin et le bridge communiquent via un socket TCP local en utilisant du JSON délimité par des retours à la ligne. Chaque requête porte un id entier et un op chaîne ; chaque réponse renvoie l'id. Les événements asynchrones (changements de dépôt côté serveur) portent une clé "event" à la place.

Continuer sur une autre machine

Le dépôt contient tout le nécessaire pour reconstruire à partir de zéro. Configuration propre à chaque développeur qui n'est pas dans git :

1. Clone + sous-modules :
   root@kitploit:~

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

2. Chemin Ghidra local : créez bridge/gradle.properties :
   root@kitploit:~

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

   (Les slashs fonctionnent aussi sous Windows — Gradle les préfère.)
3. Installations Ghidra + Binary Ninja : même configuration que vos autres machines.
4. Qt : pointez soit Qt6_DIR vers une installation existante, soit exécutez ./build.sh qt (Windows : build.bat qt) une fois.
5. Canal de release Binary Ninja : l'ABI du plugin doit correspondre au BN que vous exécutez. Sélectionnez le canal lors de la compilation ; le script récupère le commit binaryninja-api correspondant depuis 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 et --bn-api sont mutuellement exclusifs ; sans aucun des deux, le canal stable est utilisé. --channel interroge le GitHub Vector35/binaryninja-api (dernière release stable/*, ou la tête de branche dev) et nécessite donc un accès réseau. Si votre BN installé est en retard sur la dernière release, passez --bn-api avec le SHA exact issu du api_REVISION.txt de cette installation.

Lors de l'ouverture d'une nouvelle session Claude Code, les meilleurs points d'entrée sont ce README plus l'état actuel sur dev :

• Architecture et invariants du chemin d'écriture : ce fichier
• Chemin d'écriture de production : bridge/src/main/java/com/ghidra_svr/bridge/ProgramApplier.java
• Harnais de test : bridge/src/test/java/com/ghidra_svr/bridge/ProgramTestBase.java
• Suites d'aller-retour : bridge/src/test/java/com/ghidra_svr/bridge/*RoundTripTest.java
• Commits récents : git log --oneline — chaque ligne de sujet indique ce qui a changé et pourquoi

Limitations connues / travail en cours

• Stockage des variables locales : ProgramApplier ignore les entrées de paramètres is_local car mapper les indices de registres BN vers le stockage Ghidra nécessite une traduction de table de registres par architecture. Les paramètres fonctionnent ; les locales ne se synchronisent pas encore.
• Authentification : uniquement nom d'utilisateur + mot de passe. Les callbacks PKI et clé SSH ne sont pas encore gérés.
• Espace d'adressage unique : DatabaseExporter suppose un seul espace d'adressage RAM. Les espaces overlay ou les architectures Harvard peuvent produire des adresses incorrectes.
• Fusion des change-sets : le bridge écrit un DBChangeSet vide pour maintenir le fonctionnement des checkouts. La machinerie de fusion-au-checkout de Ghidra ne peut donc pas résoudre automatiquement les modifications concurrentes entre utilisateurs BN et Ghidra — le dernier écrivain gagne.