BinjaLattice

BinjaLattice

BinjaLattice 是一种适用于 Binary Ninja 的安全通信协议，可与外部 Model Context Protocol（MCP）服务和工具交互。它提供了一种从 Binary Ninja 获取信息的结构化方式，并支持通过 REST API over HTTP 修改活动的 Binary Ninja 数据库。

演示

功能

• 安全身份验证：基于令牌的身份验证系统
• 加密通信：可选的 SSL/TLS 加密
• 二进制分析上下文：导出伪代码、反汇编、变量名称、二进制信息等
• 二进制修改：更新函数名称、添加注释、重命名变量
• 令牌管理：自动过期和续订身份验证令牌

安装

Windows（自动安装）

运行 PowerShell 安装程序，一键完成设置：

.\scripts\install_windows.ps1

这将：

• 将插件安装到 %APPDATA%\Binary Ninja\plugins\
• 创建 Python 虚拟环境（.venv）
• 安装所有依赖项
• 输出可直接使用的 MCP 配置

手动安装（所有平台）

1. 将 plugin/lattice_server_plugin.py 和 plugin/lattice_config.ini 复制到 Binary Ninja 插件目录：

   • Linux：~/.binaryninja/plugins/
   • macOS：~/Library/Application Support/Binary Ninja/plugins/
   • Windows：%APPDATA%\Binary Ninja\plugins\

2. 生成安全的 API 密钥，并将其设为 lattice_config.ini 中的 api_key 值

3. 创建虚拟环境：

   python -m venv .venv
   

4. 激活环境并安装依赖项：

   # Linux/macOS
   source .venv/bin/activate
   
   # Windows
   .venv\Scripts\activate
   
   pip install -r requirements.txt
   

使用方法

在 Binary Ninja 中启动服务

1. 打开 Binary Ninja 并加载二进制文件
2. 前往 Plugins > Start Lattice Protocol Server
3. 服务启动后，会在日志控制台中显示 API 密钥
4. 在 MCP 配置中将 API 密钥设为环境变量 BNJLAT

MCP 配置示例（mcp.json）：

{
    "mcpServers": {
      "binja-lattice-mcp": {
        "command": "/path/to/BinjaLattice/.venv/bin/python",
        "args": ["/path/to/BinjaLattice/mcp_server.py"],
        "env": {
            "BNJLAT": "your_api_key_here"
        }
      }
    }
}

在 Windows 上，请使用反斜杠：

{
    "mcpServers": {
      "binja-lattice-mcp": {
        "command": "C:\\path\\to\\BinjaLattice\\.venv\\Scripts\\python.exe",
        "args": ["C:\\path\\to\\BinjaLattice\\mcp_server.py"],
        "env": {
            "BNJLAT": "your_api_key_here"
        }
      }
    }
}

提示：Windows 安装程序会输出路径正确、可直接粘贴的配置。

可用的 MCP 工具

以下工具可通过 MCP 服务使用：

二进制信息

• get_binary_info：获取二进制文件的元数据（文件名、架构、入口点、段、节、函数数量）
• get_all_function_names：列出二进制文件中的所有函数名称
• get_strings：获取字符串，可选设置 min_length 和子字符串筛选条件
• get_imports：列出导入的函数及其地址和来源库
• get_exports：列出导出的函数及其地址
• get_analysis_progress：获取 Binary Ninja 分析状态和进度百分比

函数分析

• get_function_disassembly：按名称获取函数的汇编指令
• get_function_pseudocode：获取函数反编译后的类 C 伪代码
• get_function_variables：获取参数、局部变量和全局变量
• get_cross_references_to_function：列出调用指定函数的函数
• get_call_graph：获取函数的调用者和被调用者，并可配置深度
• get_global_variable_data：读取函数中引用的全局变量数据

数据访问

• get_data_at_address：读取地址处的字节，可选进行类型解释
• search_bytes：搜索十六进制字节模式，支持通配符（例如，'48 89 ?? 24'）

类型管理

• get_types：列出已定义的类型（结构体、枚举、typedef），可选设置筛选条件
• create_struct：使用 JSON 成员定义创建新的结构体类型
• update_struct：更新现有结构体类型

注释

• update_function_name：重命名函数
• update_variable_name：重命名函数中的变量
• set_variable_type：设置变量类型注解（C 风格，如 'uint32_t'）
• set_function_signature：设置函数原型（C 风格，如 'int foo(char* arg1)'）
• add_comment_to_address：在地址处添加注释
• add_comment_to_function：为函数添加注释
• create_tag：在地址处创建标签，并设置类型和可选描述
• get_tags：列出所有标签，可选按类型筛选

客户端库用法

Lattice 客户端库提供了一个 Python 接口，用于与 BinjaLattice 服务交互：

from lib.lattice import Lattice

# Initialize client
client = Lattice(host='localhost', port=9000, use_ssl=False)

# Authenticate with API key
client.authenticate("username", "API_KEY")

# Example: Get binary information
binary_info = client.get_binary_info()

# Example: Update function name
client.update_function_name("old_name", "new_name")

# Example: Add comment to function
client.add_comment_to_function("function_name", "This function handles authentication")

命令行界面

项目包含 lattice_client.py，它提供了一次性子命令，用于测试、编写脚本和调试 BinjaLattice 服务：

python lattice_client.py --host localhost --port 9000 --username user --password YOUR_API_KEY binary-info

命令行选项

• --host：服务主机（默认：localhost）
• --port：服务端口（默认：9000）
• --ssl：启用 SSL/TLS 加密
• --username：用于身份验证的用户名
• --password：用于身份验证的密码/API 密钥
• --token：身份验证令牌（如果你有之前身份验证时获取的令牌）

运行 python lattice_client.py --help 可列出所有命令，运行 python lattice_client.py <command> --help 可查看特定命令的参数。

命令

使用客户端执行单个子命令：

# Get binary information
python lattice_client.py --username user --password YOUR_API_KEY binary-info

# Get function disassembly
python lattice_client.py --username user --password YOUR_API_KEY disassembly "main"

# Add comment to a function
python lattice_client.py --username user --password YOUR_API_KEY comment-function "main" "Entry point of the program"

# Search for bytes
python lattice_client.py --username user --password YOUR_API_KEY search-bytes "48 89 ?? 24" --max-results 20

# Create a struct
python lattice_client.py --username user --password YOUR_API_KEY create-struct MyStruct '[{"name":"field1","type":"uint32_t"}]'

安全说明

• API 密钥会在服务启动时随机生成，并显示在 Binary Ninja 日志中
• 令牌默认在 8 小时后过期
• SSL/TLS 需要用户提供证书和密钥（默认禁用）
• 所有请求都需要通过 API 密钥或令牌进行身份验证
• 服务默认在本地的 9000 端口运行

开发

• 主服务实现在 plugin/lattice_server_plugin.py 中
• MCP 服务实现在 mcp_server.py 中
• 客户端库位于 lib/lattice.py

添加新功能

添加新功能：

1. 在 lattice_server_plugin.py 的 LatticeRequestHandler 类中添加新的端点处理程序
2. 在 lib/lattice.py 的 Lattice 类中添加相应的客户端方法
3. 将命令添加到 lattice_client.py
4. 在 mcp_server.py 中添加新的 MCP 工具

运行测试

1. 创建 Python 虚拟环境并安装 requirements.txt
2. 使用 Binary Ninja 安装目录中提供的 install_api.py 安装 Binary Ninja Python API
3. 运行 pytest tests/ -v 执行测试

许可证

MIT 许可证