Skip to content

BINARY_COMPARISON_USAGE_GUIDE.md

Latest commit

 

History

History
371 lines (270 loc) · 8.92 KB

BINARY_COMPARISON_USAGE_GUIDE.md

File metadata and controls

371 lines (270 loc) · 8.92 KB

Binary Ninja Usage Guide

Overview

smartdiff uses Binary Ninja MCP servers for binary inspection. This enables AI agents to:

  1. Discover binaries loaded in Binary Ninja
  2. List functions in binaries
  3. Decompile functions to see high-level code

Binary-to-binary comparison is intentionally hidden in the default build. It requires the explicit binary-comparison Cargo feature.

Architecture

AI Agent (Claude Desktop)
    ↓ (MCP/stdio)
smartdiff MCP Server
    ↓ (HTTP client)
Binary Ninja MCP Server(s)
    ↓ (Python API)
Binary Ninja (GUI with Personal License)

Prerequisites

1. Binary Ninja

  • Binary Ninja installed (Personal License or higher)
  • Binary Ninja MCP plugin installed (from /home/matteius/smartdiff/binary_ninja_mcp/)

2. Binary Ninja MCP Server

Located at: /home/matteius/smartdiff/binary_ninja_mcp/

Installation:

cd /home/matteius/smartdiff/binary_ninja_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Plugin Installation:

  1. Copy plugin/ directory to Binary Ninja plugins folder
  2. Restart Binary Ninja
  3. Plugin will appear in Plugins menu

3. smartdiff MCP Server

Located at: /home/matteius/smartdiff/

Build:

cd /home/matteius/smartdiff
cargo build --release -p smart-diff-mcp-server
cargo build --release -p smart-diff-cli

Setup Workflow

Step 1: Load Binaries in Binary Ninja

  1. Open Binary Ninja

  2. Load first binary (e.g., malware_v1.exe)

  3. Start MCP server for this binary:

    • Plugins > MCP Server > Start Server for This Binary
    • Server will start on port 9009
    • You'll see: "MCP Server started on port 9009"

  4. Open another Binary Ninja window (or tab)

  5. Load second binary (e.g., malware_v2.exe)

  6. Start MCP server for this binary:

    • Plugins > MCP Server > Start Server for This Binary
    • Server will start on port 9010
    • You'll see: "MCP Server started on port 9010"

Step 2: Verify Direct Rust Access

The preferred smartdiff path is the Rust client talking directly to the Binary Ninja GUI plugin server:

cd /home/matteius/smartdiff
cargo run --release -p smart-diff-cli -- binja servers
cargo run --release -p smart-diff-cli -- binja functions port_9009 --limit 25
cargo run --release -p smart-diff-cli -- binja decompile port_9009 main

This avoids headless Binary Ninja entirely and works with a Personal license because the licensed GUI process owns the analysis.

Step 3: Start Binary Ninja MCP Bridge (Optional)

If you want to use Binary Ninja MCP directly with Claude:

cd /home/matteius/smartdiff/binary_ninja_mcp
source .venv/bin/activate
python bridge/bn_mcp_bridge_multi_http.py

This bridge connects to Claude Desktop and routes requests to Binary Ninja servers.

Step 4: Start smartdiff MCP Server

cd /home/matteius/smartdiff
cargo run --release --bin smart-diff-mcp

The server will start and listen on stdio for MCP requests.

Step 5: Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "smartdiff": {
      "command": "/home/matteius/smartdiff/target/release/smart-diff-mcp",
      "args": []
    }
  }
}

Note: You can also add the Binary Ninja MCP bridge if you want direct access:

{
  "mcpServers": {
    "smartdiff": {
      "command": "/home/matteius/smartdiff/target/release/smart-diff-mcp",
      "args": []
    },
    "binary_ninja": {
      "command": "/path/to/binary_ninja_mcp/.venv/bin/python",
      "args": ["/path/to/binary_ninja_mcp/bridge/bn_mcp_bridge_multi_http.py"]
    }
  }
}

Step 6: Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

Available Tools

1. list_binja_servers

Description: List all available Binary Ninja MCP servers with loaded binaries.

Usage:

User: "What binaries do I have loaded in Binary Ninja?"

Agent calls: list_binja_servers()

Response:
Found 2 Binary Ninja server(s):

Binary ID: port_9009
Filename: malware_v1.exe
Port: 9009
URL: http://localhost:9009

