ida-reverse

IDA Pro 逆向分析技能

ACCIÓN REQUERIDA (ejecutar inmediatamente después de leer)

1. AHORA: Leer ../field-journal/precedent-reverse.md — confirmar que la operación de este skill está autorizada y es rutinaria.
2. AHORA: Confirmar si la tarea actual está dentro del alcance de este skill.
3. SIGUIENTE: Leer ../tool-index.md para verificar la disponibilidad y rutas reales de las herramientas.
4. SIGUIENTE: Si faltan herramientas, invocar bootstrap; no adivinar rutas.
5. ACTUAR: Entrar al primer paso del "flujo de trabajo" y ejecutar; no quedarse en estado de confirmación.

Problemas conocidos y reflexiones (lectura obligada)

Errores ya cometidos

1. idb_open (antes idalib_open) no debe invocarse directamente desde el MCP de algunos clientes de IA

   • El cliente MCP de algunos asistentes de código tiene un bug en la validación del esquema de salida de herramientas tipo open.
   • Error: Structured content does not match the tool's output schema
   • Solución: Usar el script scripts/open.ps1 para invocar directamente a través de la API HTTP, evitando la capa de validación de MCP.
   • En la versión actual ida-pro-mcp 2.x, los nombres de las herramientas son idb_open / idb_list / idb_save (ya no idalib_*).
   • Tras abrir un archivo, se devuelve un session_id (database); las llamadas posteriores a herramientas deben incluir esta sesión.

2. Sin permisos para abrir archivos en C:\Windows\System32\

   • idalib no puede leer directamente archivos en el directorio System32.
   • Solución: open.ps1 detecta automáticamente la ruta y copia el archivo a un directorio temp antes de abrirlo.

3. El comando para iniciar el servidor bloquea la conversación

   • idalib-mcp al iniciarse genera continuamente logs INFO en la consola.
   • Solución: Usar scripts/start.ps1 (con -WindowStyle Hidden, se inicia silenciosamente en segundo plano).
   • El script espera a que el servicio esté listo y luego termina, sin bloquear la conversación.

4. El nombre del servidor MCP no puede contener guiones

   • Anteriormente se usaba ida-pro-mcp como nombre de servidor, lo que podía causar problemas de registro de herramientas.
   • Configuración actual: Nombre del servidor idapro, prefijo de herramientas idapro_*.

5. HTTP Remoto vs Stdio Local

   • Modo type:"local" (stdio): idalib_open también tiene problemas de validación de esquema.
   • Modo type:"remote" (HTTP): Se puede abrir el archivo primero con un script y luego usar las herramientas MCP.
   • Solución actual: Modo HTTP remoto.

6. PR #389 corrigió parte de los problemas de esquema

   • El autor mrexodia fusionó la corrección en PR #389 después del issue #388.
   • Se corrigió el esquema structuredContent en modo HTTP, pero la validación del lado de algunos clientes de IA sigue fallando.
   • Se ha instalado la última versión de la rama main.

7. El timeout de idalib deja procesos worker huérfanos bloqueando archivos

   • Si open.ps1 excede el tiempo de espera por primera vez, el proceso hijo python worker de idalib puede quedar huérfano, reteniendo los archivos .id0/.id1/.nam.
   • Cualquier herramienta posterior o al arrastrar el archivo a la GUI de IDA se reportará "permisos insuficientes".
   • Prohibido taskkill /F /T para matar el árbol de procesos — /T también matará al proceso hijo ida.exe de la GUI.
   • Solución: start.ps1 solo reemplaza al supervisor administrado cuando el puerto no está en escucha, o cuando tools/list responde rápido pero falta py_eval (supervisor antiguo). Si hay RPC timeout pero el puerto 13337 sigue escuchando, se considera ocupado, no se mata. Al abrir una base de datos, open.ps1 escribe opening.lock; el watchdog no debe usar -Force.
   • Excepción de interbloqueo: Si tools/list falla continuamente durante más de 3 minutos (según la marca de tiempo de last-healthy, no la hora de creación del proceso), y no hay un opening.lock en curso, y no es la GUI la que ocupa el puerto, entonces se usa -Force para reemplazar al supervisor, pero sin matar ida.exe.
   • Plan B: open.ps1 detecta que la base de datos antigua está bloqueada y automáticamente copia a Temp con un prefijo GUID.

