Читать на русском языке

Diaphora MCP

Diaphora MCP est un serveur MCP (Model Context Protocol) pour le diffing binaire automatisé. Il connecte Diaphora (le moteur de diffing) et IDA Pro (le désassembleur) via le protocole MCP, permettant à des agents d'IA (comme Claude Code) d'effectuer des comparaisons de fichiers binaires, de trouver des correctifs de sécurité et d'analyser des changements.

Fonctionnalités

• Export : Convertit les bases de données .i64 / .idb analysées au format SQLite de Diaphora (via le mode headless idat.exe)
• Diffing : Compare deux bases exportées, filtre les résultats par type de correspondance et ratio
• Analyse de vulnérabilité : Recherche les changements liés à la sécurité à l'aide de mots-clés et d'heuristiques
• Détection de correctifs : Détecte automatiquement les nouvelles vérifications de limites, les vérifications nulles, la gestion des erreurs et les changements cryptographiques
• Classement : Classe les fonctions modifiées par ordre d'importance en fonction du CFG, des sauts de complexité et des indicateurs de sécurité
• Graphe d'appels : Compare les chemins d'appel (BFS, jusqu'à N niveaux) et détecte les causes racines dans les cascades d'appels
• Transfert de métadonnées : Prépare les noms, commentaires et prototypes pour le transfert entre bases de données
• Intégration IDA Pro MCP : Tous les outils renvoient des adresses et des chemins de base prêts à être transmis directement aux outils IDA Pro MCP

Installation

1. Dépendances

• Python 3.10+
• IDA Pro 8.x / 9.x (pour les exports headless via idat.exe)
• Plugin Diaphora installé dans IDA
• Claude Code (ou tout autre client compatible MCP)

2. Installation du paquet

git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
pip install -e .

3. Configuration des chemins

Le paquet essaie de trouver automatiquement IDA Pro et Diaphora dans les emplacements d'installation standard. S'ils ne sont pas trouvés, vous pouvez définir les variables d'environnement suivantes :

Pour Claude Code, vous pouvez les spécifier dans ~/.claude.json (ou le fichier de configuration correspondant de votre client MCP) :

{
  "mcpServers": {
    "diaphora": {
      "command": "python",
      "args": ["path/to/repo/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:\\Program Files\\IDA Pro 9.3\\idat.exe",
        "DIAPHORA_DIR": "C:\\Program Files\\IDA Pro 9.3\\plugins\\diaphora-3.4.1"
      },
      "timeout": 7200
    }
  }
}

Remarque : Pour les très gros binaires (>100 Mo), assurez-vous que timeout est d'au moins 7200 (2 heures).

3.1. Codex et IDA MCP sans tête

Codex utilise généralement deux serveurs MCP complémentaires :

• diaphora-mcp — ce projet : export, diff Diaphora et analyse des résultats ;
• ida-pro-mcp — le serveur d'inspection IDA en amont pour idb_open, la décompilation et l'analyse au niveau des adresses.

idalib-mcp est le backend sans tête de ida-pro-mcp, pas un serveur Diaphora distinct. Après l'avoir installé, redémarrez Codex :

uv run ida-pro-mcp --install codex --transport streamable-http --scope global --ida-rpc http://127.0.0.1:8745/mcp

Pour ce projet, une configuration stdio est suffisante :

[mcp_servers.diaphora-mcp]
command = "python"
args = ["D:\\path\\to\\diaphora-mcp\\diaphora_mcp_server.py"]
startup_timeout_sec = 120

4. Préparation des bases de données pour le diffing

IDA Pro doit d'abord analyser les binaires (en créant des fichiers .i64 ou .idb). Après cela :

┃ export_idb_to_diaphora(idb_path="old_version.i64")
┃ export_idb_to_diaphora(idb_path="new_version.i64")

Ou exécutez le pipeline complet en une seule commande :

┃ batch_export_and_diff(idb1="old.i64", idb2="new.i64")

Ne transmettez pas directement .i64 aux outils de résultats : c'est une base de données IDA, pas SQLite. Exportez-la d'abord.

Démarrage rapide

┃ # 1. Pipeline complet : exporter deux .i64 → diff → rapport de synthèse
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. Si les bases sont déjà exportées
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. Analyse de sécurité des résultats du diff
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. Classement par importance des modifications
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. Trouver les causes racines des modifications
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. Détecter les correctifs de sécurité probables
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. Générer un rapport complet
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

Exemple (transcription de session en direct)

Voir examples/basic-session.md pour une transcription complète étape par étape d'une session réelle Diaphora MCP — de l'export de deux bases IDB à la comparaison de fonctions individuelles. Également disponible en russe.

Voici un aperçu de ce que renvoie le serveur :

Entrée — comparer deux DLL SQLite3 (2015 vs 2023) :

{"idb1_path": "old.i64", "idb2_path": "new.i64", "use_decompiler": false}

Sortie — résumé après export + diff :

{
  "best_matches": 60,
  "partial_matches": 993,
  "multimatches": 52,
  "unmatched_primary": 2647
}

La session parcourt 6 appels d'outils MCP, montrant le JSON exact d'entrée/sortie pour chaque étape, avec le raisonnement de l'agent.

Investigation d'une seule base de données

┃ # Obtenir les informations d'export de la base
┃ get_export_info(db_path="app.sqlite")
 
┃ # Rechercher des fonctions
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # Récupérer le pseudocode
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

Structure du projet

diaphora-mcp/
├── diaphora_mcp_server.py          # Point d'entrée principal
├── diaphora_mcp/
│   ├── diaphora_mcp_server.py      # Enregistrement des outils MCP
│   ├── config.py                   # Configuration des chemins et détection automatique
│   ├── models.py                   # Constantes et modèles
│   ├── core/
│   │   ├── export.py               # Export sans tête, pipeline par lots
│   │   ├── diff.py                 # Diffing et lecteur de résultats .diaphora
│   │   ├── analysis.py             # Recherche, comparaison, explication de fonctions
│   │   ├── security.py             # Correspondance de mots-clés, détection de correctifs
│   │   ├── ranking.py              # Classement par importance
│   │   ├── graph.py                # Graphe d'appels, arbres d'appels BFS, cause racine
│   │   ├── metadata.py             # Préparation des métadonnées (noms, commentaires)
│   │   └── report.py               # Génération de rapport de correctif global
│   └── utils/
│       ├── sqlite.py               # Aides SQLite
│       ├── format.py               # Diff de pseudocode, extraction de vecteurs de caractéristiques
│       └── log.py                  # Utilitaires de journalisation d'export
├── _diaphora_headless.py           # Wrapper léger idat.exe -S
└── logs/                           # Journaux d'export automatisés (créés dynamiquement)

Référence des outils MCP (21 outils)

Export

Diff

Analyse

Sécurité

Classement

Graphe d'appels

Performance

Métadonnées

Intégration avec l'interface graphique IDA Pro (pont XML-RPC)

Le projet inclut une intégration intégrée avec les sessions actives de l'interface graphique IDA Pro, permettant des exports instantanés directement depuis les fenêtres IDA actives sans conflits de verrouillage de base de données.

1. Démarrage automatique : Copiez diaphora_gui_listener.py dans votre répertoire plugins/ d'IDA Pro. Il démarrera un serveur XML-RPC en arrière-plan sur le port 28652 à chaque démarrage d'IDA.
2. Export intelligent : Lors de l'appel à export_idb_to_diaphora, le serveur MCP vérifie le port 28652. Si une session est active, il exécute l'export directement dans l'interface graphique. Sinon, il revient automatiquement à l'exécution en arrière-plan sans tête via idat.exe.

Pour des instructions détaillées sur la configuration du pont, voir GUI_INSTRUCTIONS.md.

Gestion des bases de données gigantesques (100k+ fonctions)

Lors du traitement de projets extrêmement volumineux, Diaphora MCP applique des optimisations spécifiques :

• Limite de récursion : La limite de récursion Python est automatiquement relevée à 100000 (sys.setrecursionlimit) pour éviter les plantages lors de grandes traversées de graphes d'appels.
• Optimisations des transactions SQLite : Dans votre diaphora_config.py, définir COMMIT_AFTER_EACH_GUI_UPDATE = False réduit les écritures sur disque, accélérant l'export graphique de 2 à 3 fois.
• Microcode Hex-Rays : Désactivez l'export du microcode (EXPORTING_USE_MICROCODE = False dans la configuration Diaphora) pour un export plus rapide lorsque le décompilateur n'est pas strictement nécessaire.

Intégration IDA Pro MCP

Les outils comme analyze_diff_results, compare_functions et find_function_match renvoient un bloc ida_pro_mcp contenant les adresses et les chemins. Ces informations peuvent être transmises directement aux outils ida-pro-mcp :

┃ # 1. Diaphora trouve une fonction suspecte
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP la décompile
┃ decompile_function(address="401000")

Exemples

Pour voir Diaphora MCP en action, consultez les exemples suivants :

• Transcription de session de base : Une présentation pas à pas d'une session MCP réelle avec les entrées/sorties JSON exactes pour chaque appel d'outil — de l'export à la comparaison de fonctions. Également disponible en russe.

Instructions pour les agents IA (Important)

Si vous êtes un assistant de codage IA (comme Claude Code) utilisant ce protocole, gardez à l'esprit les règles de compatibilité suivantes :

1. Schémas d'export graphique vs sans tête :

   • L'export via une session graphique active (plugin ida_mcp.py) produit un schéma personnalisé contenant des tables comme calls, strings, structures, mais pas de table program.
   • L'export sans tête (via idat.exe) produit le schéma officiel Diaphora contenant la table program.
   • Crucial : Le moteur de diff (diff_diaphora_dbs) nécessite le schéma officiel. Exportez toujours sans tête si vous prévoyez de comparer/différencier des bases.

2. Bases verrouillées dans l'interface graphique :

   • Une base de données actuellement ouverte dans l'interface graphique IDA Pro est verrouillée. Tenter de l'exporter sans tête échouera.
   • Si vous devez différencier la base actuellement ouverte, demandez à l'utilisateur de la fermer dans l'interface graphique (ou d'ouvrir une base factice) pour libérer le verrou du fichier, puis déclenchez un export sans tête.

3. Évitez les collisions de noms de bases :

   • Les bases d'export Diaphora sont nommées par défaut <basename>.diaphora.sqlite.

Statut de vérification et limitations

Les fixtures vérifiées sous IDA Pro 9.3 passent la suite de régression : 16 passed, 1 xpassed. Un export réel en conditions réelles et un diff Diaphora de deux DLL SQLite3 ont également été vérifiés. Les IDB volumineuses ou ouvertes dans l'interface graphique nécessitent toujours un verrou IDA libre, un DIAPHORA_OUTPUT_ROOT valide et un délai d'attente client MCP suffisamment grand.

Licence

MIT