unidbg

Consente di emulare una libreria nativa Android e una sperimentale emulazione iOS.

Questo è un progetto educativo per imparare di più sul formato file ELF/MachO e sull'assembly ARM.

Usalo a tuo rischio e pericolo!

Caratteristiche

• Supporto MCP (Model Context Protocol) per il debug assistito dall'AI con Cursor e altri strumenti AI.
• Emulazione dell'API JNI Invocation così che JNI_OnLoad possa essere chiamato.
• Supporta JavaVM, JNIEnv.
• Emulazione delle istruzioni syscall.
• Supporta ARM32 e ARM64.
• Hook inline, grazie a Dobby.
• Hook delle importazioni Android, grazie a xHook.
• Hook iOS con fishhook, substrate e whale.
• Il backend unicorn supporta un semplice debugger da console, stub gdb, traccia delle istruzioni, traccia di lettura/scrittura della memoria.
• Supporta il runtime objc e swift di iOS.
• Supporta il backend veloce dynarmic.
• Supporta l'hypervisor Apple M1, il backend ARM64 più veloce.
• Supporta il backend Linux KVM con Raspberry Pi B4.
• Rilevamento delle fughe di memoria per il codice nativo emulato con backtrace guest e stack trace host.

Debugger MCP (Integrazione AI)

unidbg supporta il Model Context Protocol (MCP) per il debug assistito dall'AI. Quando il debugger è attivo, digita mcp nella console per avviare un server MCP a cui gli strumenti AI (es. Cursor) possono connettersi.

Avvio rapido

L'MCP di unidbg ha due modalità operative:

Modalità 1: Debug con breakpoint — Collega il debugger ed esegui il tuo codice. Quando viene raggiunto un breakpoint, Breaker.debug() mette in pausa l'emulatore: digita mcp nella console per avviare il server MCP e lascia che l'AI assista con l'analisi. Tutti gli strumenti di debug sono disponibili (registri, memoria, disassembly, step, tracciamento, ecc.). Dopo la ripresa, se viene raggiunto un altro breakpoint, il debugger si mette di nuovo in pausa. Una volta che l'esecuzione termina senza raggiungere un breakpoint, il processo esce e l'MCP si spegne.

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

Modalità 2: Strumenti personalizzati (ripetibili) — Usa McpToolkit per registrare strumenti personalizzati e lascia che l'AI riesegua le funzioni target con parametri diversi. La libreria nativa viene caricata una sola volta; dopo ogni esecuzione il processo resta attivo e l'MCP rimane disponibile per l'esecuzione successiva.

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());

Quando il debugger si ferma, digita mcp (oppure mcp 9239 per specificare la porta) nella console. Poi aggiungi nelle impostazioni MCP di Cursor:

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

Strumenti MCP disponibili

Stato e informazioni

Tool	Description
check_connection	Stato dell'emulatore: famiglia, architettura, capacità del backend, isRunning, moduli caricati
list_modules / get_module_info	Elenca i moduli caricati, ottieni dettagli incluso il conteggio dei simboli esportati e le dipendenze
list_exports	Elenca i simboli esportati/dinamici di un modulo con filtro opzionale e demangling C++
find_symbol	Trova un simbolo per nome o trova il simbolo più vicino a un indirizzo
get_threads	Elenca tutti i thread/attività nell'emulatore

Registri e disassembly

Tool	Description
get_registers / get_register / set_register	Legge/scrive i registri della CPU
disassemble	Disassembla le istruzioni all'indirizzo (le destinazioni dei branch sono annotate automaticamente con i nomi dei simboli)
assemble	Assembla il testo delle istruzioni in codice macchina
get_callstack	Ottieni lo stack di chiamate corrente (backtrace)

Memoria

Tool	Description
read_memory / write_memory	Legge/scrive byte grezzi di memoria
read_string / read_std_string	Legge una stringa C o std::string C++ (con rilevamento SSO)
read_pointer	Legge una catena di puntatori con risoluzione dei simboli
read_typed	Legge la memoria come valori tipizzati (int8–int64, float, double, pointer)
search_memory	Cerca nella memoria pattern di byte con filtri di ambito/autorizzazioni
list_memory_map	Elenca tutte le mappature di memoria con le autorizzazioni
allocate_memory / free_memory / list_allocations	Alloca (malloc/mmap) con dati iniziali opzionali, libera e traccia i blocchi di memoria
patch	Scrive istruzioni assemblate in memoria

Breakpoint ed esecuzione

Tool	Description
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Aggiunge breakpoint per indirizzo, simbolo o modulo+offset
remove_breakpoint / list_breakpoints	Rimuove o elenca i breakpoint (con disassembly)
continue_execution	Riprende l'esecuzione. Usa poll_events per attendere breakpoint_hit o execution_completed
step_over / step_into / step_out	Esegue passo su, dentro (N istruzioni) o fuori dalla funzione
next_block	Interrompe al prossimo blocco di base (solo Unicorn)
step_until_mnemonic	Interrompe alla prossima istruzione che corrisponde al mnemonico, es. bl, ret (solo Unicorn)
poll_events	Esegue il polling di breakpoint_hit, execution_completed, eventi di traccia

Tracciamento

Tool	Description
trace_code	Traccia le istruzioni con i valori di lettura/scrittura dei registri (regs_read, prev_write)
trace_read / trace_write	Traccia letture/scritture di memoria in un intervallo di indirizzi

Chiamate di funzione

Tool	Description
call_function	Chiama una funzione nativa per indirizzo con argomenti tipizzati (hex, stringa, byte, null). Restituisce il valore con risoluzione dei simboli e anteprima della memoria
call_symbol	Chiama una funzione esportata per modulo + nome del simbolo, es. libc.so + malloc

Solo iOS (disponibile quando Family=iOS)

Tool	Description
inspect_objc_msg	Ispeziona la chiamata objc_msgSend: mostra il nome della classe del ricevente e il selettore, es. -[NSString length]
get_objc_class_name	Ottiene il nome della classe ObjC di un oggetto a un determinato indirizzo (pura analisi della memoria, nessuna modifica dello stato)
dump_objc_class	Estrae la definizione della classe ObjC (proprietà, metodi, protocolli, ivars)
dump_gpb_protobuf	Estrae lo schema del messaggio protobuf GPB in formato .proto (solo 64-bit)

Strumenti MCP personalizzati