[Version russe](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)

# Diaphora MCP

Comparez deux binaires analysés par IDA depuis votre assistant IA. Diaphora MCP exporte les bases de données IDA enregistrées, exécute [Diaphora](https://github.com/joxeankoret/diaphora), et permet à l'IA d'inspecter les fonctions correspondantes et leurs graphes d'appels.

L'interface par défaut comporte **10 outils** axés sur la comparaison. Diaphora fournit les correspondances ; l'IA lit le code réel et explique les changements.

[Démarrage rapide](#quick-start) · [Exemples](#examples) · [Outils](#tools) · [Dépannage](#troubleshooting)

```text
old.i64 + new.i64 → headless export → SQLite exports + diff results
                                       ↓
                            summary → matched code → call graph
```

## Prérequis

- Python 3.10+, IDA Pro avec `idat.exe`/`idat64`, et un plugin Diaphora installé.
- Les deux binaires analysés et enregistrés en bases de données `.i64`/`.idb`.
- Un client MCP local, tel que Codex, Claude Code ou Cursor.
- Un décompilateur Hex-Rays compatible uniquement si vous souhaitez du pseudocode.

IDA et Diaphora sont installés séparément. La validation du schéma de diff cible actuellement Diaphora **3.4.1** ; d'autres schémas peuvent nécessiter des mises à jour de compatibilité. L'interpréteur Python utilisé pour le diff doit avoir les dépendances autonomes de Diaphora installées.

## Démarrage rapide

### 1. Installer et créer un répertoire de sortie

```powershell
git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force C:\diaphora-outputs | Out-Null
```

### 2. Connecter le serveur MCP

Ajoutez cette entrée à la configuration MCP de votre client. Remplacez les chemins du dépôt, d'IDA et de Diaphora par vos chemins d'installation. Utilisez l'exécutable Python de l'environnement où vous avez installé ce projet.

```json
{
  "mcpServers": {
    "diaphora": {
      "command": "C:/src/diaphora-mcp/.venv/Scripts/python.exe",
      "args": ["C:/src/diaphora-mcp/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:/Program Files/IDA Professional 9.3/idat.exe",
        "DIAPHORA_DIR": "C:/Program Files/IDA Professional 9.3/plugins/diaphora",
        "DIAPHORA_OUTPUT_ROOT": "C:/diaphora-outputs"
      }
    }
  }
}
```

Le client lance le serveur via stdio ; il n'y a pas de service web séparé à démarrer. Redémarrez le serveur MCP après avoir modifié son code ou son environnement. Une connexion réussie expose les 10 outils listés ci-dessous.

### 3. Demandez à votre assistant de comparer les fichiers

```text
Use Diaphora to compare C:/analysis/old.i64 (old) against
C:/analysis/new.i64 (new). Save output under C:/diaphora-outputs/run-001.
Export headlessly with assembly detail, keep the exports, show a summary,
then inspect partial matches and explain the code changes in the interesting
functions. Use the result mapping when comparing functions and call graphs.
```

Choisissez un **répertoire d'exécution neuf** à chaque fois. Les cibles générées existantes ne sont jamais écrasées.

## Exemples

Les blocs JSON suivants sont des **arguments d'outils MCP**, et non des commandes shell. Votre assistant peut appeler directement les outils nommés. Les chemins et `0x401000` sont des exemples ; utilisez les chemins et adresses renvoyés par votre propre exécution.

### 1. Exporter et comparer deux bases de données IDA

Outil : **`batch_export_and_diff`**. L'ancien est toujours la première entrée, le nouveau la seconde.

```json
{
  "idb1_path": "C:/analysis/old.i64",
  "idb2_path": "C:/analysis/new.i64",
  "output_dir": "C:/diaphora-outputs/run-001",
  "export_mode": "headless",
  "use_decompiler": false,
  "summaries_only": false,
  "cleanup": false,
  "limit": 100,
  "unmatched_limit": 50
}
```

Cela conserve le détail de l'assembleur sans nécessiter Hex-Rays. Sélectionnez le profil d'export dont vous avez besoin :

| Détail | `use_decompiler` | `summaries_only` | Utilisation |
| --- | --- | --- | --- |
| Résumés de correspondance | `false` | `true` | Première passe rapide ; pas de code détaillé |
| Assembleur | `false` | `false` | Comparer le désassemblage sans décompilateur |
| Assembleur + pseudocode | `true` | `false` | Revue de code avec un décompilateur Hex-Rays compatible ; plus lent |

Récupérez toujours les chemins de sortie depuis la réponse :

```text
OLD_SQLITE = steps.export1.output
NEW_SQLITE = steps.export2.output
RESULTS    = steps.diff.output
```

Pour cet exemple, les fichiers générés sont `old.diaphora.sqlite`, `new.diaphora.sqlite` et `old_vs_new.diaphora` sous `run-001`. Des noms de base d'entrée identiques produisent des noms d'export distincts `old_`/`new_`. Conservez `cleanup=false` pour l'inspection ultérieure des fonctions.

### 2. Obtenir un résumé et inspecter les correspondances modifiées

Outil : **`get_diff_summary`**.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

Outil : **`get_diff_results`**. Cette page commence par les correspondances partielles à ratio plus faible.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora",
  "match_type": "partial",
  "min_ratio": 0.0,
  "limit": 50,
  "offset": 0,
  "unmatched_limit": 50,
  "unmatched_offset": 0,
  "sort_by": "ratio",
  "sort_order": "asc"
}
```

`partial` sélectionne une catégorie de correspondance Diaphora, et non une garantie de changement comportemental. Utilisez `match_type="all"` pour toutes les catégories prises en charge. La réponse inclut les décomptes par catégorie, le total filtré, les correspondances, les lignes non appariées, `next_offset` et `next_unmatched_offset`.

Pour continuer, copiez les prochains décalages renvoyés dans l'appel suivant, en conservant les mêmes filtres et le même tri. Par exemple, s'ils valent `50` et `50`, utilisez `offset=50` et `unmatched_offset=50`. Un prochain décalage `null` signifie que cette liste est terminée ; cessez de la faire avancer. Les deux listes progressent indépendamment. Les tailles de page doivent être positives et sont plafonnées à 5000. Utilisez `sort_order="desc"` pour inspecter d'abord les correspondances les plus fortes.

### 3. Comparer une fonction appariée et son graphe

Outil : **`compare_functions`**.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "address": "0x401000",
  "match_results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

La réponse contient `function_old`, `function_new`, l'assembleur/pseudocode disponible, les différences mesurées et les preuves d'identité. Vous pouvez utiliser `name` au lieu de `address`. Si les deux sélecteurs sont fournis, l'adresse est prioritaire ; omettez-la lors d'une sélection par nom.

Outil : **`get_changed_callgraph`** accepte les mêmes arguments ci-dessus. Il traduit les adresses correspondantes des appelants/appelés avant de signaler les changements, et sépare les voisins non résolus des différences d'arêtes confirmées.

Préférez les **adresses préfixées par `0x`** pour rendre l'entrée hexadécimale explicite. Fournissez `match_results_path` lorsqu'il est disponible : il gère le rebasage et les fonctions renommées. Des adresses égales seules n'établissent pas l'identité. Les correspondances ambiguës ou manquantes restent non résolues plutôt que d'être qualifiées de suppressions. Si vous avez vérifié manuellement une paire, vous pouvez fournir explicitement `address2` ou `name2`.

### 4. Trouver une fonction et lire son code

Outil : **`search_export_db`**. `name_pattern` utilise SQL LIKE : `%` correspond à n'importe quelle séquence.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "name_pattern": "%parse%",
  "min_instructions": 20,
  "limit": 20
}
```

Outil : **`get_function_pseudocode`** renvoie le pseudocode **et l'assembleur** disponibles, malgré son nom.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "address": "0x401000"
}
```

Si le pseudocode est vide, relancez l'export dans un nouveau répertoire d'exécution avec `use_decompiler=true` et `summaries_only=false`, en utilisant un décompilateur compatible. Utilisez `get_export_info` avec `db_path` pour inspecter les métadonnées d'export.

### 5. Comparer des exports que vous possédez déjà

Outil : **`diff_diaphora_dbs`**. Cela ignore l'export IDA et compare les exports SQLite officiels existants.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "output_path": "C:/diaphora-outputs/another-diff.diaphora"
}
```

