Binary Ninja

Binary Ninja MCP

Este repositório contém um plugin do Binary Ninja, um servidor MCP e uma ponte que permitem a integração perfeita das capacidades do Binary Ninja com o seu cliente de LLM favorito.

Recursos

• Integração perfeita e em tempo real entre o Binary Ninja e clientes MCP
• Fluxo de trabalho de engenharia reversa aprimorado com assistência de IA
• Suporte para todos os clientes MCP (Cline, Claude desktop, Roo Code, etc.)
• Abra vários binários e alterne o alvo ativo automaticamente

Exemplos

Resolvendo um Desafio de CTF

Confira este vídeo de demonstração no YouTube que usa a extensão para resolver um desafio de CTF.

Componentes

Este repositório contém dois componentes separados:

1. Um plugin do Binary Ninja que fornece um servidor MCP que expõe as capacidades do Binary Ninja por meio de endpoints HTTP. Isso pode ser usado com qualquer cliente que implemente o protocolo MCP.
2. Um componente de ponte MCP separado que conecta seu cliente MCP favorito ao servidor MCP do Binary Ninja.

Pré-requisitos

• Binary Ninja
• Python 3.12+
• Cliente MCP (aqueles com suporte a configuração automática estão listados abaixo)

Instalação

Cliente MCP

Instale o cliente MCP antes de instalar o Binary Ninja MCP para que os clientes MCP possam ser configurados automaticamente. Atualmente, oferecemos suporte à configuração automática para estes clientes MCP:

1. Cline (recomendado)
2. Roo Code
3. Claude Desktop (recomendado)
4. Cursor
5. Windsurf
6. Claude Code
7. LM Studio

Instalação da Extensão

Após a instalação do cliente MCP, você pode instalar o servidor MCP usando o Gerenciador de Plugins do Binary Ninja ou manualmente. Ambos os métodos suportam a configuração automática de clientes MCP.

Se o seu cliente MCP não estiver configurado, você deve instalá-lo primeiro e depois tentar reinstalar a extensão.

Gerenciador de Plugins do Binary Ninja

Você pode instalar a extensão através do Gerenciador de Plugins do Binary Ninja (Plugins > Manage Plugins).

Instalação Manual

Para instalar manualmente a extensão, este repositório pode ser copiado para a pasta de plugins do Binary Ninja.

[Opcional] Configuração Manual do Cliente MCP

Você NÃO precisa configurar isso manualmente se usar um cliente MCP suportado e seguir os passos de instalação anteriores.

Você também pode gerenciar entradas de clientes MCP pela linha de comando:

python scripts/mcp_client_installer.py --install    # auto setup supported MCP clients
python scripts/mcp_client_installer.py --uninstall  # remove entries and delete `.mcp_auto_setup_done`
python scripts/mcp_client_installer.py --config     # print a generic JSON config snippet

Usando o pacote npm (Recomendado)

A maneira recomendada de configurar o cliente MCP é usando o pacote npm oficial:

npx -y binary-ninja-mcp

Para clientes MCP, use esta configuração:

{
  "mcpServers": {
    "binary-ninja-mcp": {
      "command": "npx",
      "args": ["-y", "binary-ninja-mcp", "--host", "localhost", "--port", "9009"]
    }
  }
}

Ou se instalado globalmente:

{
  "mcpServers": {
    "binary-ninja-mcp": {
      "command": "binary-ninja-mcp",
      "args": ["--host", "localhost", "--port", "9009"]
    }
  }
}

Usando a Ponte Python (Legado)

Para outros clientes MCP, use a ponte Python diretamente:

{
    "mcpServers": {
        "binary_ninja_mcp": {
            "command": "/ABSOLUTE/PATH/TO/Binary Ninja/plugins/repositories/community/plugins/fosdickio_binary_ninja_mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/Binary Ninja/plugins/repositories/community/plugins/fosdickio_binary_ninja_mcp/bridge/binja_mcp_bridge.py"
            ]
        }
    }
}