8. Abrir con análisis automático parece que se queda colgado

   • idalib_open(run_auto_analysis=true) puede tardar mucho en responder, pero el backend sigue procesando la apertura y el análisis.
   • El usuario ve "PowerShell sin salida" y puede pensar que el script se ha colgado.
   • Solución actual: open.ps1 añade un -TimeoutSeconds y cambia a una solicitud en segundo plano + sondeo frontal + salida de progreso periódica.
   • Cuando el sondeo detecta que la sesión está lista, devuelve OK:nombre_archivo:session_id de forma anticipada; si se agota el tiempo, devuelve ERR:open_timeout_xxs.

9. El MCP HTTP puede cerrarse silenciosamente después del inicio de sesión

   • Cursor/Claude con type: http no lanza el proceso por sí mismo; la tarea programada antigua solo se ejecuta al iniciar sesión.
   • pythonw no tiene consola, y los logs de Application están vacíos si se cuelga.
   • Solución: start.ps1 reutiliza si está sano; watchdog.ps1 hace una comprobación por minuto; logs en %LOCALAPPDATA%\reverse-skill\ida-mcp\.
   • Instalación: scripts/install-autostart.ps1. Si el cliente HTTP arranca y el puerto aún no está listo, es necesario refrescar manualmente en el panel MCP.

10. Streamable HTTP GET /mcp puede bloquear el supervisor monohilo

    • Algunos clientes HTTP MCP envían una conexión GET larga a /mcp (SSE). El idalib_supervisor estándar usa HTTPServer con background=False, que solo maneja una solicitud a la vez.
    • Resultado: tools/list agota el tiempo de espera y el cliente marca idapro como error.
    • Solución: run-supervisor.py cambia el HTTP a ThreadingHTTPServer y acepta GET /mcp; si el parche falla, se omite y se inicia el supervisor de todas formas. Si se bloquea, usar scripts/recover.ps1 (inmediatamente con -Force).

Principios del flujo de trabajo

Paso	Qué hacer	Qué usar
1	Asegurar que el servidor HTTP está en ejecución	scripts/start.ps1 (sin argumentos)
2	Abrir el binario objetivo	scripts/open.ps1 -Path "xxx.exe"
3	Usar herramientas de análisis MCP	Llamar directamente a idapro_* / herramientas HTTP (aproximadamente 65, según la versión)
4	Análisis completado	Las herramientas están disponibles automáticamente

Recursos de scripts

start.ps1 — Iniciar el servidor HTTP MCP

Ruta: scripts/start.ps1

• Resuelve automáticamente IDADIR (variable de entorno / ruta de escritorio de la versión portátil / rutas de instalación comunes).
• Prioriza el uso de Python314\python.exe -m ida_pro_mcp.idalib_supervisor incluido con IDA.
• Por defecto, primero sondea http://127.0.0.1:13337/mcp; si está sano, imprime OK:<n>:reuse y termina.
• Si 13337 está escuchando pero tools/list agota el tiempo de espera → WARN:busy / OK:busy:reuse, no mata (no puede responder si la base de datos está abierta o la GUI ocupada).
• Si tools/list falla continuamente durante más de 3 minutos (marca de tiempo de last-healthy) y no hay opening.lock → se considera interbloqueo, imprime INFO:deadlock y usa -Force para reemplazar al supervisor. Las operaciones idb_open en curso y la GUI no pasan por esta ruta.
• Solo reemplaza al supervisor administrado cuando el puerto no está en escucha, falta py_eval, o se produce el interbloqueo anterior; nunca mata ida.exe, no usa taskkill /T.
• Si la GUI ocupa el puerto 13337, imprime WARN:gui_busy y termina, sin iniciar otro supervisor.
• Éxito: imprime OK:<número_de_herramientas> (actualmente alrededor de 66); fallo: imprime ERR:timeout.
• Logs del supervisor: %LOCALAPPDATA%\reverse-skill\ida-mcp\supervisor.log.
• El servidor se ejecuta en segundo plano, sin bloquear la conversación.

Forma de invocación:

powershell -File "<skill-root>\ida-reverse\scripts\start.ps1"

watchdog.ps1 / recover.ps1 / install-autostart.ps1 — Mantenimiento activo

