Arquitectura

El plugin lanza un subproceso Java (el "bridge") al cargarse. El bridge mantiene la conexión RMI con el Ghidra Server y habla un protocolo JSON simple de vuelta al plugin a través de un socket TCP local. Esto mantiene todo el código Java/RMI fuera del proceso C++ y permite que la JVM arranque en segundo plano mientras BN termina de cargarse.

La JVM del bridge también inicializa el framework Application de Ghidra al arrancar, para que la ruta de escritura pueda usar las APIs de alto nivel del modelo de programa de Ghidra (ProgramDB, DataTypeManager, SymbolTable, FunctionManager) en lugar de escrituras directas con db.Table.putRecord() — consulta Checkin write path más abajo.

Componentes

Plugin (C++):

• plugin.cpp — registra los ajustes y el widget de barra lateral; inicia de forma anticipada la JVM del bridge al cargar
• GhidraConnection.cpp — singleton; gestiona el ciclo de vida del bridge y todas las operaciones respaldadas por RMI
• BridgeProcess.cpp — lanza el JAR del bridge como subproceso con tuberías stdout/stderr; lee la línea de handshake READY port=N
• BridgeClient.cpp — cliente TCP; envía peticiones JSON, recibe respuestas, despacha eventos asíncronos
• SyncEngine.cpp — aplica un GhidraDbExport a un BinaryView (símbolos, comentarios, flags)
• ui/ProjectPanel.cpp — widget de barra lateral: árbol de repositorios, diálogo de conexión, registro de actividad
• ui/ConnectDialog.cpp — diálogo de host/puerto/usuario/contraseña

Bridge (Java):

• BridgeMain.java — análisis de argumentos; inicializa UniversalIdGenerator y el framework Application de Ghidra; inicia el servidor TCP; imprime READY port=N en stdout
• BridgeServer.java — acepta una conexión de cliente TCP y le entrega una BridgeConnection
• BridgeConnection.java — despachador de peticiones JSON; serializa las respuestas de la API de Ghidra a JSON; gestiona opCheckin (crea una nueva versión del programa en el servidor)
• GhidraSession.java — sesión RMI autenticada; envuelve RemoteRepositoryServerHandle
• EventStreamer.java — hilo en segundo plano por cada repositorio abierto; envía RepositoryChangeEvents al plugin como eventos JSON asíncronos
• DatabaseExporter.java — ruta de lectura: extrae las tablas de símbolos/comentarios/flags de funciones/tipos de datos/ecuaciones/marcadores desde un ManagedBufferFileHandle (el búfer de BD remoto de Ghidra) mediante acceso directo a db.jar
• ProgramApplier.java — ruta de escritura: abre el archivo de búfer como un ProgramDB real y aplica todos los cambios del lado de BN a través de las APIs de alto nivel de Ghidra (consulta Checkin write path más abajo)
• DatabaseImporter.java — helpers de escritura directa heredados, conservados solo como punto de prueba; el apply(...) de producción delega en ProgramApplier

Checkin write path

opCheckin abre el archivo de búfer gestionado del programa en modo escritura, construye un ProgramDB sobre él y aplica los cambios del lado de BN a través de las APIs del modelo de programa de Ghidra. Se evitan las escrituras directas con db.Table.putRecord() — fueron la fuente de todos los bugs de corrupción en el checkin que hemos encontrado:

ProgramApplier no tiene estas trampas porque enruta a través de DataTypeManager.addDataType, SymbolTable.createLabel, Listing.setComment, Function.setReturnType, etc. — APIs que mantienen automáticamente las invariantes de las tablas entrelazadas de Ghidra. También ejecuta una pasada cleanupBadVariableSymbols al inicio de cada checkin para purgar la corrupción dejada en la base de datos por versiones anteriores del bridge.

server-package/CleanupBadVariableSymbols.java es un GhidraScript independiente que ejecuta la misma limpieza mediante analyzeHeadless — útil cuando un archivo está demasiado corrupto para abrirlo en la GUI de Ghidra.