Nota: Substitua /ABSOLUTE/PATH/TO pelo caminho absoluto real do diretório do seu projeto. O interpretador Python do ambiente virtual deve ser usado para acessar as dependências instaladas.

Uso

1. Abra o Binary Ninja e carregue um binário
2. Clique no botão mostrado no canto inferior esquerdo
3. Comece a usá-lo através do seu cliente MCP

Agora você pode começar a fazer perguntas aos LLMs sobre o binário (ou binários) atualmente aberto. Exemplos de prompts:

Desafios de CTF

You're the best CTF player in the world. Please solve this reversing CTF challenge in the <folder_name> folder using Binary Ninja. Rename ALL the function and the variables during your analyzation process (except for main function) so I can better read the code. Write a python solve script if you need. Also, if you need to create struct or anything, please go ahead. Reverse the code like a human reverser so that I can read the decompiled code that analyzed by you.

Análise de Malware

Your task is to analyze an unknown file which is currently open in Binary Ninja. You can use the existing MCP server called "binary_ninja_mcp" to interact with the Binary Ninja instance and retrieve information, using the tools made available by this server. In general use the following strategy:

- Start from the entry point of the code
- If this function call others, make sure to follow through the calls and analyze these functions as well to understand their context
- If more details are necessary, disassemble or decompile the function and add comments with your findings
- Inspect the decompilation and add comments with your findings to important areas of code
- Add a comment to each function with a brief summary of what it does
- Rename variables and function parameters to more sensible names
- Change the variable and argument types if necessary (especially pointer and array types)
- Change function names to be more descriptive, using mcp_ as prefix.
- NEVER convert number bases yourself. Use the convert_number MCP tool if needed!
- When you finish your analysis, report how long the analysis took
- At the end, create a report with your findings.
- Based only on these findings, make an assessment on whether the file is malicious or not.

Capacidades Suportadas

A tabela a seguir lista as funções MCP disponíveis para uso:

