Leer en ruso

Diaphora MCP

Diaphora MCP es un servidor MCP (Model Context Protocol) para el diffing automatizado de binarios. Conecta Diaphora (el motor de diffing) e IDA Pro (el desensamblador) mediante el protocolo MCP, permitiendo que agentes de IA (como Claude Code) realicen comparaciones de archivos binarios, encuentren parches de seguridad y analicen cambios.

Características

• Exportación: Convierte bases de datos .i64 / .idb analizadas al formato SQLite de Diaphora (mediante el modo sin interfaz de idat.exe)
• Diffing: Compara dos bases de datos exportadas, filtra resultados por tipo de coincidencia y ratio
• Análisis de Vulnerabilidades: Busca cambios relevantes para la seguridad usando coincidencia de palabras clave y heurísticas
• Detección de Parches: Detecta automáticamente nuevas comprobaciones de límites, comprobaciones nulas, manejo de errores y cambios criptográficos
• Clasificación: Clasifica las funciones cambiadas por importancia basándose en CFG, saltos de complejidad e indicadores de seguridad
• Grafo de Llamadas: Compara rutas de llamadas (BFS, hasta N niveles) y detecta cambios de causa raíz en cascadas de llamadas
• Transferencia de Metadatos: Prepara nombres, comentarios y prototipos para transferir entre bases de datos
• Integración con IDA Pro MCP: Todas las herramientas devuelven direcciones y rutas de bases de datos listas para ser pasadas directamente a las herramientas de IDA Pro MCP

Instalación

1. Dependencias

• Python 3.10+
• IDA Pro 8.x / 9.x (para exportaciones sin interfaz mediante idat.exe)
• Diaphora plugin instalado en IDA
• Claude Code (o cualquier otro cliente compatible con MCP)

2. Instalación del Paquete

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

3. Configuración de Rutas

El paquete intenta encontrar automáticamente IDA Pro y Diaphora en las ubicaciones de instalación estándar. Si no los encuentra, puede configurar las siguientes variables de entorno:

Para Claude Code, puede especificarlas en ~/.claude.json (o el archivo de configuración correspondiente de su cliente 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
    }
  }
}

Nota: Para binarios muy grandes (>100 MB), asegúrese de que el timeout sea al menos 7200 (2 horas).

3.1. Codex e IDA MCP sin interfaz gráfica

Codex normalmente usa dos servidores MCP complementarios:

• diaphora-mcp — este proyecto: exportación, diff con Diaphora y análisis de resultados;
• ida-pro-mcp — el servidor de inspección IDA upstream para idb_open, descompilación y análisis a nivel de dirección.

idalib-mcp es el backend sin interfaz de ida-pro-mcp, no un servidor Diaphora separado. Después de instalarlo, reinicie Codex:

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

Para este proyecto, una configuración stdio es suficiente:

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

4. Preparando Bases de Datos para el Diffing

IDA Pro debe analizar primero los binarios (creando archivos .i64 o .idb). Después de eso:

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

O ejecute el pipeline completo en un solo comando:

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

No pase .i64 directamente a las herramientas de resultados: es una base de datos de IDA, no SQLite. Expórtela primero.

Inicio Rápido

┃ # 1. Pipeline completo: exportar dos .i64 → diff → informe resumen
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. Si las bases de datos ya están exportadas
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. Análisis de seguridad de los resultados del diff
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. Clasificación por importancia de los cambios
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. Encontrar cambios de causa raíz
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. Detectar probables parches de seguridad
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. Generar informe completo
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

Ejemplo (Transcripción de Sesión en Vivo)

Consulte examples/basic-session.md para una transcripción completa paso a paso de una sesión real de Diaphora MCP, desde la exportación de dos bases de datos IDB hasta la comparación de funciones individuales. También disponible en ruso.

Aquí hay un adelanto de lo que devuelve el servidor:

Entrada — comparar dos DLLs de SQLite3 (2015 vs 2023):

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

Salida — resumen después de exportar + diff:

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

La sesión recorre 6 llamadas a herramientas MCP, mostrando el JSON exacto de entrada/salida para cada paso, junto con el razonamiento del agente.

Investigando una Base de Datos Individual

┃ # Obtener información de exportación de la base de datos
┃ get_export_info(db_path="app.sqlite")
 
┃ # Buscar funciones
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # Recuperar pseudocódigo
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

Estructura del Proyecto

diaphora-mcp/
├── diaphora_mcp_server.py          # Punto de entrada principal
├── diaphora_mcp/
│   ├── diaphora_mcp_server.py      # Registro de herramientas MCP
│   ├── config.py                   # Configuración de rutas y detección automática
│   ├── models.py                   # Constantes y modelos
│   ├── core/
│   │   ├── export.py               # Exportación sin interfaz, pipeline por lotes
│   │   ├── diff.py                 # Diffing y lector de resultados .diaphora
│   │   ├── analysis.py             # Búsqueda de funciones, comparación, explicación
│   │   ├── security.py             # Coincidencia de palabras clave, detección de parches
│   │   ├── ranking.py              # Clasificación por importancia
│   │   ├── graph.py                # Grafo de llamadas, árboles BFS, causa raíz
│   │   ├── metadata.py             # Preparación de metadatos (nombres, comentarios)
│   │   └── report.py               # Generación de informe general de parches
│   └── utils/
│       ├── sqlite.py               # Ayudantes SQLite
│       ├── format.py               # Diff de pseudocódigo, extracción de vectores de características
│       └── log.py                  # Utilidades de registro de exportación
├── _diaphora_headless.py           # Wrapper delgado para idat.exe -S
└── logs/                           # Registros de exportación automatizada (creados dinámicamente)