Testing

La suite está organizada en cinco niveles. Los niveles 2–4 existen para demostrar una propiedad: los mismos datos compatibles terminan almacenados tanto en el .bndb como en la base de datos del programa de Ghidra (la matriz de compatibilidad al inicio de este README).

Oráculo de paridad (nivel 3). Ambos lados verifican de forma independiente contra el mismo JSON canónico versionado (la forma del DatabaseExporter del bridge). Dirección de importación: el golden se carga en un ProgramDB (Java) y en un BinaryView mediante SyncEngine (C++), y cada re-exportación debe ser igual al golden. Dirección de checkin: las ediciones scriptadas de BN deben producir exactamente fixtures/checkin/*/expected-preview.json (C++), y aplicar ese preview mediante ProgramApplier debe re-exportarse como expected-after.json (Java). Si ambos lados coinciden con los goldens compartidos, las dos bases de datos coinciden por transitividad. Los modos de comparación de campos y la tabla de normalización de nombres de tipos están en testdata/parity/RULES.md; el binario de prueba es testdata/bin/parity_x64.bin (disposición en parity_x64.md).

Pines de regresión de larga data en el lado Java:

• DataTypesRoundTripTest.struct_cloneSettings_doesNotThrow — la configuración de compuestos debe mantenerse consistente con la cabecera (fallo de cloneAllComponentSettings)
• FunctionSignaturesRoundTripTest.returnType_doesNotCorruptStackPurge — truncamiento de IntField
• ParametersRoundTripTest.noParameterSymbol_endsUpAtRamAddress — invariante de VariableAddress

Las pruebas de round-trip y paridad requieren una instalación de Ghidra (usada en tiempo de ejecución para los servicios de lenguaje). La ruta se lee de la propiedad de sistema de Gradle ghidra.home o de la variable de entorno GHIDRA_HOME; build.gradle pasa ghidraHome por defecto. Las pruebas C++ de nivel 2/3 además necesitan que binaryninjacore sea cargable (los scripts ponen el directorio de instalación de BN en el PATH).

Requisitos previos

Qt setup

El plugin enlaza contra la misma compilación de Qt 6 que usa Binary Ninja. Tienes dos opciones:

Opción A — Usar una instalación de Qt existente (la más rápida si ya tienes Qt)

Pasa Qt6_DIR apuntando a tu directorio CMake de Qt:

En macOS el script de compilación autodetecta Qt si fue instalado por el instalador en línea de Qt bajo /usr/local/Qt*.

Opción B — Compilar Qt desde el submódulo qt-build (~1-2 horas, una vez por máquina)

El submódulo qt-build (los scripts de compilación de Qt de Vector35) compila Qt 6 con los parches de Binary Ninja. Requiere Poetry y libclang 19 (consulta Requisitos previos arriba y qt-build/README.md).

Qt se instala en qt/<version>/<compiler>/ dentro del repositorio:

El paso qt solo es necesario una vez. CMake y los scripts de compilación detectan el Qt compilado en qt/ en cada ejecución posterior y omiten el submódulo por completo. El directorio qt/ está en gitignore.

Compilación

Checkout desde cero

Luego sigue la configuración de Qt de arriba (Opción A o B) y ejecuta:

macOS / Linux

Variables de entorno (todas opcionales — el script establece valores predeterminados razonables):

Windows

Edita las rutas al inicio de build.bat para que coincidan con tu entorno antes del primer uso:

La compilación de C++ usa CMake FetchContent para clonar binaryninja-api en el commit exacto registrado en api_REVISION.txt, de modo que la ABI del plugin siempre coincide con la versión de BN instalada. Ghidra se descarga automáticamente por CMake en la primera configuración si GHIDRA_HOME no está establecido.

Configuración

Tras la instalación, establece estos valores en los ajustes de Binary Ninja (Edit → Preferences → Settings, busca "Ghidra"):

Uso

1. Abre un binario en Binary Ninja.
2. Abre la barra lateral Ghidra (el icono rojo "G").
3. Haz clic en Connect… e introduce las credenciales de tu servidor.
4. El árbol de repositorios se rellena. Haz clic en la flecha de expansión (▶) de un repositorio para revelar sus carpetas y archivos de proyecto.
5. Los archivos de proyecto aparecen en negrita y azul. Haz doble clic en uno para importar su análisis a la vista de binario abierta actualmente.
6. El registro de actividad muestra el progreso de la importación y el rango de direcciones de los símbolos aplicados.

Requisito previo para el paso 5: el archivo del programa debe estar confirmado en el repositorio del Ghidra Server (no solo abierto localmente en Ghidra). En Ghidra: haz clic derecho en el archivo en la ventana Project → Version Control → Add to Version Control….

Protocolo del bridge

El plugin y el bridge se comunican a través de un socket TCP local usando JSON delimitado por saltos de línea. Cada petición lleva un id entero y un op de tipo string; cada respuesta repite el id. Los eventos asíncronos (cambios en el repositorio del lado del servidor) llevan en su lugar una clave "event".

Continuar en otra máquina

El repositorio contiene todo lo necesario para recompilar desde cero. Configuración por desarrollador que no está en git:

1. Clonar + submódulos:
   root@kitploit:~

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

2. Ruta local de Ghidra: crea bridge/gradle.properties:
   root@kitploit:~

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

   (Las barras inclinadas también funcionan en Windows — Gradle las prefiere.)
3. Instalaciones de Ghidra + Binary Ninja: la misma configuración que en tus otras máquinas.
4. Qt: apunta Qt6_DIR a una instalación existente o ejecuta ./build.sh qt (Windows: build.bat qt) una vez.
5. Canal de versión de Binary Ninja: la ABI del plugin debe coincidir con la BN que ejecutas. Selecciona el canal al compilar; el script obtiene el commit correspondiente de binaryninja-api desde 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 y --bn-api son mutuamente excluyentes; sin ninguno de los dos, se usa el canal stable. --channel consulta el GitHub de Vector35/binaryninja-api (última release stable/*, o la cabeza de la rama dev), por lo que necesita acceso a la red. Si tu BN instalada va por detrás de la última release, pasa --bn-api con el SHA exacto del api_REVISION.txt de esa instalación.

Al abrir una sesión nueva de Claude Code, los mejores puntos de incorporación son este README más el estado actual en dev:

• Arquitectura e invariantes de la ruta de escritura: este archivo
• Ruta de escritura de producción: bridge/src/main/java/com/ghidra_svr/bridge/ProgramApplier.java
• Arnés de pruebas: bridge/src/test/java/com/ghidra_svr/bridge/ProgramTestBase.java
• Suites de round-trip: bridge/src/test/java/com/ghidra_svr/bridge/*RoundTripTest.java
• Commits recientes: git log --oneline — cada línea de asunto dice qué cambió y por qué

Limitaciones conocidas / trabajo pendiente

• Almacenamiento de variables locales: ProgramApplier omite las entradas de parámetros is_local porque mapear los índices de registro de BN al almacenamiento de Ghidra requiere una traducción de tabla de registros por arquitectura. Los parámetros funcionan; las locales aún no se sincronizan.
• Autenticación: solo usuario + contraseña. Los callbacks de PKI y clave SSH aún no están soportados.
• Espacio de direcciones único: DatabaseExporter asume un único espacio de direcciones RAM. Los espacios overlay o las arquitecturas Harvard pueden producir direcciones incorrectas.
• Fusión de conjuntos de cambios: el bridge escribe un DBChangeSet vacío para mantener los checkouts funcionando. Por lo tanto, la maquinaria de fusión al hacer checkout de Ghidra no puede resolver automáticamente ediciones concurrentes entre usuarios de BN y de Ghidra — gana el último que escribe.