zhkl0228/unidbg is one of the mobile-focused repositories TopGit tracks, currently at 5.3k stars, written primarily in Java. Allows you to emulate an Android native library, and an experimental iOS emulation
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
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:
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");
McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
@Override public String name() { return "aesCbc"; }
@Override public String description() { return "Run AES-CBC encryption on input data"; }
@Override public String[] paramNames() { return new String[]{"input"}; }
@Override public void execute(String[] params) {
byte[] input = params.length > 0 ? params[0].getBytes() : new byte[16];
aesCbcEncryptionByteArray(input);
}
});
toolkit.addTool(new McpTool() {
@Override public String name() { return "aesCtr"; }
@Override public String description() { return "Run AES-CTR decryption on input data"; }
@Override public String[] paramNames() { return new String[]{"input"}; }
@Override public void execute(String[] params) {
byte[] input = params.length > 0 ? params[0].getBytes() : new byte[16];
aesCtrDecryptionByteArray(input);
}
});
toolkit.addTool(new McpTool() {
@Override public String name() { return "pbkdf2"; }
@Override public String description() { return "Run PBKDF2 key derivation"; }
@Override public String[] paramNames() { return new String[]{"password", "iterations"}; }
@Override public void execute(String[] params) {
String password = params.length > 0 ? params[0] : "123456";
int iterations = params.length > 1 ? Integer.parseInt(params[1]) : 100000;
pbkdf2(password.getBytes(), iterations);
}
});
toolkit.run(emulator.attach());
iOS Example — See IpaLoaderTest.java for an iOS IPA loading example with custom MCP tools:
IpaLoader ipaLoader = new IpaLoader64(ipa, new File("target/rootfs/ipa"));
LoadedIpa loader = ipaLoader.load(this);
emulator = loader.getEmulator();
loader.callEntry();
module = loader.getExecutable();
McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
@Override public String name() { return "dumpClass"; }
@Override public String description() { return "Dump an ObjC class definition by name"; }
@Override public String[] paramNames() { return new String[]{"className"}; }
@Override public void execute(String[] params) {
String className = params.length > 0 ? params[0] : "AppDelegate";
IClassDumper classDumper = ClassDumper.getInstance(emulator);
System.out.println("dumpClass(" + className + "):\n" + classDumper.dumpClass(className));
}
});
toolkit.addTool(new McpTool() {
@Override public String name() { return "readVersion"; }
@Override public String description() { return "Read the TelegramCoreVersionString from the executable"; }
@Override public void execute(String[] params) {
Symbol sym = module.findSymbolByName("_TelegramCoreVersionString");
if (sym != null) {
Pointer pointer = UnidbgPointer.pointer(emulator, sym.getAddress());
if (pointer != null) {
System.out.println("_TelegramCoreVersionString=" + pointer.getString(0));
}
}
}
});
toolkit.run(emulator.attach());
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 Debugger.addMcpTool() + Debugger.run(DebugRunnable) directly for full control. McpToolkit 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 try-with-resources — tracking starts on creation, and the leak report is printed automatically on close.
A thread-safe object pool for reusing emulator instances across multiple threads, avoiding the overhead of repeated initialization.
Lazy initialization — Workers are created on-demand only when the pool is empty, not upfront.
Max limit — Total alive workers (borrowed + idle) never exceeds the configured maximum.
Idle cleanup — Workers idle for longer than the timeout (default 10 minutes) are automatically destroyed by the management thread.
Min idle — A minimum number of workers (default 1) is always kept alive, even when idle.
1. Implement a Worker
public class MyWorker implements Worker {
private final AndroidEmulator emulator;
public MyWorker() {
emulator = AndroidEmulatorBuilder.for64Bit().build();
// load .so, call JNI_OnLoad, etc.
}
@Override
public void destroy() {
emulator.close();
}
public byte[] doWork(byte[] input) {
// call native methods and return the result
}
}
2. Create Pool, Borrow, and Close
// Create a worker pool (max = CPU cores, lazy-initialized)
WorkerPool pool = WorkerPoolFactory.create(MyWorker::new);
// Or specify max workers explicitly
// WorkerPool pool = WorkerPoolFactory.create(MyWorker::new, 4);
// Optional: customize idle timeout (default 10 minutes, minimum 1 minute)
pool.setIdleTimeout(30); // idle workers destroyed after 30 minutes
// Optional: customize minimum kept-alive workers (default 1, minimum 1)
pool.setMinIdle(2); // always keep at least 2 workers alive
// Optional: pre-create workers eagerly (default 0, fully lazy)
pool.setInitialSize(4); // eagerly create 4 workers on startup
// Concurrent invocation from multiple threads
ExecutorService executor = Executors.newFixedThreadPool(100);
for (int i = 0; i < 100; i++) {
executor.submit(() -> {
try (WorkerLoan<MyWorker> loan = pool.borrow(1, TimeUnit.MINUTES)) {
if (loan != null) {
byte[] result = loan.get().doWork(input);
}
} // worker is automatically returned to the pool
});
}
executor.shutdown();
executor.awaitTermination(10, TimeUnit.MINUTES);
pool.close(); // destroy all workers and release resources
See TTEncryptWorker.java for a complete example.
Examples
Simple tests under src/test directory:
TTEncrypt.java
JniDispatch32.java
JniDispatch64.java
Utilities32.java
Utilities64.java
More tests:
QDReaderJni.java
SignUtil.java
License
unidbg uses software libraries from Apache Software Foundation.
No homepage URL was recorded for zhkl0228/unidbg in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
How active is development on zhkl0228/unidbg?
The most recent commit recorded on zhkl0228/unidbg was 3 months ago, based on the GitHub push timestamp. The repository has 1.2k forks — one of the better signals of community interest.
How many stars does zhkl0228/unidbg have?
zhkl0228/unidbg has 5.3k GitHub stars — refresh the page for the live number, or check github.com/zhkl0228/unidbg. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is zhkl0228/unidbg open source?
Yes — zhkl0228/unidbg ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/zhkl0228/unidbg.
What else is in the Mobile space?
zhkl0228/unidbg is tracked by TopGit under the Mobile category, alongside 16 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/zhkl0228/unidbg is the definitive source.
Read full README in the tab above.
Is unidbg worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of unidbg.