Binary ID: port_9010
Filename: malware_v2.exe
Port: 9010
URL: http://localhost:9010

2. list_binary_functions

Description: List all functions in a binary.

Parameters:

  • binary_id (required): Binary server ID (e.g., "port_9009")
  • search (optional): Search term to filter functions

Usage:

User: "Show me all functions in the first binary"

Agent calls: list_binary_functions(binary_id="port_9009")

Response:
Found 150 function(s) in port_9009:

1. main
2. process_data
3. encrypt_payload
4. decrypt_payload
5. connect_to_server
...

With search:

User: "Find functions related to encryption"

Agent calls: list_binary_functions(binary_id="port_9009", search="encrypt")

Response:
Found 3 function(s) matching 'encrypt' in port_9009:

1. encrypt_payload
2. encrypt_string
3. decrypt_payload

3. decompile_binary_function

Description: Decompile a specific function and return the decompiled code.

Parameters:

  • binary_id (required): Binary server ID
  • function_name (required): Name of the function to decompile

Usage:

User: "Show me the decompiled code for process_data"

Agent calls: decompile_binary_function(
    binary_id="port_9009",
    function_name="process_data"
)

Response:
Decompiled code for function 'process_data':

```c
int64_t process_data(int64_t arg1, int64_t arg2)
{
    int64_t rax;
    
    if (arg1 != 0)
    {
        rax = encrypt_payload(arg1, arg2);
        send_to_server(rax);
    }
    else
    {
        rax = 0;
    }
    return rax;
}


## Example Workflows

### Workflow 1: Explore a Binary

User: "I have a binary loaded in Binary Ninja. Can you help me understand what it does?"

Agent:

  1. Calls list_binja_servers() to see available binaries
  2. Calls list_binary_functions(binary_id="port_9009") to see all functions
  3. Identifies interesting functions (e.g., "main", "process_data")
  4. Calls decompile_binary_function() for each interesting function
  5. Analyzes the decompiled code and explains functionality

### Workflow 2: Find Specific Functionality

User: "Does this binary have any network communication functions?"

Agent:

  1. Calls list_binary_functions(binary_id="port_9009", search="send")
  2. Calls list_binary_functions(binary_id="port_9009", search="recv")
  3. Calls list_binary_functions(binary_id="port_9009", search="connect")
  4. Decompiles found functions to analyze network behavior
  5. Reports findings

## Troubleshooting

### No servers found

**Problem**: `list_binja_servers()` returns "No Binary Ninja servers found"

**Solutions**:
1. Make sure Binary Ninja is running
2. Make sure you have loaded binaries
3. Make sure MCP server is started for each binary (Plugins > MCP Server > Start Server)
4. Check that servers are running on ports 9009+ (check Binary Ninja console)

### Function not found

**Problem**: `decompile_binary_function()` returns "Function not found"

**Solutions**:
1. Use `list_binary_functions()` to see exact function names
2. Function names are case-sensitive
3. Some functions may have mangled names - try searching first

### Connection timeout

**Problem**: Requests to Binary Ninja servers timeout

**Solutions**:
1. Check that Binary Ninja is still running
2. Check that the binary is still loaded
3. Restart the MCP server in Binary Ninja
4. Check firewall settings (localhost should be allowed)

## Rust CLI Shortcuts

The same path is available without MCP:

```bash
cargo run --release -p smart-diff-cli -- binja servers
cargo run --release -p smart-diff-cli -- binja functions port_9009 --limit 25
cargo run --release -p smart-diff-cli -- binja decompile port_9009 main

Feature-Gated Comparison

The comparison commands and MCP tools are not exposed by default. To enable them deliberately, build with:

cargo build --release -p smart-diff-cli --features binary-comparison
cargo build --release -p smart-diff-mcp-server --features binary-comparison

Technical Details

Binary Ninja MCP Client

The client library (crates/binary-ninja-client/) provides:

  • No Binary Ninja dependencies: Just HTTP/JSON
  • Async/await: Built on tokio
  • Error handling: Comprehensive error types
  • Multi-server support: Discover and connect to multiple servers

MCP Tools

The MCP server (crates/mcp-server/) now includes:

  • Source code comparison tools (existing):

    • compare_locations
    • list_changed_functions
    • get_function_diff
    • get_comparison_summary

  • Binary inspection tools:

    • list_binja_servers
    • list_binary_functions
    • decompile_binary_function

Only these binary tools are available to AI agents in the default build.

License

AGPL-3.0-only

See Also