Pour un nouvel export, utilisez `export_idb_to_diaphora` avec `idb_path`, un `output_path` neuf, et `export_mode="headless"`.

## Outils

| Outil | Objectif |
| --- | --- |
| `export_idb_to_diaphora` | Exporter une base de données IDA enregistrée |
| `batch_export_and_diff` | Exporter les deux bases de données et les comparer |
| `diff_diaphora_dbs` | Comparer des exports existants |
| `get_diff_summary` | Statistiques de correspondance et exemples bornés |
| `get_diff_results` | Résultats filtrés, triés, paginés |
| `get_export_info` | Métadonnées et décomptes d'export |
| `search_export_db` | Rechercher des fonctions |
| `get_function_pseudocode` | Lire l'assembleur/pseudocode |
| `compare_functions` | Comparer une paire ancien/nouveau résolue |
| `get_changed_callgraph` | Comparer les appelants/appelés mappés |

Les signatures exactes sont découvrables via MCP `tools/list`. Voir [Référence des outils](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md).

## Modes d'export et configuration

| Mode | Comportement |
| --- | --- |
| `headless` | Lancer IDA en mode headless et valider le schéma de diff ; recommandé pour les comparaisons |
| `auto` | Essayer le pont GUI actif, puis le repli headless |
| `gui` | Exiger la session GUI ouverte correcte ; pas de repli headless |

