BinAssist-MCP

BinAssistMCP

重要

计划归档： 随着 Binary Ninja 推出内置的原生 MCP 服务，BinAssistMCP 计划归档。原生支持无需维护单独的 MCP 集成，并能与 Binary Ninja 本身保持同步。请在安装的版本提供原生 MCP 服务后使用该服务。本仓库将继续保留，供参考。

为 Binary Ninja 提供全面的模型上下文协议（MCP）服务，具备 AI 驱动的逆向工程能力

概要

BinAssistMCP 是 Binary Ninja 与 Claude 等大语言模型（LLM）之间的强大桥梁，通过模型上下文协议（MCP）提供全面的逆向工程工具。它通过服务器发送事件（SSE）和可流式传输的 HTTP 传输方式，开放 Binary Ninja 的高级功能，从而实现 AI 辅助的二进制分析。

主要功能

• 符合 MCP 2025-11-25 规范： 全面支持工具注释、资源和提示词
• 双传输方式： 支持 SSE（服务器发送事件）和可流式传输的 HTTP
• 45 个整合工具： 精简的 Binary Ninja API 封装，采用统一的工具设计
• 8 个 MCP 资源： 可浏览、可缓存的二进制元数据
• 7 个引导式提示词： 针对常见逆向工程任务预构建的工作流
• 多二进制会话： 并发分析多个二进制文件，并智能管理上下文
• 上下文丰富的代码输出： 在代码结果中嵌入函数签名和 Binary Ninja 注释
• 对分析安全的查询： 获取代码时使用已加载的 IL，不会强制触发全局重新分析
• 与会话无关的发现： 直接调用工具即可发现已打开的 Binary Ninja 视图，无需事先调用列表工具
• 非阻塞式打开二进制文件： 异步打开大型二进制文件和 .bndb 数据库，并可轮询操作状态
• 线程安全： 基于 RLock 的并发访问同步机制
• 自动集成： 无缝集成 Binary Ninja 插件，支持自动启动

使用场景

• AI 辅助逆向工程： 利用大模型进行智能代码分析和编写文档
• 协议分析： 跟踪网络数据流并重建协议结构
• 漏洞研究： 通过引导式工作流系统地开展安全审计
• 自动化二进制分析： 使用自然语言编写复杂的分析工作流脚本
• 代码理解： 生成全面的文档和说明

---

架构

src/binassist_mcp/
├── server.py        # FastMCP server - SSE/Streamable HTTP transport, tool registration
├── tools.py         # Binary Ninja API wrapper - 45 MCP tools
├── plugin.py        # Binary Ninja plugin integration
├── context.py       # Thread-safe multi-binary session management
├── config.py        # Pydantic configuration with Binary Ninja settings
├── prompts.py       # 7 guided workflow prompts
├── resources.py     # 8 MCP resource definitions
├── cache.py         # Cache primitives (not currently connected to MCP tools)
├── tasks.py         # Task lifecycle support (tool dispatch is not yet implemented)
├── logging.py       # Binary Ninja logging integration
└── utils.py         # Utility functions

__init__.py          # Plugin entry point (root level)

---

工具（共 45 个）

BinAssistMCP 提供 45 个工具，按功能类别组织。工具包含 MCP 注释（readOnlyHint、idempotentHint），帮助客户端做出明智的决策。

二进制文件管理

工具	描述
list_binaries	与 Binary Ninja 同步，并列出所有已加载的二进制文件
get_binary_info	检查分析状态和元数据
get_binary_status	按操作 ID、路径或名称轮询已排队的打开操作，并报告分析进度
open_binary	将打开二进制文件或 .bndb 的操作加入队列，不会阻塞；原始二进制文件需要指定目标 bndb_path
update_analysis_and_wait	强制更新分析并等待完成
export_program	将已修补的二进制文件或 Binary Ninja 数据库导出到磁盘

默认情况下，open_binary 会验证路径、安排 Binary Ninja 执行打开操作，并立即返回带有 status="opening" 的 operation_id。轮询 get_binary_status(operation_id)，直到返回 ready 或 failed。就绪后，其 name 字段即为传递给分析工具的最终上下文名称。针对同一路径的并发请求会复用正在进行的操作。仅在明确需要旧版阻塞行为时，才设置 wait_for_analysis=true。

代码分析（整合）

工具	描述
get_code	读取可安全分析的代码，包含签名和注释；支持 decompile、hlil、mlil、llil、disasm 和 pseudo_c
get_function_low_level_il	获取函数的 Low-Level IL
get_function_signature	生成函数的原生掩码字节签名
analyze_function	全面的函数分析，包含控制流和复杂度指标
get_basic_blocks	获取基本块信息，用于控制流分析
get_function_stack_layout	获取栈帧布局及变量偏移

