Arquitetura

O plugin inicia um subprocesso Java (a "bridge") ao carregar. A bridge mantém a conexão RMI com o Ghidra Server e fala um protocolo JSON simples de volta ao plugin através de um socket TCP local. Isso mantém todo o código Java/RMI fora do processo C++ e permite que a JVM inicie em segundo plano enquanto o BN termina de carregar.

A JVM da bridge também inicializa o framework Application do Ghidra na inicialização, para que o caminho de escrita possa usar as APIs de alto nível do modelo de programa do Ghidra (ProgramDB, DataTypeManager, SymbolTable, FunctionManager) em vez de escritas cruas via db.Table.putRecord() — veja Checkin write path abaixo.

Componentes

Plugin (C++):

• plugin.cpp — registra configurações e o widget da sidebar; inicia a JVM da bridge antecipadamente ao carregar
• GhidraConnection.cpp — singleton; gerencia o ciclo de vida da bridge e todas as operações baseadas em RMI
• BridgeProcess.cpp — lança o JAR da bridge como subprocesso com pipes de stdout/stderr; lê a linha de handshake READY port=N
• BridgeClient.cpp — cliente TCP; envia requisições JSON, recebe respostas, despacha eventos assíncronos
• SyncEngine.cpp — aplica um GhidraDbExport a uma BinaryView (símbolos, comentários, flags)
• ui/ProjectPanel.cpp — widget da sidebar: árvore de repositórios, diálogo de conexão, log de atividades
• ui/ConnectDialog.cpp — diálogo de host/porta/usuário/senha

Bridge (Java):

• BridgeMain.java — parsing de argumentos; inicializa UniversalIdGenerator e o framework Application do Ghidra; inicia o servidor TCP; imprime READY port=N em stdout
• BridgeServer.java — aceita uma conexão de cliente TCP e entrega a ela uma BridgeConnection
• BridgeConnection.java — despachante de requisições JSON; serializa respostas da API do Ghidra para JSON; trata opCheckin (cria uma nova versão do programa no servidor)
• GhidraSession.java — sessão RMI autenticada; encapsula RemoteRepositoryServerHandle
• EventStreamer.java — thread em segundo plano por repositório aberto; envia RepositoryChangeEvents ao plugin como eventos JSON assíncronos
• DatabaseExporter.java — caminho de leitura: extrai tabelas de símbolos/comentários/flags de funções/tipos de dados/equates/bookmarks de um ManagedBufferFileHandle (buffer de DB remoto do Ghidra) via acesso cru ao db.jar
• ProgramApplier.java — caminho de escrita: abre o arquivo de buffer como um ProgramDB real e aplica todas as mudanças do lado do BN através das APIs de alto nível do Ghidra (veja Checkin write path abaixo)
• DatabaseImporter.java — helpers legados de escrita crua mantidos apenas como ponto de teste; o apply(...) de produção delega para ProgramApplier

Checkin write path

opCheckin abre o arquivo de buffer gerenciado do programa em modo de escrita, constrói um ProgramDB sobre ele e aplica as mudanças do lado do BN através das APIs de modelo de programa do Ghidra. Escritas cruas via db.Table.putRecord() são evitadas — elas foram a fonte de todos os bugs de corrupção de checkin que já encontramos:

ProgramApplier não tem essas armadilhas porque roteia através de DataTypeManager.addDataType, SymbolTable.createLabel, Listing.setComment, Function.setReturnType, etc. — APIs que mantêm automaticamente as invariantes das tabelas interligadas do Ghidra. Ele também executa uma passagem cleanupBadVariableSymbols no início de cada checkin para limpar corrupções deixadas no banco de dados por versões mais antigas da bridge.

server-package/CleanupBadVariableSymbols.java é um GhidraScript autônomo que executa a mesma limpeza via analyzeHeadless — útil quando um arquivo está corrompido demais para abrir na GUI do Ghidra.

Testes

A suíte está organizada em cinco tiers. Os tiers 2–4 existem para provar uma propriedade: os mesmos dados compatíveis acabam armazenados tanto no .bndb quanto no banco de dados de programa do Ghidra (a matriz de compatibilidade no topo deste README).

