unidbg

Permite emular una librería nativa de Android, además de una emulación experimental de iOS.

Este es un proyecto educativo para aprender más sobre el formato de archivo ELF/MachO y el ensamblador ARM.

¡Úsalo bajo tu propio riesgo!

Características

• Soporte de MCP (Model Context Protocol) para depuración asistida por IA con Cursor y otras herramientas de IA.
• Emulación de la API de invocación JNI para que se pueda llamar a JNI_OnLoad.
• Soporta JavaVM y JNIEnv.
• Emulación de la instrucción syscalls.
• Soporta ARM32 y ARM64.
• Hook en línea, gracias a Dobby.
• Hook de importaciones de Android, gracias a xHook.
• Hooks de iOS con fishhook, substrate y whale.
• El backend unicorn admite un depurador de consola simple, stub de gdb, traza de instrucciones y traza de lectura/escritura de memoria.
• Soporta el runtime de objc y swift de iOS.
• Soporta el backend rápido dynarmic.
• Soporta el hipervisor de Apple M1, el backend ARM64 más rápido.
• Soporta el backend Linux KVM con Raspberry Pi B4.
• Detección de fugas de memoria para código nativo emulado con backtrace del invitado y stack trace del anfitrión.

Depurador MCP (Integración con IA)

unidbg es compatible con Model Context Protocol (MCP) para la depuración asistida por IA. Cuando el depurador está activo, escribe mcp en la consola para iniciar un servidor MCP al que las herramientas de IA (p. ej., Cursor) puedan conectarse.

Inicio rápido

El MCP de unidbg tiene dos modos de funcionamiento:

Modo 1: Depuración con puntos de interrupción — Adjunta el depurador y ejecuta tu código. Cuando se alcanza un punto de interrupción, Breaker.debug() pausa el emulador: escribe mcp en la consola para iniciar el servidor MCP y deja que la IA ayude con el análisis. Todas las herramientas de depuración están disponibles (registros, memoria, desensamblado, ejecución paso a paso, trazado, etc.). Tras reanudar, si se alcanza otro punto de interrupción, el depurador se pausa de nuevo. Cuando la ejecución finaliza sin alcanzar ningún punto de interrupción, el proceso termina y MCP se cierra.

Debugger debugger = emulator.attach();
debugger.addBreakPoint(address);
// run your emulation logic — debugger pauses when breakpoint is hit

Modo 2: Herramientas personalizadas (repetibles) — Usa McpToolkit para registrar herramientas personalizadas y deja que la IA vuelva a ejecutar las funciones objetivo con diferentes parámetros. La librería nativa se carga una sola vez; después de cada ejecución, el proceso permanece vivo y MCP sigue activo para la siguiente ejecución.

McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
    @Override public String name() { return "encrypt"; }
    @Override public String description() { return "Run encryption"; }
    @Override public String[] paramNames() { return new String[]{"input"}; }
    @Override public void execute(String[] params) {
        String input = params.length > 0 ? params[0] : "default";
        // call encryption with input
    }
});
toolkit.run(emulator.attach());

Cuando el depurador se detenga, escribe mcp (o mcp 9239 para especificar el puerto) en la consola. A continuación, añádelo a la configuración de MCP de Cursor:

{
  "mcpServers": {
    "unidbg-mcp-server": {
      "url": "http://localhost:9239/sse"
    }
  }
}

Herramientas MCP disponibles

Estado e información

Herramienta	Descripción
check_connection	Estado del emulador: Family, arquitectura, capacidades del backend, isRunning, módulos cargados
list_modules / get_module_info	Lista los módulos cargados y obtén detalles, incluidos el número de símbolos exportados y las dependencias
list_exports	Lista los símbolos exportados/dinámicos de un módulo con filtro opcional y demangling de C++
find_symbol	Busca un símbolo por nombre o el símbolo más cercano a una dirección
get_threads	Lista todos los hilos/tareas del emulador

Registros y desensamblado

Herramienta	Descripción
get_registers / get_register / set_register	Lee/escribe registros de la CPU
disassemble	Desensambla instrucciones en una dirección (los destinos de salto se anotan automáticamente con nombres de símbolos)
assemble	Ensambla texto de instrucción en código máquina
get_callstack	Obtén la pila de llamadas actual (backtrace)

Memoria

Herramienta	Descripción
read_memory / write_memory	Lee/escribe bytes de memoria en bruto
read_string / read_std_string	Lee una cadena C o un std::string de C++ (con detección de SSO)
read_pointer	Lee la cadena de punteros con resolución de símbolos
read_typed	Lee memoria como valores tipados (int8–int64, float, double, puntero)
search_memory	Busca en la memoria patrones de bytes con filtros de alcance/permisos
list_memory_map	Lista todos los mapeos de memoria con permisos
allocate_memory / free_memory / list_allocations	Asigna (malloc/mmap) con datos iniciales opcionales, libera y realiza el seguimiento de los bloques de memoria
patch	Escribe instrucciones ensambladas en memoria

Puntos de interrupción y ejecución

Herramienta	Descripción
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Añade puntos de interrupción por dirección, símbolo o módulo+offset
remove_breakpoint / list_breakpoints	Elimina o lista puntos de interrupción (con desensamblado)
continue_execution	Reanuda la ejecución. Usa poll_events para esperar breakpoint_hit o execution_completed
step_over / step_into / step_out	Paso por encima, paso hacia dentro (N instrucciones) o paso fuera de una función
next_block	Pausa en el siguiente bloque básico (solo Unicorn)
step_until_mnemonic	Pausa en la siguiente instrucción que coincida con el mnemónico, p. ej. bl, ret (solo Unicorn)
poll_events	Consulta eventos como breakpoint_hit, execution_completed y trace events

Trazado

Herramienta	Descripción
trace_code	Traza instrucciones con valores de lectura/escritura de registros (regs_read, prev_write)
trace_read / trace_write	Traza lecturas/escrituras de memoria en un rango de direcciones

Llamadas a funciones

Herramienta	Descripción
call_function	Llama a una función nativa por dirección con argumentos tipados (hex, string, bytes, null). Devuelve el valor con resolución de símbolos y vista previa de memoria
call_symbol	Llama a una función exportada por módulo + nombre de símbolo, p. ej. libc.so + malloc

Solo iOS (disponible cuando Family=iOS)

Herramienta	Descripción
inspect_objc_msg	Inspecciona la llamada objc_msgSend: muestra el nombre de la clase receptora y el selector, p. ej. -[NSString length]
get_objc_class_name	Obtén el nombre de la clase ObjC de un objeto en una dirección determinada (análisis de memoria puro, sin cambio de estado)
dump_objc_class	Vuelca la definición de la clase ObjC (propiedades, métodos, protocolos, ivars)
dump_gpb_protobuf	Vuelca el esquema de mensaje GPB protobuf en formato .proto (solo 64 bits)

Herramientas MCP personalizadas