get_code 的行为

get_code 是只读查询。它不会清除 analysis_skipped、请求生成 IL，也不会运行全局分析。对于 format="decompile"，如果已有 HLIL，则返回已加载的 HLIL；否则依次回退到 MLIL、LLIL，最后返回与指令对齐的反汇编。需要新分析时，请显式使用 update_analysis_and_wait。

code 字符串以当前函数签名开头，并包含函数级和指令级的 Binary Ninja 注释。响应包含：

• function 和 address：解析后的函数标识
• format：请求的格式
• actual_format：实际返回的表示形式；如果明确请求的 IL 不可用，则为 null
• fallback_used：decompile 是否使用了较低级别的表示形式
• code：渲染后的代码、签名和注释
• note：存在回退时提供，说明回退原因及返回的内容

交叉引用（整合）

工具	描述
xrefs	统一的交叉引用；direction 可设为 to、from 或 both；还可选择包含调用关系

注释（整合）

工具	描述
comments	统一的注释管理 - 操作：get、set、list、remove、set_function

变量（整合）

工具	描述
variables	统一的变量管理 - 操作：list、create、rename、set_type；rename 支持通过 scope 区分局部变量和全局变量

类型（整合）

工具	描述
types	统一的类型管理 - 操作：create、create_enum、create_typedef、create_class、add_member、info、list
get_classes	列出所有类和结构体

函数发现

工具	描述
get_functions	列出所有函数及其元数据
search_functions_by_name	按名称模式查找函数
get_functions_advanced	按大小、复杂度和参数进行高级筛选
search_functions_advanced	多目标搜索（名称、注释、调用、变量）
get_function_statistics	获取所有函数的综合统计信息

符号管理

工具	描述
rename_symbol	重命名函数和数据变量
batch_rename	在一次操作中重命名多个符号
get_namespaces	列出命名空间和符号组织结构

二进制文件信息

工具	描述
get_imports	按模块分组的导入表
get_exports	包含符号信息的导出表
get_strings	分页提取字符串
search_strings	按模式搜索字符串
get_segments	内存段布局
get_sections	二进制文件节信息
get_entry_points	列出所有二进制文件入口点

数据分析

工具	描述
create_data_var	在指定地址定义数据变量
get_data_vars	列出所有已定义的数据变量
get_data_at	读取并分析原始数据
search_bytes	在二进制文件中搜索字节模式

修补

工具	描述
patch_bytes	在指定地址修补二进制文件中的原始字节
assemble_code	在指定地址汇编指令文本，并可选择进行修补

导航与书签

工具	描述
get_current_address	获取当前光标位置及上下文
get_current_function	识别当前地址处的函数
bookmarks	统一的书签管理 - 操作：list、set、remove

任务管理（实验性）

工具	描述
start_task	创建占位的后台任务记录；目前尚未实现 tool_name 分发
get_task_status	检查异步操作的状态
list_tasks	列出所有待处理／正在运行的任务
cancel_task	取消正在运行的任务

这些 API 目前仅用于执行任务生命周期管理，不会在后台执行指定的 MCP 工具。

---

MCP 资源（共 8 项）

资源提供可浏览、可缓存的数据，客户端无需调用工具即可访问。

URI 模式	描述
binassist://{filename}/triage_summary	二进制文件完整概览
binassist://{filename}/functions	包含元数据的所有函数
binassist://{filename}/imports	导入表
binassist://{filename}/exports	导出表
binassist://{filename}/strings	字符串表
binja://{filename}/info	二进制元数据（架构、平台、入口点）
binja://{filename}/segments	带权限信息的内存段
binja://{filename}/sections	二进制节

---

MCP 提示词（共 7 项）

预置提示词可引导大模型执行结构化分析工作流。

提示词	参数	描述
analyze_function	function_name、filename	全面的函数分析工作流
identify_vulnerability	function_name、filename	安全审计清单（内存安全、输入验证、加密）
document_function	function_name、filename	生成 Doxygen 风格的文档
trace_data_flow	address、filename	跟踪数据依赖关系和污点传播
compare_functions	func1、func2、filename	对比两个函数以分析相似性
reverse_engineer_struct	address、filename	根据使用模式还原结构定义
trace_network_data	filename	跟踪 POSIX/Winsock 的 send/recv，以分析协议

示例：网络协议分析

trace_network_data 提示词可引导网络通信分析：

