unidbg

Permet d'émuler une bibliothèque native Android, ainsi qu'une émulation iOS expérimentale.

Ceci est un projet pédagogique pour en apprendre davantage sur les formats de fichiers ELF/MachO et l'assembleur ARM.

À utiliser à vos risques et périls !

Fonctionnalités

• Prise en charge de MCP (Model Context Protocol) pour le débogage assisté par IA avec Cursor et d'autres outils d'IA.
• Émulation de l'API JNI Invocation afin que JNI_OnLoad puisse être appelé.
• Prise en charge de JavaVM, JNIEnv.
• Émulation de l'instruction syscalls.
• Prise en charge d'ARM32 et ARM64.
• Hook inline, grâce à Dobby.
• Hook des imports Android, grâce à xHook.
• Hooks iOS fishhook, substrate et whale.
• Backend unicorn avec débogueur console simple, stub gdb, trace d'instructions, trace de lectures/écritures mémoire.
• Prise en charge du runtime iOS objc et swift.
• Prise en charge du backend rapide dynarmic.
• Prise en charge de l'hyperviseur Apple M1, le backend ARM64 le plus rapide.
• Prise en charge du backend Linux KVM avec Raspberry Pi B4.
• Détection de fuites mémoire pour le code natif émulé avec backtrace invitée et trace de pile hôte.

Débogueur MCP (Intégration IA)

unidbg prend en charge le Model Context Protocol (MCP) pour le débogage assisté par IA. Lorsque le débogueur est actif, tapez mcp dans la console pour démarrer un serveur MCP auquel les outils d'IA (ex. Cursor) peuvent se connecter.

Démarrage rapide

Le MCP d'unidbg a deux modes de fonctionnement :

Mode 1 : Débogage par point d'arrêt — Attachez le débogueur et exécutez votre code. Lorsqu'un point d'arrêt est atteint, Breaker.debug() met l'émulateur en pause — tapez mcp dans la console pour démarrer le serveur MCP et laisser l'IA vous assister dans l'analyse. Tous les outils de débogage sont disponibles (registres, mémoire, désassemblage, pas à pas, traçage, etc.). Après la reprise, si un autre point d'arrêt est atteint, le débogueur se remet en pause. Une fois l'exécution terminée sans atteindre de point d'arrêt, le processus se termine et le MCP s'arrête.

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

Mode 2 : Outils personnalisés (réutilisables) — Utilisez McpToolkit pour enregistrer des outils personnalisés et laisser l'IA réexécuter les fonctions cibles avec différents paramètres. La bibliothèque native est chargée une seule fois ; après chaque exécution, le processus reste actif et le MCP demeure disponible pour l'exécution suivante.

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

Lorsque le débogueur s'arrête, tapez mcp (ou mcp 9239 pour spécifier le port) dans la console. Ajoutez ensuite aux paramètres MCP de Cursor :

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

Outils MCP disponibles

Statut et informations

Outil	Description
check_connection	Statut de l'émulateur : famille, architecture, capacités du backend, isRunning, modules chargés
list_modules / get_module_info	Lister les modules chargés, obtenir les détails incluant le nombre de symboles exportés et les dépendances
list_exports	Lister les symboles exportés/dynamiques d'un module avec filtre optionnel et démangling C++
find_symbol	Trouver un symbole par nom ou trouver le symbole le plus proche d'une adresse
get_threads	Lister tous les threads/tâches de l'émulateur

Registres et désassemblage

Outil	Description
get_registers / get_register / set_register	Lire/écrire les registres CPU
disassemble	Désassembler les instructions à une adresse (les cibles de branchement sont automatiquement annotées avec les noms de symboles)
assemble	Assembler le texte d'une instruction en code machine
get_callstack	Obtenir la pile d'appels actuelle (backtrace)

Mémoire

Outil	Description
read_memory / write_memory	Lire/écrire des octets mémoire bruts
read_string / read_std_string	Lire une chaîne C ou une std::string C++ (avec détection SSO)
read_pointer	Lire une chaîne de pointeurs avec résolution de symboles
read_typed	Lire la mémoire sous forme de valeurs typées (int8–int64, float, double, pointeur)
search_memory	Rechercher des motifs d'octets en mémoire avec filtres de portée/permissions
list_memory_map	Lister tous les mappings mémoire avec leurs permissions
allocate_memory / free_memory / list_allocations	Allouer (malloc/mmap) avec données initiales optionnelles, libérer et suivre les blocs mémoire
patch	Écrire des instructions assemblées en mémoire

Points d'arrêt et exécution

Outil	Description
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Ajouter des points d'arrêt par adresse, symbole ou module+offset
remove_breakpoint / list_breakpoints	Supprimer ou lister les points d'arrêt (avec désassemblage)
continue_execution	Reprendre l'exécution. Utilisez poll_events pour attendre breakpoint_hit ou execution_completed
step_over / step_into / step_out	Pas à pas au-dessus, à l'intérieur (N instructions) ou à l'extérieur d'une fonction
next_block	S'arrêter au prochain bloc de base (Unicorn uniquement)
step_until_mnemonic	S'arrêter à la prochaine instruction correspondant au mnémonique, ex. bl, ret (Unicorn uniquement)
poll_events	Interroger les événements breakpoint_hit, execution_completed, trace

Traçage

Outil	Description
trace_code	Tracer les instructions avec les valeurs de lecture/écriture des registres (regs_read, prev_write)
trace_read / trace_write	Tracer les lectures/écritures mémoire dans une plage d'adresses

Appels de fonctions

Outil	Description
call_function	Appeler une fonction native par adresse avec des arguments typés (hex, chaîne, octets, null). Renvoie la valeur avec résolution de symboles et aperçu mémoire
call_symbol	Appeler une fonction exportée par module + nom de symbole, ex. libc.so + malloc

iOS uniquement (disponible lorsque Family=iOS)

Outil	Description
inspect_objc_msg	Inspecter un appel objc_msgSend : afficher le nom de la classe du récepteur et le sélecteur, ex. -[NSString length]
get_objc_class_name	Obtenir le nom de classe ObjC d'un objet à une adresse donnée (pur parsing mémoire, sans changement d'état)
dump_objc_class	Extraire la définition d'une classe ObjC (propriétés, méthodes, protocoles, ivars)
dump_gpb_protobuf	Extraire le schéma d'un message protobuf GPB au format .proto (64 bits uniquement)

Outils MCP personnalisés