• watchdog.ps1: Sondea 13337; si está sano, reutiliza (y refresca la marca de tiempo last-healthy); si está ocupado por GUI / bloqueo de open.ps1 / last-healthy con menos de 3 minutos → reutiliza; solo si tools/list falla continuamente durante más de 3 minutos ejecuta start.ps1 -Force.
• recover.ps1: Ejecuta start.ps1 -Force inmediatamente (sin matar ida.exe). Úsalo cuando el cliente HTTP marque idapro como error.
• install-autostart.ps1: Registra la tarea programada reverse-skill-ida-mcp (al iniciar sesión + cada minuto).
• Logs: %LOCALAPPDATA%\reverse-skill\ida-mcp\watchdog.log.

open.ps1 — Abrir un archivo binario

Ruta: scripts/open.ps1

• Invoca idb_open directamente a través de la API HTTP, evitando la validación de esquema de MCP.
• Detecta automáticamente rutas System32 y copia a un directorio temporal.
• Limpia automáticamente archivos de base de datos antiguos con el mismo nombre (.id0/.id1/.nam/.til/.i64).
• Si la base de datos antigua está bloqueada, degrada automáticamente: copia a Temp con un prefijo GUID y abre, sin errores.
• Coloca la solicitud de apertura en segundo plano para evitar esperas síncronas largas que dejen el script sin respuesta.
• Soporta -TimeoutSeconds; si se agota el tiempo, devuelve ERR:open_timeout_xxs, sin bloqueos infinitos.
• Cada 10 segundos imprime INFO:opening:tiempo_transcurrido/tiempo_máximo, para facilitar la evaluación de que el análisis sigue en curso.
• Éxito: imprime OK:nombre_archivo:session_id; en caso de degradación añade la marca (temp copy).
• Si falla, reintenta automáticamente usando una copia Temp.

Forma de invocación:

powershell -File "<skill-root>\ida-reverse\scripts\open.ps1" -Path "C:\ruta\al\archivo.exe"

Parámetros opcionales:

# Especificar SessionId
powershell -File "scripts\open.ps1" -Path "archivo.exe" -SessionId "mi_sesion"

# Omitir análisis automático (recomendado para archivos grandes)
powershell -File "scripts\open.ps1" -Path "grande.exe" -NoAutoAnalysis

# Establecer tiempo de espera, para evitar que el análisis automático prolongado deje sin respuesta
powershell -File "scripts\open.ps1" -Path "archivo.exe" -TimeoutSeconds 600

Convención de salida:

# Análisis en curso (cada 10 segundos)
INFO:opening:11/600s

# Apertura exitosa
OK:sample.exe:abcd1234

# Apertura exitosa, pero degradada a copia Temp por bloqueo de archivo
OK:1234abcd-sample.exe:abcd1234 (temp copy)

# Tiempo de espera agotado
ERR:open_timeout_600s

Notas de pruebas reales:

• Snipaste.exe con análisis automático tardó aproximadamente 324s en devolver éxito; no es un "bloqueo" sino "análisis prolongado".
• Por lo tanto, al encontrarse con programas GUI o muestras más complejas, se recomienda establecer explícitamente -TimeoutSeconds 600.

Lista de herramientas principales

Análisis general (primer paso)

• idapro_survey_binary(detail_level="minimal") — Resumen rápido: número de funciones, cadenas, segmentos, punto de entrada, clasificación de imports (cifrado/red/entrada/salida de archivos).
• idapro_list_funcs(queries) — Listar funciones (paginación, filtrado por nombre).
• idapro_list_globals(queries) — Listar variables globales.
• idapro_entity_query(kind, filter) — Consulta unificada: funciones/globales/imports/cadenas/nombres.

Descompilación y desensamblado

• idapro_decompile(addr) — Descompilar a pseudocódigo.
• idapro_disasm(addr, max_instructions=N) — Desensamblar.
• idapro_analyze_function(addr, include_asm=false) — Análisis completo (pseudocódigo + cadenas + constantes + llamantes + llamados + bloques).
• idapro_func_profile(queries) — Métricas de perfil de función.

Referencias cruzadas y flujo de datos

