Binary Ninja Headless MCP

Ein Headless-Binary Ninja-Server, der MCP (Model Context Protocol) spricht und KI-Agenten vollen Zugriff auf tiefgehende Reverse-Engineering-Workflows gibt – Disassemblierung, IL, Patching, Typen, Querverweise und mehr – ohne GUI.

Entwickelt, um im gleichen Docker-Container wie die Agenten-Laufzeitumgebung zu laufen. Keine Sidecars, keine zusätzlichen Dienste.

Dieses gesamte Projekt – Code, Tests und Dokumentation – ist zu 100 % Vibe-coded.

Warum

Existierende Binary Ninja MCP-Server sind entweder GUI-gebunden oder bieten nur eine begrenzte Werkzeugoberfläche. Dieser Server ist ausschließlich headless und für agentengesteuerte Workflows in sandbox-VM/Containerumgebungen konzipiert: Der Agent erhält die vollständige Kontrolle über das Analysesystem, automatisiert große Teile des Reverse Engineerings, während Sie interaktiv diskutieren und den Prozess steuern.

Das Ziel ist eine Schnittstelle, bei der Agenten eine Analyse im Laufe der Zeit inspizieren, verfeinern und erweitern können – Aktualisieren von Typen, Symbolen und Metadaten, inkrementelles Verbessern der Analysedatenbank, Anwenden von Patches und sicheres Iterieren mit Rückgängig/Wiederholen sowie Ausführen benutzerdefinierter Skripte, wenn ein Workflow etwas Maßgeschneidertes benötigt.

Funktionen

• 181 Werkzeuge in 36 Funktionsgruppen: Analyse, Disassemblierung, IL, Patching, Rückgängig/Wiederholen, Typen, Workflows, Speicher, Suche, Querverweise, Skripting und mehr.
• Standardmäßig schreibgeschützt mit sicheren Mutations-Workflows (Rückgängig/Wiederholen, Transaktionen).
• Skriptzugriff über binja.eval und binja.call für alles, was der Werkzeugkatalog nicht abdeckt.
• Stdio- und TCP-Transporte.
• Keine Laufzeitabhängigkeiten außer Binary Ninja selbst.
• Fake-Backend-Modus für CI und Entwicklung ohne Binary Ninja-Lizenz.

Voraussetzungen

• Python 3.11+
• Eine Binary Ninja-Installation mit einer headless-fähigen Lizenz und dem importierbaren binaryninja-Python-Modul in Ihrer Laufzeitumgebung (für echte Analyse)
• Für CI/Entwicklung ohne Binary Ninja verwenden Sie den Fake-Backend-Modus

Installation

git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .

Oder direkt aus dem Repository-Root installieren ohne Klonen:

pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git

Schnellstart

Stdio-Transport (Standard):

python3 binary_ninja_headless_mcp.py

TCP-Transport:

python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765

Fake-Backend-Modus (kein Binary Ninja erforderlich):

python3 binary_ninja_headless_mcp.py --fake-backend

Verwendung mit KI-Agenten

Dieser Server spricht standardmäßig MCP über stdio (Standard) oder tcp, sodass jeder MCP-fähige Agenten-Host ihn nutzen kann.

Claude Code

claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py

Oder fügen Sie es der .mcp.json Ihres Projekts hinzu:

{
  "mcpServers": {
    "binary_ninja_headless_mcp": {
      "command": "python3",
      "args": ["binary_ninja_headless_mcp.py"],
      "cwd": "/path/to/binary-ninja-headless-mcp"
    }
  }
}

Codex

codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py

Generischer MCP-Host