`batch_export_and_diff` nécessite `headless`.

| Variable d'environnement | Signification |
| --- | --- |
| `IDAT_PATH` | Chemin absolu vers l'exécutable headless d'IDA |
| `DIAPHORA_DIR` | Répertoire contenant les scripts Diaphora |
| `DIAPHORA_OUTPUT_ROOT` | Racine autorisée existante pour les nouveaux exports et résultats de diff |
| `DIAPHORA_PYTHON` | Interpréteur de diff facultatif ; par défaut, l'interpréteur du serveur MCP |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | Exactement `1` active l'interface précédente à 21 outils |

La correspondance héritée, les scores de caractéristiques, le triage de sécurité, les rapports, les métadonnées et les diagnostics restent optionnels. Pour les activer, ajoutez l'entrée suivante à l'objet `env` de la configuration et redémarrez :

```json
{
  "DIAPHORA_ENABLE_LEGACY_TOOLS": "1"
}
```

Ces outils utilisent des heuristiques ; leurs scores ne prouvent pas l'équivalence sémantique, les correctifs de sécurité ou la causalité. [Configuration](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [Configuration GUI](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md).

## Dépannage

| Symptôme | Action |
| --- | --- |
| La cible existe déjà | Utilisez un répertoire d'exécution ou un nom de fichier de sortie neuf |
| Sortie en dehors de la racine autorisée | Choisissez une destination sous `DIAPHORA_OUTPUT_ROOT` ; créez d'abord la racine |
| Base de données IDA transmise à un outil de résultats | Utilisez les exports `.diaphora.sqlite` renvoyés ou les résultats `.diaphora`, selon le cas |
| Contrepartie manquante/ambiguë | Vérifiez l'ordre ancien/nouveau et le mappage ; inspectez le candidat manuellement |
| Assembleur/pseudocode vide | Vérifiez le profil d'export ; obtenez un nouvel export détaillé |
| L'export/diff prend beaucoup de temps | Augmentez le délai d'attente du client MCP ; inspectez les `logs/` locaux ; envisagez une première passe en résumés uniquement |
| IDB verrouillé par une session IDA | Fermez la session ou utilisez le mode d'export GUI correspondant pour un export unique |
| Schéma non pris en charge | Réexportez avec la version de Diaphora prise en charge ; consultez les tables/colonnes manquantes signalées |

La correspondance reste heuristique ; un ratio élevé est une preuve, pas une démonstration. Les fonctions non appariées ne sont pas des ajouts/suppressions confirmés. Gardez les binaires, IDB, exports et journaux hors de Git. Voir [Flux de travail](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md), [Limitations](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md), et [Sécurité](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md).

## Développement

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q .
git diff --check
```

La suite de régression utilise des bases de données synthétiques et des processus IDA simulés. L'export IDA réel nécessite une validation d'intégration locale. [Contribution](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [Instructions pour l'agent](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md).
Télécharger l’outil
diaphora-mcp

Populaires
