unidbg

Allows you to emulate an Android native library, and an experimental iOS emulation.

This is an educational project to learn more about the ELF/MachO file format and ARM assembly.

Use it at your own risk !

Features

• Support MCP (Model Context Protocol) for AI-assisted debugging with Cursor and other AI tools.
• Emulation of the JNI Invocation API so JNI_OnLoad can be called.
• Support JavaVM, JNIEnv.
• Emulation of syscalls instruction.
• Support ARM32 and ARM64.
• Inline hook, thanks to Dobby.
• Android import hook, thanks to xHook.
• iOS fishhook and substrate and whale hook.
• unicorn backend support simple console debugger, gdb stub, instruction trace, memory read/write trace.
• Support iOS objc and swift runtime.
• Support dynarmic fast backend.
• Support Apple M1 hypervisor, the fastest ARM64 backend.
• Support Linux KVM backend with Raspberry Pi B4.
• Memory leak detection for emulated native code with guest backtrace and host stack trace.

MCP Debugger (AI Integration)

unidbg supports Model Context Protocol (MCP) for AI-assisted debugging. When the debugger is active, type mcp in the console to start an MCP server that AI tools (e.g. Cursor) can connect to.

Quick Start

unidbg MCP has two operating modes:

Mode 1: Breakpoint Debug — Attach the debugger and run your code. When a breakpoint is hit, Breaker.debug() pauses the emulator — type mcp in the console to start MCP server and let AI assist with analysis. All debugging tools are available (registers, memory, disassembly, stepping, tracing, etc). After resuming, if another breakpoint is hit the debugger pauses again. Once execution completes without hitting a breakpoint, the process exits and MCP shuts down.

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

Mode 2: Custom Tools (Repeatable) — Use McpToolkit to register custom tools and let AI re-run target functions with different parameters. The native library is loaded once; after each execution the process stays alive and MCP remains active for the next run.

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

When the debugger breaks, type mcp (or mcp 9239 to specify port) in the console. Then add to Cursor MCP settings:

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

Available MCP Tools

Status & Info

Tool	Description
check_connection	Emulator status: Family, architecture, backend capabilities, isRunning, loaded modules
list_modules / get_module_info	List loaded modules, get detail including exported symbol count and dependencies
list_exports	List exported/dynamic symbols of a module with optional filter and C++ demangling
find_symbol	Find symbol by name or find nearest symbol at address
get_threads	List all threads/tasks in the emulator

Registers & Disassembly

Tool	Description
get_registers / get_register / set_register	Read/write CPU registers
disassemble	Disassemble instructions at address (branch targets auto-annotated with symbol names)
assemble	Assemble instruction text to machine code
get_callstack	Get current call stack (backtrace)

Memory

Tool	Description
read_memory / write_memory	Read/write raw memory bytes
read_string / read_std_string	Read C string or C++ std::string (with SSO detection)
read_pointer	Read pointer chain with symbol resolution
read_typed	Read memory as typed values (int8–int64, float, double, pointer)
search_memory	Search memory for byte patterns with scope/permission filters
list_memory_map	List all memory mappings with permissions
allocate_memory / free_memory / list_allocations	Allocate (malloc/mmap) with optional initial data, free, and track memory blocks
patch	Write assembled instructions to memory

Breakpoints & Execution

Tool	Description
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Add breakpoints by address, symbol, or module+offset
remove_breakpoint / list_breakpoints	Remove or list breakpoints (with disassembly)
continue_execution	Resume execution. Use poll_events to wait for breakpoint_hit or execution_completed
step_over / step_into / step_out	Step over, into (N instructions), or out of function
next_block	Break at next basic block (Unicorn only)
step_until_mnemonic	Break at next instruction matching mnemonic, e.g. bl, ret (Unicorn only)
poll_events	Poll for breakpoint_hit, execution_completed, trace events

Tracing

Tool	Description
trace_code	Trace instructions with register read/write values (regs_read, prev_write)
trace_read / trace_write	Trace memory reads/writes in address range

Function Calls

Tool	Description
call_function	Call native function by address with typed arguments (hex, string, bytes, null). Returns value with symbol resolution and memory preview
call_symbol	Call exported function by module + symbol name, e.g. libc.so + malloc

iOS Only (available when Family=iOS)

Tool	Description
inspect_objc_msg	Inspect objc_msgSend call: show receiver class name and selector, e.g. -[NSString length]
get_objc_class_name	Get ObjC class name of an object at a given address (pure memory parsing, no state change)
dump_objc_class	Dump ObjC class definition (properties, methods, protocols, ivars)
dump_gpb_protobuf	Dump GPB protobuf message schema as .proto format (64-bit only)

Custom MCP Tools

Use McpToolkit to register custom tools, each implementing the McpTool interface. This replaces manual if-else dispatch with clean, self-contained tool classes. By this point the native library is fully loaded (JNI_OnLoad / entry point already executed), so the code inside each tool's execute() is the target function logic to analyze. AI can set breakpoints and traces before triggering a custom tool, then inspect execution results across different inputs without restarting the process.

Android Example — See Utilities64.java for an Android JNI example with custom MCP tools:

DalvikModule dm = vm.loadLibrary(new File("libtmessages.29.so"), true);
dm.callJNI_OnLoad(emulator);
cUtilities = vm.resolveClass("org/telegram/messenger/Utilities");