unidbg
starsforks
How to install unidbg?
zhkl0228/unidbg
$git clone https://github.com/zhkl0228/unidbgAllows you to emulate an Android native library, and an experimental iOS emulation.
README.md
| 1 | # unidbg |
| 2 | |
| 3 | Allows you to emulate an Android native library, and an experimental iOS emulation. |
| 4 | |
| 5 | This is an educational project to learn more about the ELF/MachO file format and ARM assembly. |
| 6 | |
| 7 | Use it at your own risk ! |
| 8 | |
| 9 | ## Features |
| 10 | - Support [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) for AI-assisted debugging with Cursor and other AI tools. |
| 11 | - Emulation of the JNI Invocation API so JNI_OnLoad can be called. |
| 12 | - Support JavaVM, JNIEnv. |
| 13 | - Emulation of syscalls instruction. |
| 14 | - Support ARM32 and ARM64. |
| 15 | - Inline hook, thanks to [Dobby](https://github.com/jmpews/Dobby). |
| 16 | - Android import hook, thanks to [xHook](https://github.com/iqiyi/xHook). |
| 17 | - iOS [fishhook](https://github.com/facebook/fishhook) and substrate and [whale](https://github.com/asLody/whale) hook. |
| 18 | - [unicorn](https://github.com/zhkl0228/unicorn) backend support simple console debugger, gdb stub, instruction trace, memory read/write trace. |
| 19 | - Support iOS objc and swift runtime. |
| 20 | - Support [dynarmic](https://github.com/MerryMage/dynarmic) fast backend. |
| 21 | - Support Apple M1 hypervisor, the fastest ARM64 backend. |
| 22 | - Support Linux KVM backend with Raspberry Pi B4. |
| 23 | - Memory leak detection for emulated native code with guest backtrace and host stack trace. |
| 24 | |
| 25 | ## MCP Debugger (AI Integration) |
| 26 | |
| 27 | unidbg supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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. |
| 28 | |
| 29 | ### Quick Start |
| 30 | |
| 31 | unidbg MCP has two operating modes: |
| 32 | |
| 33 | **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. |
| 34 | |
| 35 | ```java |
| 36 | Debugger debugger = emulator.attach(); |
| 37 | debugger.addBreakPoint(address); |
| 38 | // run your emulation logic — debugger pauses when breakpoint is hit |
| 39 | ``` |
| 40 | |
| 41 | **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. |
| 42 | |
| 43 | ```java |
| 44 | McpToolkit toolkit = new McpToolkit(); |
| 45 | toolkit.addTool(new McpTool() { |
| 46 | @Override public String name() { return "encrypt"; } |
| 47 | @Override public String description() { return "Run encryption"; } |
| 48 | @Override public String[] paramNames() { return new String[]{"input"}; } |
| 49 | @Override public void execute(String[] params) { |
| 50 | String input = params.length > 0 ? params[0] : "default"; |
| 51 | // call encryption with input |
| 52 | } |
| 53 | }); |
| 54 | toolkit.run(emulator.attach()); |
| 55 | ``` |
| 56 | |
| 57 | When the debugger breaks, type `mcp` (or `mcp 9239` to specify port) in the console. Then add to Cursor MCP settings: |
| 58 | |
| 59 | ```json |
| 60 | { |
| 61 | "mcpServers": { |
| 62 | "unidbg-mcp-server": { |
| 63 | "url": "http://localhost:9239/sse" |
| 64 | } |
| 65 | } |
| 66 | } |
| 67 | ``` |
| 68 | |
| 69 | ### Available MCP Tools |
| 70 | |
| 71 | **Status & Info** |
| 72 | |
| 73 | | Tool | Description | |
| 74 | |------|-------------| |
| 75 | | `check_connection` | Emulator status: Family, architecture, backend capabilities, isRunning, loaded modules | |
| 76 | | `list_modules` / `get_module_info` | List loaded modules, get detail including exported symbol count and dependencies | |
| 77 | | `list_exports` | List exported/dynamic symbols of a module with optional filter and C++ demangling | |
| 78 | | `find_symbol` | Find symbol by name or find nearest symbol at address | |
| 79 | | `get_threads` | List all threads/tasks in the emulator | |
| 80 | |
| 81 | **Registers & Disassembly** |
| 82 | |
| 83 | | Tool | Description | |
| 84 | |------|-------------| |
| 85 | | `get_registers` / `get_register` / `set_register` | Read/write CPU registers | |
| 86 | | `disassemble` | Disassemble instructions at address (branch targets auto-annotated with symbol names) | |
| 87 | | `asse |
People who liked this also viewed
6 picksType
- langfuse-mcpA Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observabilityMCP ServersJun 2026
- tauri-plugin-mcpAllows AI agents (e.g., Cursor, Claude Code) to debug within Tauri apps via screenshot capture, window management, DOM access, and simulated user inputs.MCP ServersJul 2026
- perfetto-mcpThis is a Model Context Protocol (MCP) server that gets answers from your Perfetto Traces. It turns natural‑language prompts into focused Perfetto analyses.MCP ServersApr 2026
- jshookmcpjs hook toolkit that all you needMCP ServersJul 2026
- Cron Expression Parser — Explain & Next Run TimesCron expression parser API for AI agents. Parse, validate, and explain cron expressions in plain English. Get next N scheduled run times in any timezone. Tools: schedule_parse_cron. Use this for debugging cron schedules, building scheduliMCP Serversrecently
- trace-mcpMCP server for Claude Code and Codex. One tool call replaces ~42 minutes of agent explorationMCP ServersJul 2026
