unidbg

Ermöglicht die Emulation einer nativen Android-Bibliothek sowie eine experimentelle iOS-Emulation.

Dies ist ein Bildungsprojekt, um mehr über das ELF/MachO-Dateiformat und ARM-Assembly zu lernen.

Nutzung auf eigene Gefahr!

Features

• Unterstützung von MCP (Model Context Protocol) für KI-gestütztes Debugging mit Cursor und anderen KI-Tools.
• Emulation der JNI-Invocation-API, sodass JNI_OnLoad aufgerufen werden kann.
• Unterstützung von JavaVM, JNIEnv.
• Emulation von Syscall-Instruktionen.
• Unterstützung von ARM32 und ARM64.
• Inline-Hook, dank Dobby.
• Android-Import-Hook, dank xHook.
• iOS-fishhook-, Substrate- und whale-Hooks.
• unicorn-Backend mit einfachem Konsolen-Debugger, gdb-Stub, Instruction-Trace, Memory-Read/Write-Trace.
• Unterstützung der iOS-Objc- und Swift-Laufzeit.
• Unterstützung des schnellen dynarmic-Backends.
• Unterstützung des Apple-M1-Hypervisors, dem schnellsten ARM64-Backend.
• Unterstützung des Linux-KVM-Backends mit Raspberry Pi B4.
• Speicherleck-Erkennung für emulierten nativen Code mit Guest-Backtrace und Host-Stack-Trace.

MCP-Debugger (KI-Integration)

unidbg unterstützt das Model Context Protocol (MCP) für KI-gestütztes Debugging. Wenn der Debugger aktiv ist, gib mcp in der Konsole ein, um einen MCP-Server zu starten, mit dem sich KI-Tools (z. B. Cursor) verbinden können.

Schnellstart

Das unidbg-MCP hat zwei Betriebsmodi:

Modus 1: Breakpoint-Debug — Debugger anhängen und den Code ausführen. Wenn ein Breakpoint erreicht wird, pausiert Breaker.debug() den Emulator — gib mcp in der Konsole ein, um den MCP-Server zu starten und der KI die Analyse zu überlassen. Alle Debugging-Werkzeuge sind verfügbar (Register, Speicher, Disassembly, Stepping, Tracing usw.). Nach dem Fortsetzen pausiert der Debugger erneut, wenn ein weiterer Breakpoint erreicht wird. Sobald die Ausführung ohne Breakpoint abgeschlossen ist, endet der Prozess und MCP wird heruntergefahren.

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

Modus 2: Benutzerdefinierte Tools (wiederholbar) — Verwende McpToolkit, um benutzerdefinierte Tools zu registrieren und der KI zu erlauben, Zielfunktionen mit verschiedenen Parametern erneut auszuführen. Die native Bibliothek wird einmal geladen; nach jeder Ausführung bleibt der Prozess aktiv und MCP bleibt für den nächsten Lauf verfügbar.

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

Wenn der Debugger unterbricht, gib mcp (oder mcp 9239, um einen Port anzugeben) in der Konsole ein. Füge dann Folgendes zu den MCP-Einstellungen von Cursor hinzu:

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

Verfügbare MCP-Tools

Status & Informationen

Tool	Beschreibung
check_connection	Emulatorstatus: Familie, Architektur, Backend-Fähigkeiten, isRunning, geladene Module
list_modules / get_module_info	Geladene Module auflisten, Details inklusive Anzahl exportierter Symbole und Abhängigkeiten abrufen
list_exports	Exportierte/dynamische Symbole eines Moduls auflisten, mit optionalem Filter und C++-Demangling
find_symbol	Symbol anhand des Namens suchen oder nächstgelegenes Symbol an einer Adresse finden
get_threads	Alle Threads/Tasks im Emulator auflisten

Register & Disassembly

Tool	Beschreibung
get_registers / get_register / set_register	CPU-Register lesen/schreiben
disassemble	Anweisungen an einer Adresse disassemblieren (Branch-Ziele werden automatisch mit Symbolnamen annotiert)
assemble	Anweisungstext zu Maschinencode assemblieren
get_callstack	Aktuellen Aufrufstapel (Backtrace) abrufen

Speicher

Tool	Beschreibung
read_memory / write_memory	Rohe Speicherbytes lesen/schreiben
read_string / read_std_string	C-String oder C++-std::string lesen (mit SSO-Erkennung)
read_pointer	Zeigerkette mit Symbolauflösung lesen
read_typed	Speicher als typisierte Werte lesen (int8–int64, float, double, pointer)
search_memory	Speicher nach Bytemustern mit Bereichs-/Berechtigungsfiltern durchsuchen
list_memory_map	Alle Speicher-Mappings mit Berechtigungen auflisten
allocate_memory / free_memory / list_allocations	Speicher zuweisen (malloc/mmap) mit optionalen Initialdaten, freigeben und Speicherblöcke verfolgen
patch	Assemblierte Anweisungen in den Speicher schreiben

Breakpoints & Ausführung

Tool	Beschreibung
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Breakpoints per Adresse, Symbol oder Modul+Offset hinzufügen
remove_breakpoint / list_breakpoints	Breakpoints entfernen oder auflisten (mit Disassembly)
continue_execution	Ausführung fortsetzen. Verwende poll_events, um auf breakpoint_hit oder execution_completed zu warten
step_over / step_into / step_out	Schritt über, hinein (N Anweisungen) oder aus einer Funktion
next_block	Am nächsten Basic Block anhalten (nur Unicorn)
step_until_mnemonic	An der nächsten Anweisung anhalten, die dem Mnemonic entspricht, z. B. bl, ret (nur Unicorn)
poll_events	Auf breakpoint_hit-, execution_completed- und Trace-Ereignisse warten

Tracing

Tool	Beschreibung
trace_code	Anweisungen mit Register-Read/Write-Werten verfolgen (regs_read, prev_write)
trace_read / trace_write	Speicherzugriffe (Lese-/Schreibvorgänge) in einem Adressbereich verfolgen

Funktionsaufrufe

Tool	Beschreibung
call_function	Native Funktion per Adresse mit typisierten Argumenten aufrufen (hex, string, bytes, null). Gibt den Wert mit Symbolauflösung und Speichervorschau zurück
call_symbol	Exportierte Funktion per Modul + Symbolname aufrufen, z. B. libc.so + malloc

Nur iOS (verfügbar wenn Family=iOS)

Tool	Beschreibung
inspect_objc_msg	objc_msgSend-Aufruf untersuchen: Empfänger-Klassennamen und Selektor anzeigen, z. B. -[NSString length]
get_objc_class_name	ObjC-Klassennamen eines Objekts an einer bestimmten Adresse abrufen (reine Speicheranalyse, keine Zustandsänderung)
dump_objc_class	ObjC-Klassendefinition ausgeben (Properties, Methoden, Protokolle, Ivars)
dump_gpb_protobuf	GPB-Protobuf-Nachrichtenschema als .proto-Format ausgeben (nur 64-Bit)

Benutzerdefinierte MCP-Tools