• Registrieren Sie einen Server mit dem Namen binary_ninja_headless_mcp.
• Verwenden Sie den Befehl python3 mit den Argumenten ["binary_ninja_headless_mcp.py"] wenn cwd das Repository-Root ist, oder verwenden Sie einen absoluten Skriptpfad in args.
• Setzen Sie cwd auf den Repository-Pfad, wenn relative Pfade wie samples/ls korrekt aufgelöst werden sollen.
• Verwenden Sie den Stdio-Transport, es sei denn, Ihr Host erfordert TCP.
• Für den Fake-Modus (kein Binary Ninja installiert) fügen Sie --fake-backend hinzu.
• Überprüfen Sie die Konnektivität durch Aufrufen von health.ping, dann session.open.

Docker-Co-Location-Muster

Empfohlenes Bereitstellungsmodell: Führen Sie den Agentenprozess und diesen MCP-Server im selben Container-Image aus.

Beispiel-Basisimage:

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]

Falls Sie eine echte Binary Ninja-Analyse im Container benötigen, fügen Sie Ihre Binary Ninja-Laufzeitumgebung und Lizenz im selben Image hinzu und starten Sie den Agenten mit diesem konfigurierten MCP-Server.

MCP-Methoden

• initialize
• ping
• tools/list
• tools/call
• shutdown

Verhalten von tools/list:

• Ohne explizite Paginierungsparameter wird der vollständige Werkzeugkatalog zurückgegeben.
• Wenn offset oder limit angegeben ist, wird eine seitenweise Ausgabe verwendet (offset=0, limit=50 Standard im Seitenmodus).
• Unterstützt Filterung über:
  • prefix (z. B. binary.)
  • query (Teilstring-Übereinstimmung mit Werkzeugname/-beschreibung)
• Gibt Paginierungsmetadaten zurück: offset, limit, total, has_more.
• Wenn eine Seite abgeschnitten ist (has_more=true), werden next_offset und ein notice-Hinweis eingefügt.

Verhalten von Werkzeugaufruf-Antworten:

• structuredContent ist die kanonische vollständige Nutzlast.
• content[0].text ist eine kompakte Zusammenfassungszeichenfolge (keine vollständige JSON-Duplizierung).
• Diese Aufteilung ist beabsichtigt, um den Kontextverbrauch gering zu halten und gleichzeitig vollständige maschinenlesbare Daten bereitzustellen.

Qualität und Tests

Dieses Repository ist gut getestet und hat durchgesetzte Qualitätsgates.

• Testsuite: Führen Sie pytest --collect-only -q für die aktuelle Anzahl der gesammelten Tests aus.
• CI-Workflow erzwingt:
  • ruff format --check .
  • ruff check .
  • pytest
• CI verwendet BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1, sodass Prüfungen ohne Binary Ninja-Installation ausgeführt werden können.
• Zusätzliche strukturelle Tests überprüfen die Konsistenz des Werkzeugregisters und die Erreichbarkeit des Backends.

Kontextsteuerung

• Der schreibgeschützte Modus ist die Standardeinstellung für geöffnete Sitzungen (read_only=true).
• binary.basic_blocks_at und function.basic_blocks werden seitenweise ausgegeben (offset/limit).
• memory.read hat eine harte Antwortbegrenzung: length ≤ 65536.

Einschränkungen

• Enterprise-APIs werden derzeit nicht abgedeckt.
• Debugger-APIs werden derzeit nicht abgedeckt.

Sicherheitsmodell

• Die MCP-Kommunikation (stdio/tcp) ist standardmäßig nicht authentifiziert.
• Der Server ermöglicht beliebiges Scripting über binja.eval und breiten API-Zugriff über binja.call.
• Dies ist absichtlich für vertrauenswürdige, containerisierte Agentenumgebungen so konzipiert.
• Setzen Sie diesen Server nicht direkt ungeschützten Benutzern oder Netzwerken aus.

Lokaler Entwicklungs-Workflow

ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q

Feature-Fuzzer

Verwenden Sie den integrierten MCP-Feature-Fuzzer, um eine breite Werkzeugoberfläche gegen samples/ls zu testen.

Echtes Binary Ninja-Backend:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337

Fake-Backend-Smoke-Test:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20

JSON-Coverage-Bericht schreiben:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json

Nützliche Flags: