Binary Ninja MCP

Binary Ninja MCP

此仓库包含一个 Binary Ninja 插件、MCP 服务和桥接组件，可将 Binary Ninja 的功能与您喜爱的 LLM 客户端无缝集成。

功能

• 在 Binary Ninja 与 MCP 客户端之间实现实时无缝集成
• 借助 AI 助力改进逆向工程工作流
• 支持所有 MCP 客户端（Cline、Claude 桌面版、Roo Code 等）
• 打开多个二进制文件并自动切换当前目标

示例

解决 CTF 挑战

请查看此 YouTube 演示视频，了解如何使用此扩展解决 CTF 挑战。

组件

此仓库包含两个独立组件：

1. 一个 Binary Ninja 插件，用于提供 MCP 服务，通过 HTTP 端点公开 Binary Ninja 的功能。此服务可与任何实现了 MCP 协议的客户端搭配使用。
2. 一个独立的 MCP 桥接组件，用于将您喜爱的 MCP 客户端连接到 Binary Ninja MCP 服务。

前置条件

• Binary Ninja
• Python 3.12+
• MCP 客户端（下方列出了支持自动设置的客户端）

安装

MCP 客户端

请先安装 MCP 客户端，再安装 Binary Ninja MCP，以便自动设置 MCP 客户端。目前支持自动设置以下 MCP 客户端：

1. Cline（推荐）
2. Roo Code
3. Claude Desktop（推荐）
4. Cursor
5. Windsurf
6. Claude Code
7. LM Studio

安装扩展

安装 MCP 客户端后，您可以通过 Binary Ninja 插件管理器或手动安装 MCP 服务。两种方式都支持自动设置 MCP 客户端。

如果尚未配置 MCP 客户端，请先安装客户端，然后再尝试重新安装扩展。

Binary Ninja 插件管理器

您可以通过 Binary Ninja 的插件管理器（Plugins > Manage Plugins）安装扩展。

手动安装

如需手动安装扩展，可以将此仓库复制到 Binary Ninja 插件文件夹。

[可选] 手动设置 MCP 客户端

如果您使用受支持的 MCP 客户端并按照上述步骤安装，则无需手动设置。

您也可以通过命令行管理 MCP 客户端条目：

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

使用 npm 包（推荐）

推荐使用官方 npm 包设置 MCP 客户端：

npx -y binary-ninja-mcp

对于 MCP 客户端，请使用以下配置：

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

或者，如果已全局安装：

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

使用 Python 桥接组件（旧版）

对于其他 MCP 客户端，请直接使用 Python 桥接组件：

{
    "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"
            ]
        }
    }
}

注意：请将 /ABSOLUTE/PATH/TO 替换为项目目录的实际绝对路径。必须使用虚拟环境中的 Python 解释器才能访问已安装的依赖项。

使用方法

1. 打开 Binary Ninja 并加载一个二进制文件
2. 点击左下角显示的按钮
3. 开始通过 MCP 客户端使用

现在，您可以开始向 LLM 提问当前打开的二进制文件（或多个二进制文件）。提示词示例：

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.

恶意软件分析

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.

支持的功能

下表列出了可用的 MCP 函数：