Oráculo de paridade (tier 3). Ambos os lados verificam independentemente contra o mesmo JSON canônico versionado (o formato do DatabaseExporter da bridge). Direção de importação: o golden carrega em um ProgramDB (Java) e em uma BinaryView via SyncEngine (C++), e cada re-export deve ser igual ao golden. Direção de checkin: edições roteirizadas no BN devem produzir exatamente fixtures/checkin/*/expected-preview.json (C++), e aplicar esse preview via ProgramApplier deve re-exportar como expected-after.json (Java). Se ambos os lados correspondem aos goldens compartilhados, os dois bancos de dados concordam por transitividade. Os modos de comparação de campos e a tabela de normalização de nomes de tipos estão em testdata/parity/RULES.md; o binário de teste é testdata/bin/parity_x64.bin (layout em parity_x64.md).

Pins de regressão de longa data no lado Java:

• DataTypesRoundTripTest.struct_cloneSettings_doesNotThrow — as configurações de composite devem permanecer consistentes com o cabeçalho (crash do cloneAllComponentSettings)
• FunctionSignaturesRoundTripTest.returnType_doesNotCorruptStackPurge — truncamento de IntField
• ParametersRoundTripTest.noParameterSymbol_endsUpAtRamAddress — invariante de VariableAddress

Testes de round-trip e paridade requerem uma instalação do Ghidra (usada em tempo de execução para serviços de linguagem). O caminho é lido da propriedade de sistema Gradle ghidra.home ou da variável de ambiente GHIDRA_HOME; build.gradle repassa ghidraHome por padrão. Testes C++ dos tiers 2/3 também precisam que binaryninjacore seja carregável (os scripts colocam o diretório de instalação do BN no PATH).

Pré-requisitos

Qt setup

O plugin faz link contra a mesma build do Qt 6 que o Binary Ninja usa. Você tem duas opções:

Opção A — Usar uma instalação existente do Qt (mais rápido se você já tem o Qt)

Passe Qt6_DIR apontando para o diretório CMake do seu Qt:

No macOS o script de build detecta automaticamente o Qt se ele foi instalado pelo instalador online do Qt em /usr/local/Qt*.

Opção B — Compilar o Qt a partir do submódulo qt-build (~1-2 horas, uma vez por máquina)

O submódulo qt-build (scripts de build do Qt da Vector35) compila o Qt 6 com os patches do Binary Ninja. Ele requer Poetry e libclang 19 (veja Pré-requisitos acima e qt-build/README.md).

O Qt é instalado em qt/<version>/<compiler>/ dentro do repositório:

O passo qt só é necessário uma vez. O CMake e os scripts de build detectam o Qt compilado em qt/ em toda execução subsequente e pulam o submódulo inteiramente. O diretório qt/ está no gitignore.

Compilação

Checkout novo

Depois siga a configuração do Qt acima (Opção A ou B) e execute:

macOS / Linux

Variáveis de ambiente (todas opcionais — o script define padrões sensatos):

Windows

Edite os caminhos no topo de build.bat para corresponder ao seu ambiente antes do primeiro uso:

A build C++ usa CMake FetchContent para clonar binaryninja-api no commit exato registrado em api_REVISION.txt, então a ABI do plugin sempre corresponde à versão do BN instalada. O Ghidra é baixado automaticamente pelo CMake na primeira configuração se GHIDRA_HOME não estiver definido.

Configuração

Após instalar, defina estas opções nas configurações do Binary Ninja (Edit → Preferences → Settings, pesquise por "Ghidra"):

Uso

1. Abra um binário no Binary Ninja.
2. Abra a sidebar Ghidra (o ícone vermelho "G").
3. Clique em Connect… e insira as credenciais do seu servidor.
4. A árvore de repositórios é populada. Clique na seta de expansão (▶) em um repositório para revelar suas pastas e arquivos de projeto.
5. Arquivos de projeto aparecem em negrito e azul. Dê um duplo clique em um para importar sua análise para a binary view atualmente aberta.
6. O log de atividades mostra o progresso da importação e o intervalo de endereços dos símbolos aplicados.

Pré-requisito para o passo 5: o arquivo de programa deve estar commitado no repositório do Ghidra Server (não apenas aberto localmente no Ghidra). No Ghidra: clique com o botão direito no arquivo na janela Project → Version Control → Add to Version Control….

Protocolo da bridge

O plugin e a bridge se comunicam através de um socket TCP local usando JSON delimitado por quebras de linha. Toda requisição carrega um id inteiro e uma string op; toda resposta ecoa o id. Eventos assíncronos (mudanças de repositório do lado do servidor) carregam uma chave "event" em vez disso.

Continuando em outra máquina

O repositório contém tudo o que é necessário para recompilar do zero. Configuração por desenvolvedor que não está no git:

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

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

2. Caminho local do Ghidra: crie bridge/gradle.properties:
   root@kitploit:~

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

   (Barras normais também funcionam no Windows — o Gradle as prefere.)
3. Instalações do Ghidra + Binary Ninja: mesma configuração das suas outras máquinas.
4. Qt: aponte Qt6_DIR para uma instalação existente ou execute ./build.sh qt (Windows: build.bat qt) uma vez.
5. Canal de release do Binary Ninja: a ABI do plugin deve corresponder ao BN que você executa. Selecione o canal ao compilar; o script busca o commit correspondente de binaryninja-api no 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 são mutuamente exclusivos; sem nenhum dos dois, o canal stable é usado. --channel consulta o GitHub do Vector35/binaryninja-api (último release stable/*, ou o head da branch dev), então precisa de acesso à rede. Se o seu BN instalado está atrás do último release, passe --bn-api com o SHA exato do api_REVISION.txt daquela instalação.

Ao abrir uma sessão nova do Claude Code, os melhores pontos de onboarding são este README mais o estado atual na branch dev:

• Arquitetura e invariantes do caminho de escrita: este arquivo
• Caminho de escrita de produção: bridge/src/main/java/com/ghidra_svr/bridge/ProgramApplier.java
• Harness de testes: bridge/src/test/java/com/ghidra_svr/bridge/ProgramTestBase.java
• Suítes de round-trip: bridge/src/test/java/com/ghidra_svr/bridge/*RoundTripTest.java
• Commits recentes: git log --oneline — cada linha de assunto diz o que mudou e por quê

Limitações conhecidas / trabalho pendente

• Storage de variáveis locais: ProgramApplier pula entradas de parâmetros is_local porque mapear índices de registradores do BN para storage do Ghidra requer uma tradução de tabela de registradores por arquitetura. Parâmetros funcionam; locais ainda não sincronizam.
• Autenticação: apenas usuário + senha. Callbacks de PKI e chave SSH ainda não são tratados.
• Espaço de endereçamento único: DatabaseExporter assume um único espaço de endereçamento RAM. Espaços overlay ou arquiteturas Harvard podem produzir endereços incorretos.
• Merge de change-set: a bridge grava um DBChangeSet vazio para manter os checkouts funcionando. Portanto, a maquinaria de merge-on-checkout do Ghidra não consegue resolver automaticamente edições concorrentes entre usuários do BN e do Ghidra — o último a escrever vence.