zhkl0228 / unidbg

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 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, pauses the emulator — type 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. **Mode 2: Custom Tools (Repeatable)** — Use 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. When the debugger breaks, type (or to specify port) in the console. Then add to Cursor MCP settings: Available MCP Tools **Status & Info** | Tool | Description | |------|-------------| | | Emulator status: Family, architecture, backend capabilities, isRunning, loaded modules | | / | List loaded modules, get detail including exported symbol count and dependencies | | | List exported/dynamic symbols of a module with optional filter and C++ demangling | | | Find symbol by name or find nearest symbol at address | | | List all threads/tasks in the emulator | **Registers & Disassembly** | Tool | Description | |------|-------------| | / / | Read/write CPU registers | | | Disassemble instructions at address (branch targets auto-annotated with symbol names) | | | Assemble instruction text to machine code | | | Get current call stack (backtrace) | **Memory** | Tool | Description | |------|-------------| | / | Read/write raw memory bytes | | / | Read C string or C++ std::string (with SSO detection) | | | Read pointer chain with symbol resolution | | | Read memory as typed values (int8–int64, float, double, pointer) | | | Search memory for byte patterns with scope/permission filters | | | List all memory mappings with permissions | | / / | Allocate (malloc/mmap) with optional initial data, free, and track memory blocks | | | Write assembled instructions to memory | **Breakpoints & Execution** | Tool | Description | |------|-------------| | / / | Add breakpoints by address, symbol, or module+offset | | / | Remove or list breakpoints (with disassembly) | | | Resume execution. Use poll_events to wait for breakpoint_hit or execution_completed | | / / | Step over, into (N instructions), or out of function | | | Break at next basic block (Unicorn only) | | | Break at next instruction matching mnemonic, e.g. , (Unicorn only) | | | Poll for breakpoint_hit, execution_completed, trace events | **Tracing** | Tool | Description | |------|-------------| | | Trace instructions with register read/write values (regs_read, prev_write) | | / | Trace memory reads/writes in address range | **Function Calls** | Tool | Description | |------|-------------| | | Call native function by address with typed arguments (hex, string, bytes, null). Returns value with symbol resolution and memory preview | | | Call exported function by module + symbol name, e.g. + | **iOS Only** (available when Family=iOS) | Tool | Description | |------|-------------| | | Inspect objc_msgSend call: show receiver class name and selector, e.g. | | | Get ObjC class name of an object at a given address (pure memory parsing, no state change) | | | Dump ObjC class definition (properties, methods, protocols, ivars) | | | Dump GPB protobuf message schema as .proto format (64-bit only) | Custom MCP Tools Use to register custom tools, each implementing the 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 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: **iOS Example** — See IpaLoaderTest.java for an iOS IPA loading example with custom MCP tools: Once the MCP server is started, AI can call these tools via MCP to run emulations with custom parameters, set breakpoints, trace execution, and inspect results — all without restarting the process. > **Low-level API**: You can also use + directly for full control. is a higher-level wrapper that eliminates if-else dispatch. Memory Leak Detection Track guest-side memory allocations (mmap/munmap/brk) to detect leaks in emulated native code. Use — tracking starts on creation, and the leak report is printed automatically on close. Each leaked block includes guest ARM backtrace (module+offset+sy…