Servidor MCP Headless do Binary Ninja — fornecendo a agentes de IA capacidades profundas de engenharia reversa por meio de 180 ferramentas.
Um servidor headless Binary Ninja que fala MCP (Protocolo de Contexto de Modelo), dando a agentes de IA acesso completo a fluxos de trabalho profundos de engenharia reversa — desmontagem, IL, patches, tipos, referências cruzadas e mais — sem uma GUI.
Projetado para rodar no mesmo contêiner Docker que o runtime do agente. Sem sidecars, sem serviços extras.
Este projeto inteiro — código, testes e documentação — é 100% vibe coded.
Os servidores MCP existentes do Binary Ninja são vinculados à GUI ou expõem uma superfície de ferramentas limitada. Este servidor é apenas headless e projetado para fluxos de trabalho orientados por agentes em ambientes de VM/contêiner em sandbox: o agente obtém controle total sobre o sistema de análise, automatizando grandes partes da engenharia reversa enquanto você discute interativamente e direciona o processo.
O objetivo é uma interface onde agentes possam inspecionar, refinar e estender uma análise ao longo do tempo — atualizando tipos, símbolos e metadados, melhorando incrementalmente o banco de dados de análise, aplicando patches e iterando com segurança usando desfazer/refazer, e executando scripts personalizados quando um fluxo de trabalho precisar de algo sob medida.
binja.eval e binja.call para qualquer coisa que o catálogo de ferramentas não cubra.3.11+binaryninja importável no seu runtime (para análise real)git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .
Ou instale diretamente da raiz do repositório sem clonar:
pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git
Transporte Stdio (padrão):
python3 binary_ninja_headless_mcp.py
Transporte TCP:
python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765
Modo falso de backend (nenhum Binary Ninja necessário):
python3 binary_ninja_headless_mcp.py --fake-backend
Este servidor fala MCP padrão sobre stdio (padrão) ou tcp, então qualquer host de agente compatível com MCP pode usá-lo.
claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py
Ou adicione ao .mcp.json do seu projeto:
{
"mcpServers": {
"binary_ninja_headless_mcp": {
"command": "python3",
"args": ["binary_ninja_headless_mcp.py"],
"cwd": "/path/to/binary-ninja-headless-mcp"
}
}
}
codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py
binary_ninja_headless_mcp.python3 com args ["binary_ninja_headless_mcp.py"] quando o cwd for a raiz do repositório, ou use um caminho absoluto do script em args.cwd para o caminho do repositório se você quiser que caminhos relativos como samples/ls sejam resolvidos corretamente.--fake-backend.health.ping, depois session.open.Modelo de implantação recomendado: execute o processo do agente e este servidor MCP na mesma imagem de contêiner.
Exemplo base:
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]
Se você precisar de análise real do Binary Ninja no contêiner, adicione seu runtime do Binary Ninja + configuração de licença nesta mesma imagem e inicie o agente com este servidor MCP configurado.
initializepingtools/listtools/callshutdownComportamento de tools/list:
offset ou limit for fornecido, usa saída paginada (offset=0, limit=50 padrão no modo paginado).prefix (por exemplo binary.)query (correspondência de substring contra nome/descrição da ferramenta)offset, limit, total, has_more.has_more=true), inclui next_offset e uma dica notice.Comportamento da resposta de chamada de ferramenta:
structuredContent é o payload completo canônico.content[0].text é uma string de resumo compacta (não duplicação completa de JSON).Este repositório é bem testado e possui portões de qualidade obrigatórios.
pytest --collect-only -q para a contagem atual de testes coletados.ruff format --check .ruff check .pytestBINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 para que as verificações sejam executadas sem exigir instalação do Binary Ninja.read_only=true).binary.basic_blocks_at e function.basic_blocks são paginados (offset/limit).memory.read tem um limite de resposta: length <= 65536.stdio/tcp) não é autenticada por padrão.binja.eval e acesso amplo à API via binja.call.ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q
Use o fuzzer de funcionalidades MCP embutido para exercitar uma ampla superfície de ferramentas contra samples/ls.
Backend real do Binary Ninja:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337
Execução de teste com backend falso:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20
Escreva um relatório JSON de cobertura:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json
Flags úteis:
--min-success-tools N: sai com código diferente de zero se menos de N ferramentas tiverem sucesso.--verbose: imprime cada chamada de ferramenta durante o fuzzing.--update-analysis: abre a sessão semente com update_analysis=true.O servidor atualmente expõe 181 ferramentas em 36 grupos de funcionalidades.
analysis.status: Obter status da análise.analysis.progress: Obter instantâneo do progresso da análise.analysis.update: Acionar atualização assíncrona da análise.analysis.update_and_wait: Executar atualização da análise e aguardar conclusão.analysis.abort: Abortar análise.analysis.set_hold: Segurar/liberar fila de análise.annotation.rename_function: Renomear uma função.annotation.rename_symbol: Renomear símbolo no endereço.annotation.undefine_symbol: Indefinir símbolo de usuário no endereço.annotation.define_symbol: Definir símbolo no endereço.annotation.rename_data_var: Renomear variável de dados.annotation.define_data_var: Definir variável de dados.annotation.undefine_data_var: Indefinir variável de dados.annotation.set_comment: Definir comentário no endereço.annotation.get_comment: Obter comentário no endereço.annotation.add_tag: Adicionar tag de dados de usuário no endereço.annotation.get_tags: Obter tags no endereço.arch.info: Obter metadados de arquitetura e plataforma.arch.disasm_bytes: Desmontar bytes com arquitetura selecionada.arch.assemble: Montar texto de instrução com arquitetura selecionada.baseaddr.detect: Executar detecção de endereço base.baseaddr.reasons: Obter razões de detecção de endereço base.baseaddr.abort: Abortar detecção de endereço base.binary.summary: Obter resumo do binário/sessão.binary.save: Salvar visualização binária atual em um caminho de arquivo.binary.functions: Listar funções com paginação.binary.strings: Listar strings descobertas com paginação.binary.search_text: Pesquisar texto/bytes brutos em uma sessão.binary.sections: Listar seções com paginação.binary.segments: Listar segmentos com paginação.binary.symbols: Listar símbolos com paginação.binary.data_vars: Listar variáveis de dados com paginação.binary.get_function_at: Encontrar função por endereço.binary.get_function_disassembly_at: Obter desmontagem completa para função que contém um endereço.binary.get_function_il_at: Obter IL completo para função que contém um endereço.binja.info: Retornar informações de versão/instalação do Binary Ninja.binja.call: Ponte genérica de API: chamar caminho alvo bn.* ou bv.*.binja.eval: Avaliar código Python com bn, sessions e bv opcional.data.typed_at: Obter variável de dados tipada em um endereço.database.create_bndb: Criar .bndb a partir da sessão.database.save_auto_snapshot: Salvar instantâneo automático.database.info: Obter status do banco de dados para a sessão.database.snapshots: Listar instantâneos do banco de dados.database.read_global: Ler chave de string global do banco de dados.database.write_global: Escrever chave de string global do banco de dados.debug.parsers: Listar analisadores de informações de depuração válidos para esta visualização.debug.parse_and_apply: Analisar informações de depuração e aplicá-las à visualização.disasm.linear: Obter linhas de desmontagem linear.disasm.function: Obter desmontagem completa para função que contém um endereço.disasm.range: Linhas de desmontagem de intervalo de endereços.external.library_add: Adicionar biblioteca externa.external.library_list: Listar bibliotecas externas.external.library_remove: Remover biblioteca externa.external.location_add: Adicionar mapeamento de localização externa.external.location_get: Obter mapeamento de localização externa.external.location_remove: Remover mapeamento de localização externa.function.basic_blocks: Listar blocos básicos em uma função com paginação.function.callers: Chamadores de uma função.function.callees: Chamados de uma função.function.variables: Listar variáveis de função.function.var_refs: Listar referências de variáveis em MLIL/HLIL.function.var_refs_from: Listar referências de variáveis originadas de um endereço.function.ssa_var_def_use: Obter definição e usos de variável SSA.function.ssa_memory_def_use: Obter definição e usos de memória SSA por versão de memória.function.metadata_store: Armazenar metadados de função por chave.function.metadata_query: Consultar metadados de função por chave.function.metadata_remove: Remover metadados de função por chave.health.ping: Verificação de saúde.il.function: Listagem de função IL.il.instruction_by_addr: Obter instrução IL por endereço de origem.il.address_to_index: Mapear endereço para índice(s) IL.il.index_to_address: Mapear índice IL para endereço de origem.il.rewrite.capabilities: Listar suporte de reescrita IL para uma função e nível IL.il.rewrite.noop_replace: Realizar substituição de expressão IL por no-op.il.rewrite.translate_identity: Traduzir IL com callback de mapeamento de identidade.loader.rebase: Rebasear BinaryView.loader.load_settings_types: Listar nomes de tipos de configurações do carregador.loader.load_settings_get: Obter valores de configurações do carregador.loader.load_settings_set: Definir um valor de configuração do carregador.memory.read: Ler bytes da visualização (length <= 65536).memory.write: Escrever bytes (hex) na visualização.memory.insert: Inserir bytes (hex) na visualização.memory.remove: Remover bytes da visualização.memory.reader_read: Ler valores inteiros via BinaryReader.memory.writer_write: Escrever valores inteiros via BinaryWriter.mcp.response_format: Explicar campos de resultado da ferramenta (structuredContent payload completo, content[0].text resumo).metadata.store: Armazenar metadados por chave.metadata.query: Consultar metadados por chave.metadata.remove: Remover metadados por chave.patch.assemble: Montar e corrigir bytes de instrução no endereço.patch.status: Inspecionar disponibilidade de patch no endereço.patch.convert_to_nop: Corrigir instrução para NOP quando suportado.patch.always_branch: Corrigir desvio condicional para sempre desviar quando suportado.patch.never_branch: Corrigir desvio condicional para nunca desviar quando suportado.patch.invert_branch: Corrigir desvio condicional por inversão quando suportado.patch.skip_and_return_value: Corrigir instrução para pular e retornar valor quando suportado.plugin.valid_commands: Listar comandos de plugin válidos no contexto.plugin.execute: Executar um comando de plugin válido no contexto.plugin_repo.status: Listar repositórios de plugins e estados de plugins.plugin_repo.check_updates: Verificar atualizações de repositório de plugins.plugin_repo.plugin_action: Executar ação de instalar/desinstalar/habilitar/desabilitar em plugin de repositório.project.create: Criar projeto.project.open: Abrir projeto.project.close: Fechar projeto rastreado.project.list: Listar pastas/arquivos do projeto.project.create_folder: Criar pasta do projeto.project.create_file: Criar arquivo do projeto a partir de dados base64.project.metadata_store: Armazenar metadados do projeto.project.metadata_query: Consultar metadados do projeto.project.metadata_remove: Remover metadados do projeto.search.data: Pesquisar padrões de bytes brutos (string hex).search.next_text: Encontrar próxima correspondência de texto.search.all_text: Encontrar todas as correspondências de texto no intervalo (regex opcional).search.next_data: Encontrar próxima correspondência de dados/padrão de byte.search.all_data: Encontrar todas as correspondências de dados/padrão de byte no intervalo.search.next_constant: Encontrar próxima ocorrência de constante.search.all_constant: Encontrar todas as ocorrências de constante no intervalo.section.add_user: Adicionar seção de usuário.section.remove_user: Remover seção de usuário.segment.add_user: Adicionar segmento de usuário.segment.remove_user: Remover segmento de usuário.session.open: Abrir um binário e criar uma sessão.session.open_bytes: Abrir uma sessão binária a partir de bytes codificados em base64.session.open_existing: Abrir outra sessão a partir do arquivo de uma sessão existente.session.close: Fechar uma sessão aberta.session.list: Listar sessões abertas.session.mode: Obter modo de segurança/determinismo da sessão.session.set_mode: Atualizar modo de segurança/determinismo da sessão.task.analysis_update: Iniciar tarefa de atualização de análise assíncrona.task.search_text: Iniciar tarefa de busca assíncrona.task.status: Obter status da tarefa.task.result: Obter resultado da tarefa.task.cancel: Cancelar tarefa (melhor esforço).transform.inspect: Inspecionar/processar pipeline de extração de transformação.type.parse_string: Analisar uma única string de tipo.type.parse_declarations: Analisar declarações C para tipos/variáveis/funções.type.define_user: Definir tipo de usuário a partir da fonte do tipo.type.rename: Renomear um tipo.type.undefine_user: Indefinir um tipo de usuário.type.import_library_type: Importar tipo da biblioteca de tipos.type.import_library_object: Importar tipo de objeto da biblioteca de tipos.type.export_to_library: Exportar tipo para uma biblioteca de tipos.type_archive.create: Criar e opcionalmente anexar um arquivo de tipos.type_archive.open: Abrir e opcionalmente anexar um arquivo de tipos.type_archive.list: Listar arquivos de tipos anexados.type_archive.get: Obter um arquivo de tipos rastreado.type_archive.pull: Extrair tipos de um arquivo de tipos.type_archive.push: Enviar tipos para um arquivo de tipos.type_archive.references: Consultar referências de entrada/saída do arquivo para um tipo.type_library.create: Criar e opcionalmente anexar uma biblioteca de tipos.type_library.load: Carregar e opcionalmente anexar uma biblioteca de tipos.type_library.list: Listar bibliotecas de tipos anexadas à visualização.type_library.get: Obter uma biblioteca de tipos rastreada.uidf.parse_possible_value: Analisar string de conjunto de valores possíveis informada pelo usuário.uidf.set_user_var_value: Definir valor de variável de usuário de função.uidf.clear_user_var_value: Limpar valor de variável de usuário de função.uidf.list_user_var_values: Listar todos os valores de variáveis de usuário para uma função.undo.begin: Iniciar transação de desfazer.undo.commit: Confirmar transação de desfazer.undo.revert: Reverter transação de desfazer.undo.undo: Realizar desfazer.undo.redo: Realizar refazer.value.reg: Obter valor de registro em/após um endereço.value.stack: Obter conteúdo da pilha em/após um endereço.value.possible: Obter conjunto de valores possíveis IL em um endereço.value.flags_at: Obter estado de leitura/gravação de flags IL levantadas em um endereço.workflow.list: Listar fluxos de trabalho registrados.workflow.describe: Descrever topologia e configurações do fluxo de trabalho.workflow.clone: Clonar fluxo de trabalho.workflow.insert: Inserir atividades antes de uma atividade.workflow.insert_after: Inserir atividades após uma atividade.workflow.remove: Remover atividade do fluxo de trabalho.workflow.graph: Resumir grafo do fluxo de trabalho.workflow.machine.status: Obter status da máquina de fluxo de trabalho.workflow.machine.control: Controlar runtime da máquina de fluxo de trabalho.xref.code_refs_to: Referências de código para um endereço.xref.code_refs_from: Referências de código de um endereço.xref.data_refs_to: Referências de dados para um endereço.xref.data_refs_from: Referências de dados de um endereço.Para mais informações, entre em contato com Tim Blazytko (@mr_phrazer).
binary.functions_at: Listar funções em um endereço.binary.basic_blocks_at: Listar blocos básicos em um endereço com paginação.