1. 识别网络函数：查找 POSIX（send/recv/sendto/recvfrom）和 Winsock（WSASend/WSARecv）调用
2. 跟踪调用栈：将应用程序处理函数向下映射到网络 I/O
3. 分析缓冲区：识别协议结构（标头、长度字段、TLV 编码）
4. 重建协议：为消息格式生成 C 结构体定义
5. 安全评估：检查缓冲区溢出、整数问题和信息泄露

---

安装

前提条件

• Binary Ninja：版本 5000 或更高
• Python：3.10+（通常随 Binary Ninja 一起捆绑，并且是固定版本 MCP SDK 的必需项）
• 平台：Windows、macOS 或 Linux

注意：Windows 用户请从此处开始：Windows 上的 BinAssistMCP

选项 1：Binary Ninja 插件管理器（推荐）

1. 打开 Binary Ninja
2. 前往 工具 → 管理插件
3. 搜索“BinAssistMCP”
4. 点击 安装
5. 重启 Binary Ninja

选项 2：手动安装

# Clone the repository
git clone https://github.com/symgraph/BinAssistMCP.git
cd BinAssistMCP

# Install dependencies
pip install -r requirements.txt

复制到 Binary Ninja 插件目录：

平台	路径
Windows	%APPDATA%\Binary Ninja\plugins\
macOS	~/Library/Application Support/Binary Ninja/plugins/
Linux	~/.binaryninja/plugins/

---

配置

Binary Ninja 设置

打开 Edit → Preferences → binassistmcp：

设置	默认值	说明
server.host	localhost	服务绑定地址
server.port	8000	服务端口
server.transport	streamablehttp	传输方式：streamablehttp 或 sse
binary.max_binaries	10	最大并发二进制文件数
plugin.auto_startup	true	加载文件时自动启动服务

环境变量

export BINASSISTMCP_SERVER__HOST=localhost
export BINASSISTMCP_SERVER__PORT=8000
export BINASSISTMCP_SERVER__TRANSPORT=streamablehttp
export BINASSISTMCP_BINARY__MAX_BINARIES=10

---

使用方法

启动服务

通过 Binary Ninja 菜单：

1. Tools → BinAssistMCP → Start Server
2. 检查日志面板，确认显示：BinAssistMCP server started on http://localhost:8000

自动启动： Binary Ninja 加载文件时会自动启动服务（可配置）。

连接 MCP 客户端

Streamable HTTP（默认）：

http://localhost:8000/mcp

服务器发送事件：

http://localhost:8000/sse

Claude Desktop 配置

将以下内容添加到 Claude Desktop MCP 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "binassist": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

---

集成示例

大多数特定于二进制文件的工具都需要在 filename 中提供上下文名称。list_binaries 会返回这些名称，但这不是初始化的必要条件：直接按文件名调用时，必要情况下会自动从 Binary Ninja 刷新上下文。

基本函数分析

User: "Analyze the main function and explain what it does"

Claude uses:
1. list_binaries() - obtain the context filename
2. get_functions(filename='sample.bndb') - find main
3. get_code(filename='sample.bndb', function_name_or_address='main', format='decompile')
4. xrefs(filename='sample.bndb', address_or_name='main', direction='from')
5. analyze_function(filename='sample.bndb', function_name_or_address='main')

漏洞研究

User: "Find buffer overflow vulnerabilities in input handling functions"

Claude uses:
1. search_functions_advanced(filename='sample.bndb', search_term='strcpy', search_in='calls')
2. get_code(filename='sample.bndb', function_name_or_address='handler', format='decompile')
3. variables(filename='sample.bndb', action='list', function_name_or_address='handler')
4. comments(filename='sample.bndb', action='set', address='0x401000', text='Unchecked copy')

协议逆向工程

User: "Analyze the network protocol used by this binary"

Claude uses the trace_network_data prompt:
1. Identifies send/recv call sites
2. Traces data flow from handlers to network I/O
3. Reconstructs message structures
4. Checks for network vulnerabilities

---

故障排除

服务问题

问题	解决方案
服务无法启动	检查端口 8000 是否可用，并确认依赖项无误
连接被拒绝	确认服务正在运行，并检查防火墙设置
请求的 IL 不可用	运行 update_analysis_and_wait，然后重试 get_code
二进制文件名称被拒绝	调用 list_binaries 并使用其返回的上下文名称

性能

• 内存用量：调低 max_binaries 设置
• 代码检索：get_code 会立即返回已加载的分析结果；若无结果，则回退处理，而不会触发分析

日志

查看 Binary Ninja 的日志面板以获取详细错误信息。

---

贡献

1. Fork 此仓库
2. 创建功能分支
3. 遵循现有代码规范（Pydantic 模型、类型提示、文档字符串）
4. 使用多种二进制文件类型进行测试
5. 提交拉取请求

---

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。