• idapro_xrefs_to(addrs) — Buscar quién referencia a la dirección objetivo.
• idapro_xref_query(addr, direction) — Consulta avanzada de xref (filtro por dirección/tipo).
• idapro_callees(addrs) — Lista de subfunciones.
• idapro_callgraph(roots, max_depth) — Grafo de llamadas.
• idapro_trace_data_flow(addr, direction, max_depth) — Trazado de flujo de datos (forward/backward).

Búsqueda

• idapro_find_regex(pattern, limit) — Búsqueda de cadenas con expresiones regulares.
• idapro_search_text(pattern) — Buscar texto en la lista de desensamblado.
• idapro_find_bytes(patterns, limit) — Búsqueda de patrones de bytes (comodín ?? soportado).
• idapro_find(type, targets) — Búsqueda avanzada (inmediatos/cadenas/referencias).

Memoria y datos

• idapro_get_bytes(addrs) — Leer bytes originales.
• idapro_get_string(addrs) — Leer cadenas.
• idapro_get_int(queries) — Leer valores enteros.
• idapro_get_global_value(queries) — Leer valor de variable global.
• idapro_read_struct(queries) — Leer valor de campo de estructura.
• idapro_search_structs(filter) — Buscar estructuras.

Operaciones de modificación

• idapro_set_comments(items) — Añadir comentarios (sincronización bidireccional desensamblado+descompilado).
• idapro_append_comments(items) — Añadir comentarios al final.
• idapro_rename(batch) — Renombrar por lotes (funciones/globales/locales/variables de pila).
• idapro_patch_asm(items) — Parchear instrucciones ensamblador.
• idapro_patch(patches) — Parchear bytes.
• idapro_define_func(items) — Definir función.
• idapro_undefine(items) — Deshacer definición.
• idapro_define_code(items) — Convertir bytes a código.

Sistema de tipos

• idapro_declare_type(decls) — Declarar estructuras C/enumeraciones/uniones.
• idapro_set_type(edits) — Aplicar tipo a funciones/globales/locales.
• idapro_infer_types(addrs) — Inferir tipos.
• idapro_type_query(queries) — Consultar tipos declarados.
• idapro_type_inspect(queries) — Ver detalles de tipo.

Marco de pila

• idapro_stack_frame(addrs) — Ver variables del marco de pila.
• idapro_declare_stack(items) — Declarar variable de pila.
• idapro_delete_stack(items) — Eliminar variable de pila.

Firmas

• idapro_make_signature(addrs) — Generar firma de bytes única para una dirección.
• idapro_make_signature_for_function(addrs) — Generar firma para una función.
• idapro_find_xref_signatures(addrs) — Generar firmas para el código que referencia a una dirección.

Depurador (requiere ?ext=dbg)

• idapro_open_file(file_path) — Abrir archivo en una instancia GUI de IDA.
• Las herramientas de depurador están ocultas por defecto; se activan con el parámetro URL ?ext=dbg.

Gestión de sesiones (ida-pro-mcp 2.x)

• idapro_idb_open / HTTP idb_open — ⚠️ Se recomienda usar open.ps1 para abrir.
• idapro_idb_list / HTTP idb_list — Listar todas las sesiones.
• idapro_idb_save / HTTP idb_save — Guardar la base de datos.
• La mayoría de las herramientas de análisis requieren el parámetro database=<session_id> (la sesión devuelta por open.ps1).

Otras

• idapro_int_convert(inputs) — Conversión entre bases (¡debes usar esto, no conviertas manualmente!).
• idapro_export_funcs(addrs, format) — Exportar funciones (json/c_header/prototypes).
• idapro_py_eval(code) — Ejecutar Python en el contexto de IDA.
• idapro_server_health() — Comprobación de salud del servidor.
• idapro_server_warmup() — Calentar subsistemas (caché de cadenas, Hex-Rays, etc.).

Flujo de trabajo completo de análisis inverso

Paso 1: Iniciar el servidor

Ruta A — Headless idalib (requiere licencia válida)

powershell -File "scripts/start.ps1"

Salida OK:<número de herramientas> (actualmente alrededor de 65) indica que está listo.

Ruta B — GUI + plugin (cuando la licencia de idalib falla o se necesita análisis interactivo)

powershell -File "scripts/start-gui.ps1" -Path "C:\objetivo.exe"

o haga doble clic en Launch-IDA-Pro.cmd de la versión portátil, abra la muestra en IDA.

Confirme que en la ventana Output aparece [MCP] ... port=13337; entonces las herramientas MCP estarán disponibles.

Los pasos de integración general se encuentran en LOCAL-SETUP.md.

Paso 2: Abrir el archivo

Headless:

powershell -File "scripts/open.ps1" -Path "C:\objetivo.exe" -TimeoutSeconds 600

Salida OK:nombre_archivo:session_id indica éxito (si va seguido de (temp copy), se ha degradado automáticamente a una copia temporal).

Si aparece ERR:idalib_license:..., cambie a la Ruta B (modo GUI); no intente repetir open.ps1 varias veces.

Modo GUI: simplemente abra la muestra directamente en IDA; no necesita open.ps1.

Paso 3: Visión general global (incluye puerta obligatoria de tabla de imports)

idapro_survey_binary(detail_level="minimal")

Preste atención a:

• Arquitectura (x86/x64/ARM)
• Punto de entrada (main/WinMain/DllMain)
• Cadenas interesantes (URL, rutas, mensajes de error)
• Clasificación de imports (DEBE HACERSE): funciones de cifrado / API de red / operaciones de archivos / inyección de procesos / registro — debe registrarse como Evidence (sugerencia: id E-imports). Puede usar idapro_entity_query(kind="imports") o la sección imports de la salida de survey.
• DLL/SYS: tabla de exportaciones y tabla de imports en paralelo (Evidence E-exports).
• .NET: cuando no haya IAT tradicional, use un resumen de módulos/metadatos/referencias administradas como anclaje equivalente y escríbalo en el slot semántico E-imports.
• Tabla de imports limpia: indique sospecha de carga dinámica y promueva la verificación de breakpoints de API dinámicos.
• Funciones populares (funciones con alto recuento de xref suelen ser lógica clave).

Puerta obligatoria: antes de escribir la vista de imports/resumen de clasificación (o un anclaje equivalente válido) en Evidence, NO DEBE pasar al Paso 4 para profundizar conclusiones, NI declarar que el survey está completo. Si la tabla de imports está vacía o la consulta falla, DEBE registrar el fallo. Si la reparación del IAT con packer falla, DEBE registrar E-iat-repair-fail y pasar a depuración dinámica para capturar APIs; está prohibido estancarse en análisis estático. Si el usuario solicita rehacer la verificación de imports/IAT, DEBE rehacer el paso indicado (si está bloqueado, use el pestillo de viabilidad: explicar + confirmar; si es forzoso, marque quality=unreadable); está prohibido cambiar a pasos no relacionados.

Paso 4: Profundizar en funciones clave

idapro_analyze_function(addr="nombre_función_clave")

o:

idapro_decompile(addr="nombre_función")
idapro_disasm(addr="nombre_función", max_instructions=50)

Paso 5: Flujo de datos y referencias cruzadas

idapro_xrefs_to(addrs="dirección/cadena clave")
idapro_callgraph(roots=["función clave"], max_depth=3)
idapro_trace_data_flow(addr="dirección clave", direction="backward", max_depth=5)

Paso 6: Documentar y optimizar

idapro_set_comments(items=[{"addr": "0x140001000", "comment": "tu interpretación"}])
idapro_rename(batch={"func": [{"addr": "dirección de función", "name": "nombre significativo"}]})

Paso 7: Generar informe

Después del análisis, genere report.md documentando los hallazgos y pasos.

Principios de ingeniería de prompts

1. No convierta bases manualmente — en cualquier momento que necesite convertir números, use idapro_int_convert.
2. Primero survey, luego profundizar — primero vea el panorama general, luego analice de forma selectiva.
3. Añada comentarios y renombre continuamente — durante el análisis, actualice nombres de funciones y variables para mejorar la precisión de análisis posteriores.
4. Siga las referencias cruzadas — si encuentra datos/cadenas interesantes, use xrefs_to para ver quién las referencia.
5. Código ofuscado — primero realice preprocesamiento como descifrado de cadenas, eliminación de hash de imports, eliminación de ofuscación de flujo de control.
6. Código C++ STL — use FLIRT/Lumina para identificar funciones de biblioteca, luego analice la lógica de negocio.
7. No use fuerza bruta — el análisis debe derivar soluciones del desensamblado, use Python simple para cálculos auxiliares.
8. Si encuentra "No database bound" — aún no se ha abierto ningún archivo binario; ejecute open.ps1 primero.
9. Si encuentra "Failed to open database" — puede deberse a que la base de datos anterior está bloqueada; open.ps1 degradará automáticamente a una copia Temp (salida con marca (temp copy)).
10. Al abrir GUI/muestras complejas con análisis automático — añada por defecto -TimeoutSeconds 600; no confunda INFO:opening:... prolongado con un script colgado.