Referencia de Herramientas MCP (21 herramientas)

Exportación

Diff

Análisis

Seguridad

Clasificación

Grafo de Llamadas

Rendimiento

Metadatos

Integración con la GUI de IDA Pro (Puente XML-RPC)

El proyecto incluye integración incorporada con sesiones activas de la GUI de IDA Pro, permitiendo exportaciones instantáneas directamente desde ventanas de IDA activas sin conflictos de bloqueo de base de datos.

1. Inicio automático: Copie diaphora_gui_listener.py en su directorio plugins/ de IDA Pro. Iniciará un servidor XML-RPC en segundo plano en el puerto 28652 cada vez que IDA se inicie.
2. Exportación inteligente: Cuando se llama a export_idb_to_diaphora, el servidor MCP verifica el puerto 28652. Si hay una sesión activa, ejecuta la exportación directamente en la GUI. De lo contrario, vuelve automáticamente a la ejecución en segundo plano sin interfaz mediante idat.exe.

Para instrucciones detalladas sobre la configuración del puente, consulte GUI_INSTRUCTIONS.md.

Manejo de Bases de Datos Gigantes (100k+ funciones)

Al procesar proyectos extremadamente grandes, Diaphora MCP aplica optimizaciones específicas:

• Límite de recursión: El límite de recursión de Python se eleva automáticamente a 100000 (sys.setrecursionlimit) para evitar fallos durante recorridos grandes del grafo de llamadas.
• Optimizaciones de transacciones SQLite: En su diaphora_config.py, establecer COMMIT_AFTER_EACH_GUI_UPDATE = False reduce las escrituras en disco, acelerando la exportación desde la GUI entre 2 y 3 veces.
• Microcódigo de Hex-Rays: Desactive la exportación de microcódigo (EXPORTING_USE_MICROCODE = False en la configuración de Diaphora) para una exportación más rápida cuando el descompilador no sea estrictamente necesario.

Integración con IDA Pro MCP

Herramientas como analyze_diff_results, compare_functions y find_function_match devuelven un bloque ida_pro_mcp que contiene direcciones y rutas. Esta información se puede pasar directamente a las herramientas de ida-pro-mcp:

┃ # 1. Diaphora encuentra una función sospechosa
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP la descompila
┃ decompile_function(address="401000")

Ejemplos

Para ver Diaphora MCP en acción, consulte los siguientes ejemplos:

• Transcripción de Sesión Básica: Un recorrido real de una sesión MCP con JSON exacto de entrada/salida para cada llamada a herramienta, desde la exportación hasta la comparación de funciones. También disponible en ruso.

Directrices para Agentes de IA (Importante)

Si usted es un asistente de codificación de IA (como Claude Code) que usa este protocolo, tenga en cuenta las siguientes reglas de compatibilidad:

1. Esquemas de exportación GUI vs. sin interfaz:

   • Exportar mediante una sesión GUI activa (plugin ida_mcp.py) produce un esquema personalizado que contiene tablas como calls, strings, structures, pero no tiene tabla program.
   • La exportación sin interfaz (mediante idat.exe) produce el esquema oficial de Diaphora que contiene la tabla program.
   • Crucial: El motor de diff (diff_diaphora_dbs) requiere el esquema oficial. Exporte siempre sin interfaz si tiene la intención de comparar/hacer diff de bases de datos.

2. Bases de datos bloqueadas en la GUI:

   • Una base de datos actualmente abierta en la GUI de IDA Pro está bloqueada. Intentar exportarla sin interfaz fallará.
   • Si necesita hacer diff de la base de datos actualmente abierta, pida al usuario que la cierre en la GUI (o que abra una base de datos ficticia) para liberar el bloqueo del archivo, luego active una exportación sin interfaz.

3. Evite colisiones de nombres de bases de datos:

   • Las bases de datos de exportación de Diaphora por defecto tienen el nombre <basename>.diaphora.sqlite.
   • Nunca use <basename>.sqlite para exportaciones de Diaphora, ya que esto entra en conflicto con la base de datos de caché interna creada por el supervisor ida-pro-mcp.

Estado de verificación y limitaciones

Los fixtures verificados de IDA Pro 9.3 pasan el conjunto de regresión: 16 passed, 1 xpassed. También se verificaron una exportación real por etapas y un diff Diaphora de dos DLLs de SQLite3. Las IDBs grandes o abiertas en la GUI aún requieren un bloqueo libre de IDA, un DIAPHORA_OUTPUT_ROOT válido y un tiempo de espera del cliente MCP suficientemente grande.

Licencia

MIT