Binary Ninja Headless MCP

Un serveur Binary Ninja sans interface graphique qui parle le MCP (Model Context Protocol), offrant aux agents IA un accès complet à des workflows avancés de rétro-ingénierie — désassemblage, IL, patching, types, références croisées, et plus — sans GUI.

Conçu pour fonctionner dans le même conteneur Docker que l'exécution de l'agent. Pas de sidecars, pas de services supplémentaires.

Ce projet entier — code, tests et documentation — est 100 % vibe codé.

Pourquoi

Les serveurs MCP Binary Ninja existants sont soit liés à une interface graphique, soit n'exposent qu'une surface d'outils limitée. Ce serveur est uniquement sans interface graphique et conçu pour des workflows pilotés par agent dans des environnements VM/conteneurs sandboxés : l'agent obtient un contrôle total sur le système d'analyse, automatisant de grandes parties de la rétro-ingénierie pendant que vous discutez et orientez le processus de manière interactive.

L'objectif est une interface où les agents peuvent inspecter, affiner et étendre une analyse au fil du temps — mettre à jour les types, symboles et métadonnées, améliorer la base de données d'analyse de manière incrémentale, appliquer des correctifs et itérer en toute sécurité avec annulation/répétition, et exécuter des scripts personnalisés lorsqu'un workflow nécessite quelque chose de spécifique.

Fonctionnalités

• 181 outils répartis dans 36 groupes de fonctionnalités : analyse, désassemblage, IL, patching, annulation/répétition, types, workflows, mémoire, recherche, références croisées, scripts, et plus.
• Lecture seule par défaut avec des workflows de mutation sûrs (annulation/répétition, transactions).
• Accès aux scripts via binja.eval et binja.call pour tout ce que le catalogue d'outils ne couvre pas.
• Transports stdio et TCP.
• Zéro dépendance d'exécution en dehors de Binary Ninja lui-même.
• Mode backend factice pour l'intégration continue et le développement sans licence Binary Ninja.

Prérequis

• Python 3.11+
• Une installation de Binary Ninja avec une licence compatible sans interface graphique et le module Python binaryninja importable dans votre environnement d'exécution (pour une analyse réelle)
• Pour l'intégration continue/le développement sans Binary Ninja, utilisez le mode backend factice

Installation

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

Ou installez directement depuis la racine du dépôt sans cloner :

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

Démarrage rapide

Transport stdio (par défaut) :

python3 binary_ninja_headless_mcp.py

Transport TCP :

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

Mode backend factice (Binary Ninja non requis) :

python3 binary_ninja_headless_mcp.py --fake-backend

Utilisation avec les agents IA

Ce serveur parle MCP standard via stdio (par défaut) ou tcp, donc tout hôte d'agent compatible MCP peut l'utiliser.

Claude Code

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

Ou ajoutez-le au fichier .mcp.json de votre projet :

{
  "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

Hôte MCP générique

• Enregistrez un serveur nommé binary_ninja_headless_mcp.
• Utilisez la commande python3 avec les arguments ["binary_ninja_headless_mcp.py"] lorsque cwd est la racine du dépôt, ou utilisez un chemin de script absolu dans args.
• Définissez cwd sur le chemin du dépôt si vous voulez que les chemins relatifs comme samples/ls soient résolus correctement.
• Utilisez le transport stdio sauf si votre hôte nécessite TCP.
• Pour le mode factice (Binary Ninja non installé), ajoutez --fake-backend.
• Vérifiez la connectivité en appelant health.ping, puis session.open.

Modèle de co-localisation Docker

Modèle de déploiement recommandé : exécutez le processus d'agent et ce serveur MCP dans la même image de conteneur.

Exemple de base :

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"]

Si vous avez besoin d'une analyse Binary Ninja réelle dans le conteneur, ajoutez votre environnement d'exécution Binary Ninja + configuration de licence dans cette même image et démarrez l'agent avec ce serveur MCP configuré.

Méthodes MCP

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

Comportement de tools/list :

• Sans paramètres de pagination explicites, retourne le catalogue complet d'outils.
• Si offset ou limit est fourni, utilise une sortie paginée (offset=0, limit=50 par défaut en mode paginé).
• Prend en charge le filtrage via :
  • prefix (par exemple binary.)
  • query (correspondance de sous-chaîne avec le nom/la description de l'outil)
• Retourne les métadonnées de pagination : offset, limit, total, has_more.
• Lorsqu'une page est tronquée (has_more=true), inclut next_offset et un indice notice.

Comportement de la réponse d'appel d'outil :

• structuredContent est la charge utile canonique complète.
• content[0].text est une chaîne de résumé compacte (pas de duplication JSON complète).
• Cette séparation est intentionnelle pour réduire l'utilisation du contexte tout en exposant toujours les données complètes lisibles par machine.

Qualité et tests

Ce dépôt est bien testé et comporte des barrières de qualité obligatoires.

• Suite de tests : exécutez pytest --collect-only -q pour le nombre actuel de tests collectés.
• Le workflow CI impose :
  • ruff format --check .
  • ruff check .
  • pytest
• CI utilise BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pour que les vérifications s'exécutent sans nécessiter l'installation de Binary Ninja.
• Des tests structurels supplémentaires vérifient la cohérence du registre d'outils et l'accessibilité du backend.

Contrôles de contexte

• Le mode lecture seule est la valeur par défaut pour les sessions ouvertes (read_only=true).
• binary.basic_blocks_at et function.basic_blocks sont paginés (offset/limit).
• memory.read a une limite stricte de réponse : length <= 65536.

Limitations

• Les API Enterprise ne sont actuellement pas couvertes.
• Les API du débogueur ne sont actuellement pas couvertes.

Modèle de sécurité

• La communication MCP (stdio/tcp) est non authentifiée par défaut.
• Le serveur expose des scripts arbitraires via binja.eval et un accès large aux API via binja.call.
• C'est fait exprès pour des environnements d'agents conteneurisés et de confiance.
• N'exposez pas ce serveur directement à des utilisateurs ou réseaux non fiables.

Workflow de développement local

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

Fuzzer de fonctionnalités

Utilisez le fuzzer de fonctionnalités MCP intégré pour exercer une large surface d'outils sur samples/ls.

Backend Binary Ninja réel :

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

Exécution de test rapide avec backend factice :

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

Écrire un rapport de couverture JSON :

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

Indicateurs utiles :