功能	描述
decompile_function	按名称反编译指定函数，并返回带地址的类 HLIL 代码。
get_il(name_or_address, view, ssa)	获取函数的 hlil、mlil 或 llil 中间语言（MLIL/LLIL 支持 SSA）。
define_types	从 C 字符串类型定义中添加类型定义。
delete_comment	删除指定地址处的注释。
delete_function_comment	删除函数的注释。
declare_c_type(c_declaration)	根据单条 C 声明创建或更新本地类型。
format_value(address, text, size)	转换一个值，并在 BN 中为指定地址添加注释。
function_at	获取地址所属函数的名称。
fetch_disassembly	按函数名称或地址获取函数的汇编表示。
get_entry_points()	列出已加载二进制文件的入口点。
get_binary_status	获取已加载二进制文件的当前状态。
get_comment	获取指定地址处的注释。
get_function_comment	获取函数的注释。
get_user_defined_type	获取用户定义类型（结构体、枚举、typedef、联合体）的定义。
get_xrefs_to(address)	获取指向某个地址的所有交叉引用（代码和数据）。
get_data_decl(name_or_address, length)	返回数据符号或地址的类 C 声明和十六进制转储。
hexdump_address(address, length)	返回指定地址处的文本格式十六进制转储。length < 0 时，如果有可用的精确定义大小，则读取该大小的数据。
hexdump_data(name_or_address, length)	按数据符号名称或地址返回十六进制转储。length < 0 时，如果有可用的精确定义大小，则读取该大小的数据。
get_xrefs_to_enum(enum_name)	获取与枚举相关的用法（匹配代码中的成员常量）。
get_xrefs_to_field(struct_name, field_name)	获取指向指定结构体字段的所有交叉引用。
get_xrefs_to_struct(struct_name)	获取与结构体相关的交叉引用或用法（成员、全局变量、代码引用）。
get_xrefs_to_type(type_name)	获取与结构体或类型相关的交叉引用或用法（全局变量、引用、HLIL 匹配项）。
get_xrefs_to_union(union_name)	获取与联合体相关的交叉引用或用法（成员、全局变量、代码引用）。
get_stack_frame_vars(function_identifier)	获取函数的栈帧变量信息（名称、偏移量、大小、类型）。
get_type_info(type_name)	解析类型并返回其声明、种类和成员。
get_callers(identifiers)	列出一个或多个函数标识符的调用方及调用位置。
get_callees(identifiers)	列出一个或多个函数标识符的被调用方及调用位置。
make_function_at(address, platform)	在指定地址创建函数。platform 为可选项；使用 default 可选择 BinaryView/平台默认值。
list_platforms()	列出所有可用的平台名称。
list_binaries()	列出已管理或已打开的二进制文件及其 ID 和活动标记。
select_binary(view)	按 ID 或文件名选择活动二进制文件。
list_all_strings()	列出所有字符串（不分页；汇总所有页面）。
list_classes	列出程序中的所有命名空间/类名称。
list_data_items	列出已定义的数据标签及其值。
list_exports	列出导出的函数/符号。
list_imports	列出程序中导入的符号。
list_local_types(offset, count)	列出当前数据库中的本地类型（名称/种类/声明）。
list_methods	列出程序中的所有函数名称。
list_namespaces	列出程序中的所有非全局命名空间。
list_segments	列出程序中的所有内存段。
list_strings(offset, count)	列出数据库中的所有字符串（分页）。
list_strings_filter(offset, count, filter)	列出匹配的字符串（分页，并按子字符串筛选）。
rename_data	重命名指定地址处的数据标签。
rename_function	将函数当前名称重命名为新的用户定义名称。
rename_single_variable	重命名函数中的单个局部变量。
rename_multi_variables	批量重命名函数中的多个局部变量（使用映射或键值对）。
set_local_variable_type(function_address, variable_name, new_type)	设置局部变量的类型。
retype_variable	更改指定函数中变量的类型。
search_functions_by_name	搜索名称包含指定子字符串的函数。
search_types(query, offset, count)	按子字符串搜索本地类型（名称/声明）。
set_comment	在指定地址处设置注释。
set_function_comment	为函数设置注释。
set_function_prototype(name_or_address, prototype)	按名称或地址设置函数原型。
patch_bytes(address, data, save_to_file)	在指定地址修补原始字节（字节级，而非汇编）。提供指令的字节码即可修补整条指令。地址：十六进制（例如 "0x401000"）或十进制。数据：十六进制字符串（例如 "90 90"）。save_to_file（默认值为 True）会将更改保存到磁盘，并在 macOS 上重新签名。
以下是可调用的 HTTP 端点列表：

• /allStrings：在一个响应中返回所有字符串。
• /formatValue?address=<addr>&text=<value>&size=<n>：转换值，并在某个地址处设置注释。
• /getXrefsTo?address=<addr>：指向某个地址的交叉引用（代码和数据）。
• /getDataDecl?name=<symbol>|address=<addr>&length=<n>：返回 JSON，其中包含数据符号或地址的声明样式字符串和十六进制转储。键：address、name、size、type、decl、hexdump。如果 length < 0，且有可用的精确定义大小，则读取该大小。
• /hexdump?address=<addr>&length=<n>：在地址处对齐的文本十六进制转储；如果 length < 0，且有可用的精确定义大小，则读取该大小。
• /hexdumpByName?name=<symbol>&length=<n>：按符号名称获取文本十六进制转储。可识别 BN 自动标签，例如 data_<hex>、byte_<hex>、word_<hex>、dword_<hex>、qword_<hex>、off_<hex>、unk_<hex>，以及纯十六进制地址。
• /makeFunctionAt?address=<addr>&platform=<name|default>：在某个地址创建函数（如果已存在，则不会重复创建）。platform=default 使用 BinaryView／平台默认值。
• /platforms：列出所有可用的平台名称。
• /binaries 或 /views：列出受管理／已打开的二进制文件及其 ID 和活动状态。
• /selectBinary?view=<id|filename>：选择活动二进制文件，供后续操作使用。
• /data?offset=<n>&limit=<m>&length=<n>：列出已定义的数据项及其预览。length 控制每个数据项读取的字节数（上限为已定义大小）。默认行为是在有可用精确定义大小时读取该大小；length=-1 强制读取精确定义大小。
• /getXrefsToEnum?name=<enum>：按匹配的成员常量查找枚举的使用情况。
• /getXrefsToField?struct=<name>&field=<name>：查找指向结构体字段的交叉引用。
• /getXrefsToType?name=<type>：查找与结构体／类型名称相关的交叉引用／使用情况。
• /getTypeInfo?name=<type>：解析类型并返回声明和详细信息。
• /getXrefsToUnion?name=<union>：联合体的交叉引用／使用情况（成员、全局变量、引用）。
• /getStackFrameVars?name=<function>|address=<addr>：获取函数的栈帧变量信息。
• /getCallers?identifiers=<name|addr>[,...]：返回一个或多个标识符的调用者摘要（函数、调用点、HLIL／IL 片段）。接受 identifiers、identifier、names 或 addresses 查询参数。
• /getCallees?identifiers=<name|addr>[,...]：返回被调用者摘要，结构与 /getCallers 相同，详细列出每个请求标识符对应的所有外呼目标。
• /localTypes?offset=<n>&limit=<m>：列出本地类型。
• /strings?offset=<n>&limit=<m>：分页列出字符串。
• /strings/filter?offset=<n>&limit=<m>&filter=<substr>：筛选字符串。
• /searchTypes?query=<substr>&offset=<n>&limit=<m>：按子字符串搜索本地类型。
• /patch 或 /patchBytes?address=<addr>&data=<hex>&save_to_file=<bool>：在某个地址修补原始字节（字节级，不是汇编）。可通过提供指令的字节码修补整条指令。地址：十六进制（例如，"0x401000"）或十进制。数据：十六进制字符串（例如，"90 90"）。save_to_file（默认值为 True）会将更改保存到磁盘，并在 macOS 上重新签名。
• /renameVariables：批量重命名函数中的局部变量。参数：
  • 函数：以下参数之一：functionAddress、address、function、functionName 或 name。
  • 使用以下任一方式提供重命名内容：
    • renames：由 {old, new} 对象组成的 JSON 数组
    • mapping：old->new 形式的 JSON 对象
    • pairs：紧凑字符串 old1:new1,old2:new2 返回逐项结果及总数。顺序会被遵循；后续条目可以引用先前的新名称。

开发

代码质量

本项目使用 Ruff 进行代码检查和格式化。配置位于 ruff.toml。

手动运行 Ruff

检查问题：

ruff check .

自动修复问题：

ruff check --fix .

检查格式问题：

ruff format --check .

格式化代码：

ruff format .

GitHub Actions

GitHub Actions 工作流（.github/workflows/lint-format.yml）会在以下情况下自动运行 Ruff：

• 每次推送到 main 分支时
• 每个以 main 分支为目标的拉取请求

如果存在代码检查错误或格式问题，工作流将失败，以确保 CI 中的代码质量。

参与贡献

欢迎贡献。请随时提交拉取请求。