Serveur MCP Headless Binary Ninja — offrant aux agents IA des capacités profondes de rétro-ingénierie via 180 outils.
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é.
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.
binja.eval et binja.call pour tout ce que le catalogue d'outils ne couvre pas.3.11+binaryninja importable dans votre environnement d'exécution (pour une analyse réelle)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
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
Ce serveur parle MCP standard via stdio (par défaut) ou tcp, donc tout hôte d'agent compatible MCP peut l'utiliser.
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 mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py
binary_ninja_headless_mcp.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.cwd sur le chemin du dépôt si vous voulez que les chemins relatifs comme samples/ls soient résolus correctement.--fake-backend.health.ping, puis session.open.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é.
initializepingtools/listtools/callshutdownComportement de tools/list :
offset ou limit est fourni, utilise une sortie paginée (offset=0, limit=50 par défaut en mode paginé).prefix (par exemple binary.)query (correspondance de sous-chaîne avec le nom/la description de l'outil)offset, limit, total, has_more.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).Ce dépôt est bien testé et comporte des barrières de qualité obligatoires.
pytest --collect-only -q pour le nombre actuel de tests collectés.ruff format --check .ruff check .pytestBINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pour que les vérifications s'exécutent sans nécessiter l'installation de Binary Ninja.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.stdio/tcp) est non authentifiée par défaut.binja.eval et un accès large aux API via binja.call.ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q
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 :
--min-success-tools N : se termine avec un code non nul si moins de N outils ont réussi.--verbose : affiche chaque appel d'outil pendant le fuzzing.--update-analysis : ouvre la session de départ avec update_analysis=true.Le serveur expose actuellement 181 outils répartis dans 36 groupes de fonctionnalités.
analysis.status : Obtenir le statut de l'analyse.analysis.progress : Obtenir un instantané de l'avancement de l'analyse.analysis.update : Déclencher une mise à jour asynchrone de l'analyse.analysis.update_and_wait : Exécuter une mise à jour de l'analyse et attendre la fin.analysis.abort : Annuler l'analyse.analysis.set_hold : Mettre en attente/libérer la file d'attente de l'analyse.annotation.rename_function : Renommer une fonction.annotation.rename_symbol : Renommer un symbole à une adresse.annotation.undefine_symbol : Supprimer la définition d'un symbole utilisateur à une adresse.annotation.define_symbol : Définir un symbole à une adresse.annotation.rename_data_var : Renommer une variable de données.annotation.define_data_var : Définir une variable de données.annotation.undefine_data_var : Supprimer la définition d'une variable de données.annotation.set_comment : Définir un commentaire à une adresse.annotation.get_comment : Obtenir un commentaire à une adresse.annotation.add_tag : Ajouter une étiquette de données utilisateur à une adresse.annotation.get_tags : Obtenir les étiquettes à une adresse.arch.info : Obtenir les métadonnées de l'architecture et de la plateforme.arch.disasm_bytes : Désassembler des octets avec l'architecture sélectionnée.arch.assemble : Assembler du texte d'instruction avec l'architecture sélectionnée.baseaddr.detect : Lancer la détection de l'adresse de base.baseaddr.reasons : Obtenir les raisons de la détection de l'adresse de base.baseaddr.abort : Annuler la détection de l'adresse de base.binary.summary : Obtenir un résumé du binaire/session.binary.save : Sauvegarder la vue binaire actuelle dans un chemin de fichier.binary.functions : Lister les fonctions avec pagination.binary.strings : Lister les chaînes découvertes avec pagination.binary.search_text : Rechercher du texte/octets bruts dans une session.binary.sections : Lister les sections avec pagination.binary.segments : Lister les segments avec pagination.binary.symbols : Lister les symboles avec pagination.binary.data_vars : Lister les variables de données avec pagination.binary.get_function_at : Trouver une fonction par adresse.binary.get_function_disassembly_at : Obtenir le désassemblage complet pour la fonction contenant une adresse.binja.info : Retourner les informations de version/installation de Binary Ninja.binja.call : Pont API générique : appeler le chemin cible bn.* ou bv.*.binja.eval : Évaluer du code Python avec bn, sessions, et bv optionnel.data.typed_at : Obtenir une variable de données typée à une adresse.database.create_bndb : Créer un .bndb à partir de la session.database.save_auto_snapshot : Sauvegarder un instantané automatique.database.info : Obtenir le statut de la base de données pour la session.database.snapshots : Lister les instantanés de la base de données.database.read_global : Lire une clé chaîne globale de la base de données.database.write_global : Écrire une clé chaîne globale de la base de données.debug.parsers : Lister les analyseurs d'informations de débogage valides pour cette vue.debug.parse_and_apply : Analyser les informations de débogage et les appliquer à la vue.disasm.linear : Obtenir des lignes de désassemblage linéaire.disasm.function : Obtenir le désassemblage complet pour la fonction contenant une adresse.disasm.range : Lignes de désassemblage pour une plage d'adresses.external.library_add : Ajouter une bibliothèque externe.external.library_list : Lister les bibliothèques externes.external.library_remove : Supprimer une bibliothèque externe.external.location_add : Ajouter un mappage d'emplacement externe.external.location_get : Obtenir un mappage d'emplacement externe.external.location_remove : Supprimer un mappage d'emplacement externe.function.basic_blocks : Lister les blocs de base dans une fonction avec pagination.function.callers : Appelants d'une fonction.function.callees : Appelés d'une fonction.function.variables : Lister les variables d'une fonction.function.var_refs : Lister les références de variables en MLIL/HLIL.function.var_refs_from : Lister les références de variables provenant d'une adresse.function.ssa_var_def_use : Obtenir la définition et les utilisations de variable SSA.function.ssa_memory_def_use : Obtenir la définition et les utilisations de mémoire SSA par version mémoire.function.metadata_store : Stocker des métadonnées de fonction par clé.function.metadata_query : Interroger des métadonnées de fonction par clé.function.metadata_remove : Supprimer des métadonnées de fonction par clé.health.ping : Vérification de santé.il.function : Liste des fonctions IL.il.instruction_by_addr : Obtenir une instruction IL par adresse source.il.address_to_index : Mapper une adresse vers un/des index IL.il.index_to_address : Mapper un index IL vers une adresse source.il.rewrite.capabilities : Lister les capacités de réécriture IL pour une fonction et un niveau IL.il.rewrite.noop_replace : Effectuer un remplacement d'expression IL par NOP.il.rewrite.translate_identity : Traduire IL avec un callback de mappage d'identité.loader.rebase : Rebaser la BinaryView.loader.load_settings_types : Lister les noms de types de paramètres du chargeur.loader.load_settings_get : Obtenir les valeurs des paramètres du chargeur.loader.load_settings_set : Définir une valeur de paramètre du chargeur.memory.read : Lire des octets de la vue (length <= 65536).memory.write : Écrire des octets (hex) dans la vue.memory.insert : Insérer des octets (hex) dans la vue.memory.remove : Supprimer des octets de la vue.memory.reader_read : Lire des valeurs entières via BinaryReader.memory.writer_write : Écrire des valeurs entières via BinaryWriter.mcp.response_format : Expliquer les champs de résultat d'outil (structuredContent charge utile complète, content[0].text résumé).metadata.store : Stocker des métadonnées par clé.metadata.query : Interroger des métadonnées par clé.metadata.remove : Supprimer des métadonnées par clé.patch.assemble : Assembler et patcher les octets d'instruction à une adresse.patch.status : Inspecter la disponibilité du patch à une adresse.patch.convert_to_nop : Patcher une instruction en NOP quand c'est supporté.patch.always_branch : Patcher un branchement conditionnel pour toujours brancher quand c'est supporté.patch.never_branch : Patcher un branchement conditionnel pour ne jamais brancher quand c'est supporté.patch.invert_branch : Patcher un branchement conditionnel par inversion quand c'est supporté.patch.skip_and_return_value : Patcher une instruction pour sauter et retourner une valeur quand c'est supporté.plugin.valid_commands : Lister les commandes de plugin valides dans le contexte.plugin.execute : Exécuter une commande de plugin valide dans le contexte.plugin_repo.status : Lister les dépôts de plugins et les états des plugins.plugin_repo.check_updates : Vérifier les mises à jour du dépôt de plugins.plugin_repo.plugin_action : Exécuter une action d'installation/désinstallation/activation/désactivation sur un plugin du dépôt.project.create : Créer un projet.project.open : Ouvrir un projet.project.close : Fermer le projet suivi.project.list : Lister les dossiers/fichiers du projet.project.create_folder : Créer un dossier de projet.project.create_file : Créer un fichier de projet à partir de données en base64.project.metadata_store : Stocker des métadonnées de projet.project.metadata_query : Interroger des métadonnées de projet.project.metadata_remove : Supprimer des métadonnées de projet.search.data : Rechercher des motifs d'octets bruts (chaîne hexadécimale).search.next_text : Trouver la correspondance texte suivante.search.all_text : Trouver toutes les correspondances texte dans une plage (regex optionnel).search.next_data : Trouver la correspondance de données/motif d'octets suivante.search.all_data : Trouver toutes les correspondances de données/motifs d'octets dans une plage.search.next_constant : Trouver l'occurrence suivante d'une constante.search.all_constant : Trouver toutes les occurrences d'une constante dans une plage.section.add_user : Ajouter une section utilisateur.section.remove_user : Supprimer une section utilisateur.segment.add_user : Ajouter un segment utilisateur.segment.remove_user : Supprimer un segment utilisateur.session.open : Ouvrir un binaire et créer une session.session.open_bytes : Ouvrir une session binaire à partir d'octets encodés en base64.session.open_existing : Ouvrir une autre session à partir du fichier d'une session existante.session.close : Fermer une session ouverte.session.list : Lister les sessions ouvertes.session.mode : Obtenir le mode de sécurité/déterminisme de la session.session.set_mode : Mettre à jour le mode de sécurité/déterminisme de la session.task.analysis_update : Démarrer une tâche de mise à jour asynchrone de l'analyse.task.search_text : Démarrer une tâche de recherche asynchrone.task.status : Obtenir le statut de la tâche.task.result : Obtenir le résultat de la tâche.task.cancel : Annuler la tâche (au mieux).transform.inspect : Inspecter/traiter le pipeline d'extraction de transformation.type.parse_string : Analyser une chaîne de type unique.type.parse_declarations : Analyser des déclarations C pour types/variables/fonctions.type.define_user : Définir un type utilisateur à partir d'une source de type.type.rename : Renommer un type.type.undefine_user : Supprimer la définition d'un type utilisateur.type.import_library_type : Importer un type depuis une bibliothèque de types.type.import_library_object : Importer un type d'objet depuis une bibliothèque de types.type.export_to_library : Exporter un type dans une bibliothèque de types.type_archive.create : Créer et éventuellement attacher une archive de types.type_archive.open : Ouvrir et éventuellement attacher une archive de types.type_archive.list : Lister les archives de types attachées.type_archive.get : Obtenir une archive de types suivie.type_archive.pull : Récupérer des types depuis une archive de types.type_archive.push : Envoyer des types vers une archive de types.type_archive.references : Interroger les références entrantes/sortantes de l'archive pour un type.type_library.create : Créer et éventuellement attacher une bibliothèque de types.type_library.load : Charger et éventuellement attacher une bibliothèque de types.type_library.list : Lister les bibliothèques de types attachées à la vue.type_library.get : Obtenir une bibliothèque de types suivie.uidf.parse_possible_value : Analyser une chaîne d'ensemble de valeurs possibles informé par l'utilisateur.uidf.set_user_var_value : Définir la valeur de variable utilisateur d'une fonction.uidf.clear_user_var_value : Effacer la valeur de variable utilisateur d'une fonction.uidf.list_user_var_values : Lister toutes les valeurs de variables utilisateur pour une fonction.undo.begin : Commencer une transaction d'annulation.undo.commit : Valider une transaction d'annulation.undo.revert : Annuler une transaction d'annulation.undo.undo : Effectuer une annulation.undo.redo : Effectuer une répétition.value.reg : Obtenir la valeur d'un registre à/après une adresse.value.stack : Obtenir le contenu de la pile à/après une adresse.value.possible : Obtenir l'ensemble de valeurs possibles IL à une adresse.value.flags_at : Obtenir l'état de lecture/écriture des drapeaux IL levés à une adresse.workflow.list : Lister les workflows enregistrés.workflow.describe : Décrire la topologie et les paramètres du workflow.workflow.clone : Cloner un workflow.workflow.insert : Insérer des activités avant une activité.workflow.insert_after : Insérer des activités après une activité.workflow.remove : Supprimer une activité de workflow.workflow.graph : Résumer le graphe du workflow.workflow.machine.status : Obtenir le statut de la machine de workflow.workflow.machine.control : Contrôler l'exécution de la machine de workflow.xref.code_refs_to : Références de code vers une adresse.xref.code_refs_from : Références de code depuis une adresse.xref.data_refs_to : Références de données vers une adresse.xref.data_refs_from : Références de données depuis une adresse.Pour plus d'informations, contactez Tim Blazytko (@mr_phrazer).
binary.get_function_il_at : Obtenir l'IL complet pour la fonction contenant une adresse.binary.functions_at : Lister les fonctions à une adresse.binary.basic_blocks_at : Lister les blocs de base à une adresse avec pagination.