Função	Descrição
decompile_function	Descompilar uma função específica pelo nome e retornar código semelhante a HLIL com endereços.
get_il(name_or_address, view, ssa)	Obter IL para uma função em hlil, mlil, ou llil (SSA suportado para MLIL/LLIL).
define_types	Adicionar definições de tipo a partir de uma definição de tipo em string C.
delete_comment	Excluir o comentário em um endereço específico.
delete_function_comment	Excluir o comentário de uma função.
declare_c_type(c_declaration)	Criar/atualizar um tipo local a partir de uma única declaração C.
format_value(address, text, size)	Converter um valor e anotá-lo em um endereço no BN (adiciona um comentário).
function_at	Recuperar o nome da função à qual o endereço pertence.
fetch_disassembly	Obter a representação em assembly de uma função pelo nome ou endereço.
get_entry_points()	Listar o(s) ponto(s) de entrada do binário carregado.
get_binary_status	Obter o status atual do binário carregado.
get_comment	Obter o comentário em um endereço específico.
get_function_comment	Obter o comentário de uma função.
get_user_defined_type	Recuperar a definição de um tipo definido pelo usuário (struct, enumeração, typedef, union).
get_xrefs_to(address)	Obter todas as referências cruzadas (código e dados) para um endereço.
get_data_decl(name_or_address, length)	Retornar uma declaração semelhante a C e um hexdump para um símbolo de dados ou endereço.
hexdump_address(address, length)	Hexdump de texto em um endereço. length < 0 lê o tamanho definido exato se disponível.
hexdump_data(name_or_address, length)	Hexdump pelo nome do símbolo de dados ou endereço. length < 0 lê o tamanho definido exato se disponível.
get_xrefs_to_enum(enum_name)	Obter usos relacionados a uma enumeração (corresponde a constantes de membros no código).
get_xrefs_to_field(struct_name, field_name)	Obter todas as referências cruzadas para um campo de struct nomeado.
get_xrefs_to_struct(struct_name)	Obter xrefs/usos relacionados a um struct (membros, globais, referências de código).
get_xrefs_to_type(type_name)	Obter xrefs/usos relacionados a um struct/tipo (globais, referências, correspondências HLIL).
get_xrefs_to_union(union_name)	Obter xrefs/usos relacionados a uma union (membros, globais, referências de código).
get_stack_frame_vars(function_identifier)	Obter informações de variáveis do quadro de pilha para uma função (nomes, deslocamentos, tamanhos, tipos).
get_type_info(type_name)	Resolver um tipo e retornar declaração, tipo e membros.
get_callers(identifiers)	Listar chamadores mais locais de chamada para um ou mais identificadores de função.
get_callees(identifiers)	Listar chamados mais locais de chamada para um ou mais identificadores de função.
make_function_at(address, platform)	Criar uma função em um endereço. platform opcional; use default para escolher o padrão BinaryView/plataforma.
list_platforms()	Listar todos os nomes de plataforma disponíveis.
list_binaries()	Listar binários gerenciados/abertos com ids e sinalizador ativo.
select_binary(view)	Selecionar binário ativo por id ou nome de arquivo.
list_all_strings()	Listar todas as strings (sem paginação; agrega todas as páginas).
list_classes	Listar todos os nomes de namespace/classe no programa.
list_data_items	Listar rótulos de dados definidos e seus valores.
list_exports	Listar funções/símbolos exportados.
list_imports	Listar símbolos importados no programa.
list_local_types(offset, count)	Listar tipos locais no banco de dados atual (nome/tipo/decl).
list_methods	Listar todos os nomes de funções no programa.
list_namespaces	Listar todos os namespaces não globais no programa.
list_segments	Listar todos os segmentos de memória no programa.
list_strings(offset, count)	Listar todas as strings no banco de dados (paginado).
list_strings_filter(offset, count, filter)	Listar strings correspondentes (paginado, filtrado por substring).
rename_data	Renomear um rótulo de dados no endereço especificado.
rename_function	Renomear uma função pelo seu nome atual para um novo nome definido pelo usuário.
rename_single_variable	Renomear uma única variável local dentro de uma função.
rename_multi_variables	Renomear em lote múltiplas variáveis locais em uma função (mapeamento ou pares).
set_local_variable_type(function_address, variable_name, new_type)	Definir o tipo de uma variável local.
retype_variable	Redefinir o tipo de uma variável dentro de uma determinada função.
search_functions_by_name	Pesquisar funções cujo nome contém a substring fornecida.
search_types(query, offset, count)	Pesquisar tipos locais por substring (nome/decl).
set_comment	Definir um comentário em um endereço específico.
set_function_comment	Definir um comentário para uma função.
set_function_prototype(name_or_address, prototype)	Definir o protótipo de uma função pelo nome ou endereço.
patch_bytes(address, data, save_to_file)	Aplicar patch em bytes brutos em um endereço (nível de byte, não assembly). Pode aplicar patch em instruções inteiras fornecendo seu bytecode. Endereço: hex (ex.: "0x401000") ou decimal. Dados: string hex (ex.: "90 90"). save_to_file (padrão True) salva no disco e re-assina no macOS.

Estes são a lista de endpoints HTTP que podem ser chamados:

• /allStrings: Todas as strings em uma resposta.
• /formatValue?address=<addr>&text=<value>&size=<n>: Converte e define um comentário em um endereço.
• /getXrefsTo?address=<addr>: Referências cruzadas para o endereço (código+dados).
• /getDataDecl?name=<symbol>|address=<addr>&length=<n>: JSON com string no estilo de declaração e um hexdump para um símbolo de dados ou endereço. Chaves: address, name, size, type, decl, hexdump. length < 0 lê o tamanho definido exato, se disponível.
• /hexdump?address=<addr>&length=<n>: Hexdump de texto alinhado ao endereço; length < 0 lê o tamanho definido exato, se disponível.
• /hexdumpByName?name=<symbol>&length=<n>: Hexdump de texto por nome de símbolo. Reconhece rótulos automáticos do BN como data_<hex>, byte_<hex>, word_<hex>, dword_<hex>, qword_<hex>, off_<hex>, unk_<hex> e endereços hexadecimais simples.
• /makeFunctionAt?address=<addr>&platform=<name|default>: Cria uma função em um endereço (idempotente se já existir). platform=default usa o padrão da BinaryView/plataforma.
• /platforms: Lista todos os nomes de plataformas disponíveis.
• /binaries ou /views: Lista binários gerenciados/abertos com IDs e flag ativo.
• /selectBinary?view=<id|filename>: Seleciona o binário ativo para operações subsequentes.
• /data?offset=<n>&limit=<m>&length=<n>: Itens de dados definidos com pré-visualizações. length controla os bytes lidos por item (limitado ao tamanho definido). O comportamento padrão lê o tamanho definido exato quando disponível; length=-1 força o tamanho exato.
• /getXrefsToEnum?name=<enum>: Usos de enumeração correspondendo constantes de membros.
• /getXrefsToField?struct=<name>&field=<name>: Referências cruzadas para campo de struct.
• /getXrefsToType?name=<type>: Referências cruzadas/usos relacionados a um nome de struct/tipo.
• /getTypeInfo?name=<type>: Resolve um tipo e retorna declaração e detalhes.
• /getXrefsToUnion?name=<union>: Referências cruzadas/usos de união (membros, globais, referências).
• /getStackFrameVars?name=<function>|address=<addr>: Obtém informações de variáveis de quadro de pilha para uma função.
• /getCallers?identifiers=<name|addr>[,...]: Retorna resumos de chamadores (funções, locais de chamada, trechos HLIL/IL) para um ou mais identificadores. Aceita parâmetros de consulta identifiers, identifier, names ou addresses.
• /getCallees?identifiers=<name|addr>[,...]: Retorna resumos de chamados com o mesmo esquema de /getCallers, detalhando cada destino de chamada de saída por identificador de solicitação.
• /localTypes?offset=<n>&limit=<m>: Lista tipos locais.
• /strings?offset=<n>&limit=<m>: Strings paginadas.
• /strings/filter?offset=<n>&limit=<m>&filter=<substr>: Strings filtradas.
• /searchTypes?query=<substr>&offset=<n>&limit=<m>: Pesquisa tipos locais por substring.
• /patch ou /patchBytes?address=<addr>&data=<hex>&save_to_file=<bool>: Aplica patch em bytes brutos em um endereço (nível de byte, não assembly). Pode aplicar patch em instruções inteiras fornecendo seu bytecode. Endereço: hexadecimal (ex.: "0x401000") ou decimal. Dados: string hexadecimal (ex.: "90 90"). save_to_file (padrão True) salva no disco e re-assina no macOS.
• /renameVariables: Renomeia em lote variáveis locais em uma função. Parâmetros:
  • Função: um de functionAddress, address, function, functionName ou name.
  • Forneça renomeações por meio de um de:
    • renames: Array JSON de objetos {old, new}
    • mapping: Objeto JSON de old->new
    • pairs: string compacta old1:new1,old2:new2 Retorna resultados por item mais totais. A ordem é respeitada; pares posteriores podem referir-se a nomes novos anteriores.

Desenvolvimento

Qualidade de Código

Este projeto usa Ruff para linting e formatação. A configuração está em ruff.toml.

Executando Ruff Manualmente

Verifique problemas:

ruff check .

Corrija problemas automaticamente:

ruff check --fix .

Verifique problemas de formatação:

ruff format --check .

Formate o código:

ruff format .

GitHub Actions

Um fluxo de trabalho do GitHub Action (.github/workflows/lint-format.yml) executa Ruff automaticamente em:

• Cada push para o branch main
• Cada pull request direcionado ao branch main

O fluxo de trabalho falhará se houver erros de linting ou problemas de formatação, garantindo a qualidade do código no CI.

Contribuindo

Contribuições são bem-vindas. Sinta-se à vontade para enviar um pull request.