---

Contexto de ruteo

Entrada ascendente: skills/SKILL.md (controlador general), routing.md Alternativa ascendente: radare2/ (si no quiere abrir IDA, puede hacer un reconocimiento rápido con r2 primero) Salida descendente:

• Si necesita verificación dinámica con Frida → reverse-engineering/tools-dynamic.md
• Si necesita ejecución simbólica/angr → reverse-engineering/tools-dynamic.md
• Si necesita metodología general de reversing → reverse-engineering/SKILL.md

Módulos relacionados del mismo nivel: radare2/ (alternativa cuando IDA no está disponible)

---

Autoinicio bajo demanda (On-Demand Bootstrap)

Los scripts de entrada de este skill están integrados en el sistema de autoinicio unificado.

Límites de capacidad automatizada

Herramienta	Instalable automáticamente	Método de instalación	Descripción
idalib-mcp	✓	pip install (desde GitHub)	Se instala automáticamente si falta start.ps1
IDA Pro (núcleo)	✗	Software comercial, instalación manual	Configure la variable de entorno IDADIR apuntando al directorio de instalación

Pasos de instalación (verificados)

# 1. Establecer ruta de IDA (reemplazar con su directorio real de instalación de IDA)
setx IDADIR "<su_directorio_de_instalación_de_IDA>"

# 2. Instalar ida-pro-mcp desde GitHub (el paquete ida-mcp en PyPI es otro proyecto, ¡no lo instale!)
pip install git+https://github.com/mrexodia/ida-pro-mcp.git

# 3. Instalar el plugin de IDA (seleccionar Streamable HTTP + Global + todos los clientes)
ida-pro-mcp --install

# 4. Reiniciar IDA Pro, abrir el archivo objetivo
# El plugin escucha automáticamente en 127.0.0.1:13337

# 5. Verificar
ida-pro-mcp --config

⚠️ Nota: El paquete ida-mcp en PyPI (autor jtsylve) es otro proyecto, no el que necesitamos. Debe instalar mrexodia/ida-pro-mcp desde GitHub.

Puntos de activación del autoinicio

• scripts/start.ps1: si falta idalib-mcp, llama automáticamente a bootstrap-reverse.ps1.
• Registro MCP: bootstrap escribe automáticamente idapro en la configuración MCP de Claude.

Requisitos previos

• IDA Pro instalado y variable de entorno IDADIR configurada (o que las rutas por defecto dentro del script sean correctas).
• Se recomienda usar ida-pro-mcp desde el Python314 incluido con IDA (ya está integrado en la versión portátil).
• Configuraciones locales comunes:
  • User env IDADIR → directorio de instalación de IDA (que contenga ida.exe).
  • Opcional: wrapper ~\Tools\bin\idalib-mcp.cmd / ida-pro-mcp.cmd.
  • En la configuración MCP del cliente, dejar solo el nombre de servidor idapro → http://127.0.0.1:13337/mcp.

---

Autocomprobación de tarea completada (DEBE pasar antes de declarar finalización)

• ¿Ejecuté cada paso del flujo de trabajo (no solo lo leí)?
• ¿El survey/imports ya está escrito en Evidence (E-imports o equivalente)? ¿Para DLL/SYS incluye E-exports? ¿Si falló IAT, se registró E-iat-repair-fail?
• Si el usuario solicitó rehacer la tabla de imports/IAT, ¿rehice exactamente ese paso?
• ¿Usé rutas reales de herramientas basadas en tool-index?
• ¿Produje evidencia reproducible (comandos/scripts/capturas de pantalla/informes)?
• ¿Completé y devolví los elementos de la Checklist requerida por las RULES?