symgraph/BinAssistMCP

# BinAssistMCP ## 概述 BinAssistMCP 是连接 Binary Ninja 与 Claude 等大型语言模型 (LLM) 的强大桥梁，通过模型上下文协议 (MCP) 提供全面的逆向工程工具。它通过 Server-Sent Events (SSE) 和 Streamable HTTP 传输方式暴露 Binary Ninja 的高级功能，从而实现 AI 辅助的二进制分析。 ### 核心特性 - **兼容 MCP 2025-11-25 标准**：全面支持工具注解、资源和提示词 - **双重传输支持**：支持 SSE (Server-Sent Events) 和 Streamable HTTP 传输 - **39 个整合工具**：具有统一工具设计的简化版 Binary Ninja API 封装 - **8 个 MCP 资源**：可浏览、可缓存的二进制元数据 - **7 个引导式提示词**：针对常见逆向工程任务的预构建工作流 - **多二进制会话**：并发分析多个二进制文件，并具有智能上下文管理 - **分析缓存**：带有二进制作用域失效机制的 LRU 缓存，可提升性能 - **异步任务支持**：长时间运行的操作采用非阻塞执行 - **线程安全**：基于 RLock 的同步机制，支持并发访问 - **自动集成**：无感集成的 Binary Ninja 插件，支持自动启动功能 ### 应用场景 - **AI 辅助逆向工程**：利用 LLM 进行智能代码分析和文档编写 - **协议分析**：追踪网络数据流并重构协议结构 - **漏洞研究**：通过引导式工作流进行系统性安全审计 - **自动化二进制分析**：使用自然语言编写复杂的分析脚本 - **代码理解**：生成详尽的文档和解释 ## 架构 ``` src/binassist_mcp/ ├── server.py # FastMCP server - SSE/Streamable HTTP transport, tool registration ├── tools.py # Binary Ninja API wrapper - 39 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 # LRU analysis cache with invalidation ├── tasks.py # Async task manager for long-running operations ├── logging.py # Binary Ninja logging integration └── utils.py # Utility functions __init__.py # Plugin entry point (root level) ``` ## 工具 (共 39 个) BinAssistMCP 提供 39 个按功能分类的工具。工具包含 MCP 注解（`readOnlyHint`, `idempotentHint`）以帮助客户端做出明智决策。 ### 二进制管理 | 工具 | 描述 | |------|-------------| | `list_binaries` | 列出所有已加载的二进制文件 | | `get_binary_info` | 检查分析状态和元数据 | | `update_analysis_and_wait` | 强制更新分析并等待完成 | ### 代码分析 (整合版) | 工具 | 描述 | |------|-------------| | `get_code` | **统一代码检索** - 支持格式：`decompile`, `hlil`, `mlil`, `llil`, `disasm`, `pseudo_c` | | `get_function_low_level_il` | 获取函数的低级中间语言 (IL) | | `analyze_function` | 包含控制流和复杂度指标的综合函数分析 | | `get_basic_blocks` | 获取用于控制流分析的基本块信息 | | `get_function_stack_layout` | 获取包含变量偏移量的栈帧布局 | ### 交叉引用 (整合版) | 工具 | 描述 | |------|-------------| | `xrefs` | **统一交叉引用** - 操作：`refs_to`, `refs_from`, `call_graph` | ### 注释 (整合版) | 工具 | 描述 | |------|-------------| | `comments` | **统一注释管理** - 操作：`get`, `set`, `list`, `remove`, `set_function` | ### 变量 (整合版) | 工具 | 描述 | |------|-------------| | `variables` | **统一变量管理** - 操作：`list`, `create`, `rename`, `set_type` | ### 类型 (整合版) | 工具 | 描述 | |------|-------------| | `types` | **统一类型管理** - 操作：`create`, `create_enum`, `create_typedef`, `create_class`, `add_member`, `get_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` | 在二进制中搜索字节模式 | ### 导航与书签 | 工具 | 描述 | |------|-------------| | `get_current_address` | 获取当前光标位置及上下文 | | `get_current_function` | 识别当前地址所在的函数 | | `bookmarks` | **统一书签管理** - 操作：`list`, `set`, `remove` | ### 任务管理 | 工具 | 描述 | |------|-------------| | `start_task` | 启动异步后台任务 | | `get_task_status` | 检查异步操作的状态 | | `list_tasks` | 列出所有待处理/运行中的任务 | | `cancel_task` | 取消正在运行的任务 | ## 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 个) 预构建的提示词可引导 LLM 完成结构化的分析工作流。 | 提示词 | 参数 | 描述 | |--------|-----------|-------------| | `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**：4000 或更高版本 - **Python**：3.8+（通常随 Binary Ninja 附带） - **平台**：Windows、macOS 或 Linux 注意：Windows 用户应首先阅读：[BinAssistMCP on Windows](binassistmcp-on-windows.md) ### 选项 1：Binary Ninja 插件管理器（推荐） 1. 打开 Binary Ninja 2. 导航至 **Tools** → **Manage Plugins** 3. 搜索 "BinAssistMCP" 4. 点击 **Install** 5. 重启 Binary Ninja ### 选项 2：手动安装 ``` # 克隆 repository git clone https://github.com/jtang613/BinAssistMCP.git cd BinAssistMCP # 安装 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` | `9090` | 服务器端口 | | `server.transport` | `streamablehttp` | 传输方式：`streamablehttp` 或 `sse` | | `binary.max_binaries` | `10` | 最大并发二进制数 | | `plugin.auto_startup` | `true` | 文件加载时自动启动服务器 | ### 环境变量 ``` export BINASSISTMCP_SERVER__HOST=localhost export BINASSISTMCP_SERVER__PORT=9090 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:9090` **自动启动：** 当 Binary Ninja 加载文件时，服务器会自动启动（可配置）。 ### 连接 MCP 客户端 **Streamable HTTP (默认)：** ``` http://localhost:9090/mcp ``` **Server-Sent Events：** ``` http://localhost:9090/sse ``` ### Claude Desktop 配置 添加到您的 Claude Desktop MCP 配置 (`claude_desktop_config.json`)： ``` { "mcpServers": { "binassist": { "url": "http://localhost:9090/mcp" } } } ``` ## 集成示例 ### 基本函数分析 ``` User: "Analyze the main function and explain what it does" Claude uses: 1. get_functions() - find main 2. get_code(format='decompile') - get readable code 3. xrefs(action='refs_from') - find called functions 4. analyze_function() - get complexity metrics ``` ### 漏洞研究 ``` User: "Find buffer overflow vulnerabilities in input handling functions" Claude uses: 1. search_functions_advanced(search_in='calls') - find memcpy/strcpy callers 2. get_code(format='decompile') - examine implementations 3. variables(action='list') - check buffer sizes 4. comments(action='set') - document findings ``` ### 协议逆向工程 ``` 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 ``` ## 故障排除 ### 服务器问题 | 问题 | 解决方案 | |---------|----------| | 服务器无法启动 | 检查端口 9090 是否可用，验证依赖项 | | 连接被拒绝 | 确保服务器正在运行，检查防火墙设置 | | 工具返回错误 | 等待分析完成，验证二进制文件已加载 | ### 性能 - **反编译速度慢**：结果已缓存；第二次请求会更快 - **内存使用**：降低 `max_binaries` 设置 - **长时间操作**：使用 `get_task_status` 检查任务状态 ### 日志 请查看 Binary Ninja 的日志面板以获取详细的错误信息。 ## 贡献 1. Fork 本仓库 2. 创建一个功能分支 3. 遵循现有的代码模式（Pydantic 模型、类型提示、文档字符串） 4. 使用多种二进制类型进行测试 5. 提交 Pull Request ## 许可证 本项目采用 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。

标签：API 包装器, Binary Analysis, Binary Ninja, Claude, CVE检测, LLM 集成, MCP, Python, Reverse Engineering, SSE, 上下文管理, 二进制分析, 云安全运维, 云资产清单, 人工智能辅助, 代码理解, 协议分析, 大模型工具, 情报收集, 插件, 无后门, 权限提升, 漏洞研究, 自动化分析, 跨站脚本, 逆向工具, 逆向工程