Unidbg

https://github.com/zhkl0228/unidbg
Admin
Unidbg is an educational project that allows you to emulate Android native libraries and provides...
Tokens:991,171
Snippets:5,238
Trust Score:9.1
License:Apache-2.0
Update:23 hours ago
Show doc for...
Tokens:
Raw
### UnidbgPointer usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/pointer.md

Shows how to create a pointer, set and get an int, write a byte array, and read a NUL-terminated string from guest memory.

```java
UnidbgPointer ptr = UnidbgPointer.pointer(emulator, 0x40001000L);
ptr.setInt(0, 0x1234);
int value = ptr.getInt(0);
ptr.write(4, new byte[]{1, 2, 3, 4});
String name = UnidbgPointer.pointer(emulator, symbolAddr).getString(0);
```

--------------------------------

### McpServer usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Shows how to create an McpServer instance, add a custom tool, start the server, and stop it in a finally block. The server listens on http://localhost:9239/sse for AI connections.

```java
McpServer server = new McpServer(emulator, 9239);
server.addCustomTool("myTool", "Runs my tool", "param1", "param2");
try {
    server.start();
    // keep process alive while AI connects to http://localhost:9239/sse
} finally {
    server.stop();
}
```

--------------------------------

### start()

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Starts the HTTP server, replaces System.in with a merged input stream, and adds SSE and message endpoints.

```APIDOC
## start()

### Description
Starts the MCP HTTP server. It creates the HTTP server, replaces `System.in` with a `MergedInputStream` of the original stdin plus a command pipe, adds `/sse` and `/message` contexts, and starts a daemon executor named `mcp-server`.

### Method
void start() throws IOException

### Exceptions
- **IOException** - If the server fails to start.

### Usage Example
```java
server.start();
```
```

--------------------------------

### ARMEmulator Usage Example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/emulator.md

Example demonstrating how to create an Android emulator, load a library, set a timeout, trace code, call a function, and close the emulator.

```APIDOC
## ARMEmulator Usage Example

### Description
Example demonstrating how to create an Android emulator, load a library, set a timeout, trace code, call a function, and close the emulator.

### Code
```java
AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit()
        .setProcessName("com.example.app")
        .addBackendFactory(new Unicorn2Factory(true))
        .build();

Memory memory = emulator.getMemory();
Module lib = emulator.loadLibrary(new File("libnative.so"), true);
emulator.setTimeout(0); // unlimited

// trace instructions in the module range
TraceHook trace = emulator.traceCode(lib.base, lib.base + lib.size);
Number ret = lib.callFunction(emulator, "nativeHash", 42L, 0x1000L);
trace.stopTrace();
System.out.println("result=" + ret.intValue());

emulator.close();
```
```

--------------------------------

### Usage Example: Loading and Calling a Symbol

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/module.md

Demonstrates how to load a library, call JNI_OnLoad, get the module, find a symbol, and invoke it.

```APIDOC
## Usage Example: Loading and Calling a Symbol

### Description
Shows the typical workflow of loading a native library, initializing it, and calling a specific exported function.

### Code Example
```java
DalvikModule dm = vm.loadLibrary("tmessages", true); // libtmessages.so, force init
dm.callJNI_OnLoad(emulator);

Module module = dm.getModule();
Symbol symbol = module.findSymbolByName("Java_org_telegram_messenger_Utilities_aesCbcEncryptionByteArray");
Number ret = symbol.call(emulator, arg1, arg2); // or module.callFunction(emulator, 0x1234, arg1)
```
```

--------------------------------

### IxHook usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/android-emulator.md

Shows how to get an IxHook instance, register a replacement for 'connect' on libtarget.so, and apply with refresh(). The callback overrides the fd argument and returns success.

```java
IxHook xHook = IxHook.getInstance(emulator);
xHook.register("libtarget\\.so$", "connect", new ReplaceCallback() {
    @Override
    public HookStatus onCall(Emulator<?> emulator, HookContext context, long originFunction) {
        context.push(0); // override 'connect' arg 0 (fd)
        return HookStatus.LR(emulator, 0); // pretend success
    }
});
xHook.refresh();
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Example JSON configuration for connecting an MCP client to the unidbg MCP server.

```APIDOC
## MCP Client Configuration

### Description
Example configuration for setting up an MCP client to connect to the unidbg MCP server.

### Configuration
```json
{
  "mcpServers": {
    "unidbg-mcp-server": {
      "url": "http://localhost:9239/sse"
    }
  }
}
```
```

--------------------------------

### Usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/workers.md

Example of creating and using a worker pool with an emulator worker.

```APIDOC
## Usage example

### Description
Demonstrates creating a worker pool with a factory that creates emulator workers, borrowing a worker, and releasing it.

### Code
```java
// Typical worker = one emulator instance
WorkerPool pool = WorkerPoolFactory.create(() -> {
    AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit().build();
    return (Worker) () -> {           // Worker.destroy() releases the emulator
        try {
            emulator.close();
        } catch (IOException ignored) {
        }
    };
}, 4); // max 4 workers

try (WorkerLoan<EmulatorWorker> loan = pool.borrow(1, TimeUnit.MINUTES)) {
    if (loan != null) {
        EmulatorWorker worker = loan.get(); // typed via generic borrow
        worker.doWork();
    } else {
        System.err.println("no worker available within 1 minute");
    }
} // loan.close() returns the worker to the pool
pool.close(); // destroys all workers
```
```

--------------------------------

### Usage example for DalvikModule

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/module.md

Demonstrates loading a library with force init, calling JNI_OnLoad, and invoking a symbol by name.

```java
DalvikModule dm = vm.loadLibrary("tmessages", true); // libtmessages.so, force init
dm.callJNI_OnLoad(emulator);

Module module = dm.getModule();
Symbol symbol = module.findSymbolByName("Java_org_telegram_messenger_Utilities_aesCbcEncryptionByteArray");
Number ret = symbol.call(emulator, arg1, arg2); // or module.callFunction(emulator, 0x1234, arg1)
```

--------------------------------

### Kernel Setup Commands for Raspberry Pi 4B

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/kvm/README.md

Commands to install dependencies, clone the kernel repository, checkout the rpi-5.4.y branch, configure, build, install modules and device tree blobs, and reboot. Requires CentOS-7-aarch64 on Raspberry Pi 4B.

```bash
yum install -y make gcc gcc-c++ flex bison openssl-devel java-1.8.0-openjdk-devel maven git
git clone https://github.com/zhkl0228/linux
cd linux && git checkout rpi-5.4.y
make bcm2711_defconfig
make -j4
make Image modules dtbs
make modules_install
cp arch/arm64/boot/dts/broadcom/bcm2711-rpi-4-b.dtb /boot/
cp -f arch/arm64/boot/dts/overlays/*.dtb* /boot/overlays/
cp arch/arm64/boot/Image /boot/kernel8.img
reboot
```

--------------------------------

### IPA loading usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/ios-emulator.md

Shows how to load an IPA using IpaLoader64, retrieve the emulator and executable, and call the entry point.

```java
IpaLoader ipaLoader = new IpaLoader64(ipa, new File("target/rootfs/ipa"));
LoadedIpa loader = ipaLoader.load(this);
emulator = loader.getEmulator();
loader.callEntry();
module = loader.getExecutable();
```

--------------------------------

### iOS: Register custom MCP tools with McpToolkit

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

iOS example showing how to load an IPA, get the emulator and executable, and register custom MCP tools (dumpClass, readVersion) using McpToolkit. The dumpClass tool uses ClassDumper to dump an ObjC class, and readVersion reads a symbol from the executable. The toolkit is run with emulator.attach().

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

--------------------------------

### VirtualModule usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/module.md

Creates a VirtualModule named "libvirtual.so", allocates a stub pointer in onInitialize, and registers it with the memory.

```java
VirtualModule<Object> vm = new VirtualModule<Object>(emulator, "libvirtual.so") {
    @Override
    protected void onInitialize(Emulator<?> emulator, Object extra, Map<String, UnidbgPointer> symbols) {
        UnidbgPointer stub = emulator.getSvcMemory().allocate(16, "virtual.stub");
        symbols.put("virtualFunc", stub);
    }
};
Module module = vm.register(emulator.getMemory());
```

--------------------------------

### HookZz.replace Example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/hooks.md

Example showing how to replace a function using HookZz with a ReplaceCallback.

```APIDOC
## HookZz.replace Example

### Description
Example showing how to replace a function using HookZz with a ReplaceCallback.

### Code
```java
HookZz hookZz = HookZz.getInstance(emulator);
hookZz.replace(module.base + 0x1234, new ReplaceCallback() {
    @Override
    public HookStatus onCall(Emulator<?> emulator, HookContext context, long originFunction) {
        context.push(emulator.getContext().getPointerArg(1)); // save arg1
        return HookStatus.LR(emulator, 0);                     // return 0 immediately
    }
    @Override
    public void postCall(Emulator<?> emulator, HookContext context) {
        // only when enablePostCall=true
    }
}, true); // enablePostCall
```

```

--------------------------------

### AndroidEmulator usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/emulator.md

Shows how to build a 64-bit Android emulator, load a native library, set an unlimited timeout, trace code in the module range, call a function, and close the emulator. The trace is stopped after the call and the result is printed.

```java
AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit()
        .setProcessName("com.example.app")
        .addBackendFactory(new Unicorn2Factory(true))
        .build();

Memory memory = emulator.getMemory();
Module lib = emulator.loadLibrary(new File("libnative.so"), true);
emulator.setTimeout(0); // unlimited

// trace instructions in the module range
TraceHook trace = emulator.traceCode(lib.base, lib.base + lib.size);
Number ret = lib.callFunction(emulator, "nativeHash", 42L, 0x1000L);
trace.stopTrace();
System.out.println("result=" + ret.intValue());

emulator.close();
```

--------------------------------

### McpToolkit usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Shows how to create a McpToolkit, add a custom tool named "encrypt", and run it with the debugger attached to an emulator. The tool's execute method reads the first parameter as input bytes, defaulting to a 16-byte array if none provided.

```java
McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
    @Override public String name() { return "encrypt"; }
    @Override public String description() { return "Run encryption with the loaded library"; }
    @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];
        encrypt(input);
    }
});
toolkit.run(emulator.attach());
```

--------------------------------

### Substrate.getInstance

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the Substrate singleton instance. iOS hook library, cached per emulator.

```APIDOC
## Substrate.getInstance

### Description
Gets the Substrate singleton instance. iOS hook library, cached per emulator.

### Method
getInstance

### Parameters
None

### Response
Returns the Substrate singleton instance.
```

--------------------------------

### Build emulator with backend factories

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/backend.md

Shows how to configure an AndroidEmulator with preferred backend factories using addBackendFactory. The example prefers DynarmicFactory, then Unicorn2Factory, and finally falls back to the built-in UnicornBackend. It then retrieves the backend and prints page size and resident memory size.

```java
AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit()
        .addBackendFactory(new DynarmicFactory(true))     // prefer dynarmic, fall back on failure
        .addBackendFactory(new Unicorn2Factory(true))     // then unicorn2
        .build();                                          // then built-in UnicornBackend
Backend backend = emulator.getBackend();
System.out.println("page=" + backend.getPageSize() + " resident=" + backend.getMemResidentSize());
```

--------------------------------

### ProxyClassFactory usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/dvm.md

Shows how to configure ProxyClassFactory with a class name mapper and object visitor, mapping a specific class to a proxy class and visiting proxied objects.

```java
vm.setDvmClassFactory(new ProxyClassFactory()
        .configClassNameMapper(className ->
                "org/telegram/messenger/Utilities".equals(className)
                        ? MyProxyClass.class.getName() : className)
        .configObjectVisitor((obj, arg) -> { /* visit proxied object */ }));
```

--------------------------------

### Custom MMapListener Usage

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/memory.md

Example of using a custom MMapListener with error handling, saving and restoring the previous listener.

```APIDOC
## Custom MMapListener Usage

### Description
Example of using a custom MMapListener with error handling, saving and restoring the previous listener.

### Usage Example
```java
Memory memory = emulator.getMemory();
MMapListener previous = memory.getMMapListener(); // save
memory.setMMapListener(new MMapListener() {
    @Override public void onMap(long address, long size, int perms) { /* ... */ }
    @Override public int onProtect(long address, long size, int perms) { return perms; }
    @Override public void onUnmap(long address, long size) { /* ... */ }
});
try {
    // emulation
} finally {
    memory.setMMapListener(previous); // restore
}
```
```

--------------------------------

### AndroidResolver usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/android-emulator.md

Shows how to create an Android emulator and set the AndroidResolver with SDK 23 and specific libraries. The comment notes that this forces 'use libc.so' logging for emulated __android_log_print and similar functions.

```java
AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit().build();
emulator.getMemory().setLibraryResolver(new AndroidResolver(23, "libc.so", "libm.so", "libdl.so"));
// forces "use libc.so" logging for emulated __android_log_print etc.
```

--------------------------------

### Usage with custom MMapListener (error handling)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/memory.md

Shows how to save the current MMapListener, install a custom one, and restore it in a finally block to ensure proper cleanup even if an error occurs.

```java
Memory memory = emulator.getMemory();
MMapListener previous = memory.getMMapListener(); // save
memory.setMMapListener(new MMapListener() {
    @Override public void onMap(long address, long size, int perms) { /* ... */ }
    @Override public int onProtect(long address, long size, int perms) { return perms; }
    @Override public void onUnmap(long address, long size) { /* ... */ }
});
try {
    // emulation
} finally {
    memory.setMMapListener(previous); // restore
}
```

--------------------------------

### Console debugger usage example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/debugger.md

Shows how to attach a console debugger, load a library, add a temporary breakpoint on JNI_OnLoad, trace function calls, and run the emulator until breakpoint or completion.

```java
Debugger debugger = emulator.attach(DebuggerType.CONSOLE);
Module lib = emulator.loadLibrary(new File("libtarget.so"), true);

BreakPoint bp = debugger.addBreakPoint(lib, "JNI_OnLoad", (emu, address) -> {
    System.out.println("JNI_OnLoad hit at 0x" + Long.toHexString(address));
    return false; // stop
});
bp.setTemporary(true); // auto-remove after first hit

debugger.traceFunctionCall(new FunctionCallListener() {
    @Override public void onCall(Emulator<?> emulator, long callerAddress, long functionAddress) {
        System.out.printf("call 0x%x -> 0x%x%n", callerAddress, functionAddress);
    }
    @Override public void postCall(Emulator<?> emulator, long callerAddress, long functionAddress, Number[] args) {
        System.out.printf("ret  from 0x%x%n", functionAddress);
    }
});

// run until breakpoint or completion
debugger.run(emulator::emulate); // DebugRunnable<Void>
```

--------------------------------

### HookZz.getInstance(emulator)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the HookZz singleton instance for the given emulator. Loads bundled libhookzz and caches it in emulator set/get.

```APIDOC
## HookZz.getInstance(emulator)

### Description
Gets the HookZz singleton instance for the given emulator. Loads bundled libhookzz and caches it in emulator set/get.

### Method
getInstance

### Parameters
#### Parameters
- **emulator** (Emulator) - Required - The emulator instance

### Response
Returns the HookZz singleton instance.
```

--------------------------------

### Android: Register custom MCP tools with McpToolkit

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

Android example showing how to load a native library, resolve a class, and register custom MCP tools (aesCbc, aesCtr, pbkdf2) using McpToolkit. Each tool implements McpTool and its execute() method contains the target function logic. The toolkit is run with emulator.attach().

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

--------------------------------

### IxHook.getInstance(emulator)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the IxHook singleton instance for the given emulator. Loads libxhook (Android only).

```APIDOC
## IxHook.getInstance(emulator)

### Description
Gets the IxHook singleton instance for the given emulator. Loads libxhook (Android only).

### Method
getInstance

### Parameters
#### Parameters
- **emulator** (Emulator) - Required - The emulator instance

### Response
Returns the IxHook singleton instance.
```

--------------------------------

### Configure DarwinResolver with DarwinEmulatorBuilder

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/ios-emulator.md

Builds a 64-bit Darwin emulator with a Dynarmic backend, sets the library resolver to DarwinResolver, and enables the Objective-C runtime on the MachOLoader. This setup is required before using iOS framework/dylib resources.

```java
ARMEmulator<DarwinFileIO> emulator = DarwinEmulatorBuilder.for64Bit()
        .addBackendFactory(new DynarmicFactory(true))
        .build();
emulator.getMemory().setLibraryResolver(new DarwinResolver());
MachOLoader loader = (MachOLoader) emulator.getMemory();
loader.setObjcRuntime(true);
```

--------------------------------

### UnidbgPointer error handling example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/pointer.md

Demonstrates catching InvalidMemoryAccessException when reading a byte array from an unmapped guest address, printing the address and attaching a debugger.

```java
try {
    UnidbgPointer ptr = UnidbgPointer.pointer(emulator, address);
    byte[] data = ptr.getByteArray(0, 0x100); // may throw InvalidMemoryAccessException
    System.out.println(Hex.encodeHexString(data));
} catch (InvalidMemoryAccessException e) {
    System.err.println("unmapped guest address 0x" + Long.toHexString(address));
    emulator.attach().debug("invalid memory access");
}
```

--------------------------------

### Usage example with MemoryTracker

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/memory.md

Shows how to use MemoryTracker via try-with-resources to detect memory leaks during a function call. The close() method prints the full leak report to stdout.

```java
try (MemoryTracker tracker = emulator.traceMemoryLeaks()) {
    module.callFunction(emulator, "targetFunction", arg1, arg2);
    System.out.println("leaked=" + tracker.getTotalLeakedSize() + " bytes");
    for (AllocationRecord record : tracker.getLeaks()) {
        System.out.printf("0x%x size=%d%n", record.address, record.size);
        for (String frame : record.guestBacktrace) {
            System.out.println("  " + frame);
        }
    }
} // close() also prints the full formatted leak report to stdout
```

--------------------------------

### Sample Memory Leak Report output

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

Example output of the memory leak report, showing tracking duration, allocation counts, leaked blocks, and per-leak details with guest ARM backtrace and host Java stack trace.

```text
=== Memory Leak Report ===
Tracking duration: 42ms
Total allocations: 5
Total deallocations: 3
Leaked blocks: 2
Total leaked size: 32768 bytes (32.0 KB)

--- Leak #1 ---
Address: 0x40001000, Size: 16384 (16.0 KB), Perms: rw-
Guest Backtrace:
  #0 0x40123456 libexample.so+0x3456 (malloc+0x12)
  #1 0x40124000 libexample.so+0x4000 (doSomething+0x48)
Host Stack Trace:
  com.github.unidbg.linux.AndroidElfLoader.mmap2(AndroidElfLoader.java:785)
  ...
```

--------------------------------

### Build hypervisor dylib with build.sh

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/hypervisor/README.md

Builds the native hypervisor library. Run from the backend/hypervisor/src/main/native/hypervisor directory. Artifacts are placed in src/main/resources/natives/osx_arm64/.

```bash
cd backend/hypervisor/src/main/native/hypervisor
./build.sh
```

--------------------------------

### Build all platforms with build.sh

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/unicorn2/README.md

Navigate to the native build directory and run build.sh with the 'all' argument to build for all platforms.

```bash
cd backend/unicorn2/src/main/native

# Build all platforms
./build.sh all
```

--------------------------------

### GET /sse

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/endpoints.md

Establishes a Server-Sent Events stream. Each GET creates a new session with a UUID sessionId. The stream sends an 'endpoint' event with the message URL, followed by JSON-RPC responses and notifications.

```APIDOC
## GET /sse

### Description
Establishes a Server-Sent Events (SSE) stream. Each GET creates a new session with a UUID sessionId. The stream sends an 'endpoint' event with the message URL, followed by JSON-RPC responses and notifications.

### Method
GET

### Endpoint
/sse

### Response
#### Success Response (200)
- **Content-Type**: text/event-stream
- **Cache-Control**: no-cache
- **Connection**: keep-alive
- **Access-Control-Allow-Origin**: *

#### Response Example
```
event: endpoint
data: "http://localhost:<port>/message?sessionId=<sessionId>"

```

### Error Handling
- **405**: Non-GET methods (except OPTIONS) are not allowed.
- **204**: OPTIONS preflight request.

```

--------------------------------

### HookZz replace function example

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/hooks.md

Usage example for replacing a function with HookZz. The onCall method saves arg1 and returns 0 immediately; postCall is only called when enablePostCall is true. The third argument to replace enables postCall.

```java
HookZz hookZz = HookZz.getInstance(emulator);
hookZz.replace(module.base + 0x1234, new ReplaceCallback() {
    @Override
    public HookStatus onCall(Emulator<?> emulator, HookContext context, long originFunction) {
        context.push(emulator.getContext().getPointerArg(1)); // save arg1
        return HookStatus.LR(emulator, 0);                     // return 0 immediately
    }
    @Override
    public void postCall(Emulator<?> emulator, HookContext context) {
        // only when enablePostCall=true
    }
}, true); // enablePostCall
```

--------------------------------

### initialize

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/endpoints.md

Initializes the MCP server connection and returns server information, capabilities, protocol version, and instructions.

```APIDOC
## initialize

### Description
Initializes the MCP server connection and returns server information, capabilities, protocol version, and instructions.

### Method
JSON-RPC

### Parameters
None.

### Result
| Field | Type | Value |
|-------|------|-------|
| `serverInfo.name` | string | `"unidbg-mcp"` |
| `serverInfo.version` | string | `"1.0.0"` |
| `capabilities.tools.listChanged` | boolean | `false` |
| `capabilities.logging` | object | `{}` |
| `protocolVersion` | string | `"2024-11-05"` |
| `instructions` | string | Free-text instructions (state, modes, arg format, backend capabilities, tips) |
```

--------------------------------

### ClassDumper.getInstance

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the ClassDumper singleton instance.

```APIDOC
## ClassDumper.getInstance

### Description
Gets the ClassDumper singleton instance.

### Method
getInstance

### Parameters
None

### Response
Returns the ClassDumper singleton instance.
```

--------------------------------

### get_callstack

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

Get the current call stack (backtrace).

```APIDOC
## get_callstack

### Description
Get the current call stack (backtrace).

### Method
MCP Tool

### Endpoint
get_callstack

### Parameters
None

### Response
#### Success Response
- **callstack** (array) - List of stack frames with addresses and symbols
```

--------------------------------

### Clean build with build.sh

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/unicorn2/README.md

Perform a clean build from scratch by passing the --clean flag, e.g., for macOS.

```bash
# Clean build (rebuild from scratch)
./build.sh --clean osx
```

--------------------------------

### FishHook.getInstance

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the FishHook singleton instance. iOS hook library, cached per emulator.

```APIDOC
## FishHook.getInstance

### Description
Gets the FishHook singleton instance. iOS hook library, cached per emulator.

### Method
getInstance

### Parameters
None

### Response
Returns the FishHook singleton instance.
```

--------------------------------

### Whale.getInstance

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Gets the Whale singleton instance. iOS hook library, cached per emulator.

```APIDOC
## Whale.getInstance

### Description
Gets the Whale singleton instance. iOS hook library, cached per emulator.

### Method
getInstance

### Parameters
None

### Response
Returns the Whale singleton instance.
```

--------------------------------

### FileSystem interface definition

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/file-io.md

Defines the guest filesystem abstraction with methods for opening, creating, and managing files. Includes constants for default root directory and work directory.

```java
public interface FileSystem<T extends NewFileIO> {
    String DEFAULT_ROOT_FS = "rootfs/default";
    String DEFAULT_WORK_DIR = "unidbg_work";

    File getRootDir();
    File createWorkDir();                // rootDir/unidbg_work (only when rootDir set)
    FileResult<T> open(String pathname, int oflags);
    void unlink(String path);
    boolean mkdir(String path, int mode); // true = created
    void rmdir(String path);
    T createSimpleFileIO(File file, int oflags, String path);
    T createDirectoryFileIO(File file, int oflags, String path);
    int rename(String oldPath, String newPath);
}
```

--------------------------------

### get_objc_class_name

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

Get ObjC class name of an object at a given address (pure memory parsing, no state change).

```APIDOC
## get_objc_class_name

### Description
Get ObjC class name of an object at a given address (pure memory parsing, no state change).

### Method
MCP Tool

### Endpoint
get_objc_class_name

### Parameters
- **address** (integer) - Required - Address of the object

### Response
#### Success Response
- **class_name** (string) - ObjC class name
```

--------------------------------

### Registers & Disassembly Tools

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Tools for reading and writing registers, disassembling and assembling instructions, and getting the call stack.

```APIDOC
## Registers & Disassembly Tools

### get_registers
- **Params**: None
- **Description**: Retrieves all register values.

### get_register
- **Params**: `name` (e.g. `X0`, `R0`, `SP`, `PC`, `LR`)
- **Description**: Retrieves the value of a specific register.

### set_register
- **Params**: `name` (e.g. `X0`, `R0`, `SP`, `PC`, `LR`), `value` (hex)
- **Description**: Sets the value of a specific register.

### disassemble
- **Params**: `address`, `count` (default 10)
- **Description**: Disassembles instructions at the given address.

### assemble
- **Params**: `assembly`, `address` (default 0)
- **Description**: Assembles an instruction at the given address.

### get_callstack
- **Params**: None
- **Description**: Retrieves the current call stack.
```

--------------------------------

### ModulePatcher

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/syscalls-loading.md

Abstract class for post-load binary patching hooks. Concrete subclasses install byte patches before relocation.

```APIDOC
## ModulePatcher

### Description
Abstract class for post-load binary patching hooks. Concrete subclasses install byte patches before relocation.

### Class
`public abstract class ModulePatcher`

### Usage
Subclass and implement to install byte patches before relocation.

```

--------------------------------

### Catching InvalidMemoryAccessException

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/errors.md

Example of catching InvalidMemoryAccessException when reading memory at a potentially bad address, printing an error and attaching a debugger.

```java
try {
    byte[] data = UnidbgPointer.pointer(emulator, address).getByteArray(0, 64);
} catch (InvalidMemoryAccessException e) {
    System.err.println("bad address 0x" + Long.toHexString(address));
    emulator.attach().debug("invalid memory access at 0x" + Long.toHexString(address));
}
```

--------------------------------

### AndroidEmulatorBuilder.build()

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/android-emulator.md

Builds the Android emulator. Returns AndroidARM64Emulator for 64-bit and AndroidARMEmulator for 32-bit, passing processName, rootDir, and backendFactories to the constructor.

```APIDOC
## build()

### Description
Builds the Android emulator. Returns AndroidARM64Emulator for 64-bit and AndroidARMEmulator for 32-bit, passing processName, rootDir, and backendFactories to the constructor.

### Method
build

### Signature
@Override public AndroidEmulator build()

### Parameters
None

### Returns
AndroidEmulator - an AndroidARM64Emulator for 64-bit or AndroidARMEmulator for 32-bit
```

--------------------------------

### Hook a Binding

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/syscalls-loading.md

Example of adding a hook listener to intercept symbol bindings, such as malloc, and register a service to handle the call.

```APIDOC
## Hook a Binding

### Description
Add a hook listener to intercept symbol bindings. If the symbol matches, register a service and return its peer; otherwise return 0 for no hook.

### Usage Example
```java
emulator.getMemory().addHookListener((svcMemory, libraryName, symbolName, old) -> {
    if ("malloc".equals(symbolName)) {
        return svcMemory.registerSvc(new Arm64Svc() {
            @Override public long handle(Emulator<?> emulator) {
                System.out.println("malloc called");
                return 0; // stub
            }
        }).peer;
    }
    return 0; // no hook
});
```

```

--------------------------------

### Custom Library Resolver

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/syscalls-loading.md

Example of setting a custom library resolver to load Android ELF libraries from a vendor directory.

```APIDOC
## Custom Library Resolver

### Description
Set a custom library resolver to handle library loading. If the library file exists in the vendor directory, return an ElfLibraryFile; otherwise return null to indicate load failure.

### Usage Example
```java
emulator.getMemory().setLibraryResolver((emu, libraryName) -> {
    File file = new File("vendor/lib/" + libraryName);
    if (file.isFile()) {
        return new ElfLibraryFile(file, emu.is64Bit());   // Android ELF
    }
    return null; // unhandled -> load failure
});
```

```

--------------------------------

### AndroidEmulator.createDalvikVM(File apkFile)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/android-emulator.md

Creates a Dalvik VM using the provided APK file. The APK provides package name, version, assets, manifest, and embedded .so files. The apkFile may be null.

```APIDOC
## createDalvikVM(File apkFile)

### Description
Creates a Dalvik VM using the provided APK file. The APK provides package name, version, assets, manifest, and embedded .so files. The apkFile may be null.

### Method
createDalvikVM

### Signature
VM createDalvikVM(File apkFile)

### Parameters
- **apkFile** (File) - Optional - The APK file to use. May be null.

### Returns
VM - the created Dalvik VM

### Exceptions
IllegalStateException - if a VM has already been created
```

--------------------------------

### EmulatorBuilder options

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Options for configuring an emulator builder, including process name, root directory, and backend factories.

```APIDOC
## EmulatorBuilder options

### Description
Options for configuring an emulator builder, including process name, root directory, and backend factories.

### Options
- **is64Bit** (boolean) - Required - Set via `for32Bit()` / `for64Bit()` static factories
- **processName** (String) - Optional - Default: `null` → `"unidbg"` - Process name exposed to the guest (`getProcessName`, argv[0])
- **rootDir** (File) - Optional - Default: `new File(target, "rootfs/default")` (or temp dir if `target/` missing) - Guest filesystem root
- **backendFactories** (List<BackendFactory>) - Optional - Default: empty (default `UnicornBackend` fallback) - Ordered backend factory chain; first success wins

### Methods
- `setProcessName(String)` - Returns the builder (chainable)
- `setRootDir(File)` - Returns the builder (chainable)
- `addBackendFactory(BackendFactory)` - Returns the builder (chainable)
- `build()` - Abstract method
```

--------------------------------

### DarwinEmulatorBuilder.addEnv

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/configuration.md

Adds guest environment variables, including IpaLoader defaults.

```APIDOC
## DarwinEmulatorBuilder.addEnv

### Description
Adds guest environment variables, including IpaLoader defaults.

### Method
addEnv

### Parameters
#### Parameters
- **env** (Map) - Required - Environment variables to add

### Response
Returns the builder instance.
```

--------------------------------

### IpaLoader.load(String...)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/ios-emulator.md

Loads an IPA file and returns a LoadedIpa instance. This is the primary entry point for loading an IPA.

```APIDOC
## IpaLoader.load(String...)

### Description
Loads an IPA file and returns a LoadedIpa instance. This is the primary entry point for loading an IPA.

### Method
load

### Signature
public final LoadedIpa load(String... loads);

### Parameters
- **loads** (String...) - Required - Paths to the IPA file or additional resources.

### Returns
- **LoadedIpa** - The loaded IPA result.

### Example
```java
IpaLoader ipaLoader = new IpaLoader64(ipa, new File("target/rootfs/ipa"));
LoadedIpa loader = ipaLoader.load(this);
```
```

--------------------------------

### list_modules / get_module_info

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

List loaded modules and get detailed information about a specific module, including exported symbol count and dependencies.

```APIDOC
## list_modules / get_module_info

### Description
List loaded modules and get detailed information about a specific module, including exported symbol count and dependencies.

### Method
MCP Tool

### Endpoint
list_modules / get_module_info

### Parameters
#### For get_module_info
- **module_name** (string) - Required - Name of the module to query

### Response
#### Success Response
- **modules** (array) - List of loaded modules (for list_modules)
- **module_info** (object) - Detailed module info including exported symbol count and dependencies (for get_module_info)
```

--------------------------------

### WorkerLoan class methods

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/workers.md

WorkerLoan is an AutoCloseable that holds a borrowed worker. get() returns the borrowed worker, and close() releases it back to the pool.

```java
public T get();       // the borrowed worker
@Override public void close();  // pool.release(worker)
```

--------------------------------

### CMake configuration for libhypervisor.dylib

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/hypervisor/src/main/native/hypervisor/CMakeLists.txt

Sets minimum CMake 3.5, C++17, Darwin system, and project name 'hypervisor'. Finds JNI and reports include dirs, then builds a MODULE library from hypervisor.mm and headers, sets the suffix to .dylib, and links the Hypervisor framework, Objective-C runtime, and JNI libraries.

```CMake
cmake_minimum_required(VERSION 3.5)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)
set(CMAKE_SYSTEM_NAME Darwin)
set(PROJECT_LIB_NAME hypervisor)

find_package(JNI REQUIRED)
if (JNI_FOUND)
    message (STATUS "JNI_INCLUDE_DIRS=${JNI_INCLUDE_DIRS}")
endif()

project(${PROJECT_LIB_NAME})

# generate libhypervisor.dylib
include_directories(${PROJECT_LIB_NAME}
    ${JNI_INCLUDE_DIRS}
    ${JAVA_INCLUDE_PATH2}
)
add_library(${PROJECT_LIB_NAME} MODULE
    hypervisor.mm
    hypervisor.h
    khash.h
    vcpu.h
    com_github_unidbg_arm_backend_hypervisor_Hypervisor.h
)
set_target_properties(${PROJECT_LIB_NAME} PROPERTIES SUFFIX ".dylib")
target_link_libraries(${PROJECT_LIB_NAME} "-framework Hypervisor -lobjc")
target_link_libraries(${PROJECT_LIB_NAME} ${JNI_LIBRARIES})
```

--------------------------------

### Sign Java binary with ldid for Hypervisor entitlement

Source: https://github.com/zhkl0228/unidbg/blob/master/backend/hypervisor/README.md

Signs the java binary with the hypervisor entitlement using ldid. Requires sudo and must be run from the backend/hypervisor/assets directory.

```bash
cd backend/hypervisor/assets
sudo ./ldid -M -Shypervisor.entitlements "$JAVA_HOME"/bin/java
```

--------------------------------

### MemoryBlock Interface

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/memory.md

Represents a block of memory in the emulated process. Provides methods to get the pointer, check if it points to the same memory, and free the block.

```APIDOC
## MemoryBlock Interface

### Description
Represents a block of memory in the emulated process. Provides methods to get the pointer, check if it points to the same memory, and free the block.

### Methods

#### getPointer()
- **Return type**: `UnidbgPointer`
- **Description**: Returns the pointer to the start of the memory block.

#### isSame(Pointer pointer)
- **Parameters**: `pointer` (Pointer) - The pointer to compare.
- **Return type**: `boolean`
- **Description**: Checks if the given pointer points to the same memory block.

#### free()
- **Return type**: `void`
- **Description**: Frees the memory block.
```

--------------------------------

### Backend Capability Matrix

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Lists the capabilities of each backend (Unicorn, Hypervisor, Dynarmic/KVM) for the MCP server tools.

```APIDOC
## Backend Capability Matrix

### Description
Different backends provide varying levels of support for MCP server tools. This matrix outlines the capabilities.

### Backends
- **Unicorn / Unicorn2**: FULL - All tools available
- **Hypervisor**: PARTIAL - Limited hardware breakpoints, 1 code trace, no `next_block`/`step_until_mnemonic`
- **Dynarmic / KVM**: MINIMAL - Breakpoints only, no trace/step
```

--------------------------------

### ptr.getByteArray(offset, length)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/pointer.md

Reads a byte array from guest memory starting at the specified offset and with the given length. May throw InvalidMemoryAccessException if the address is unmapped.

```APIDOC
## ptr.getByteArray(offset, length)

### Description
Reads a byte array from guest memory starting at the specified offset and with the given length. May throw InvalidMemoryAccessException if the address is unmapped.

### Method
Instance method

### Parameters
- `offset` (long) - Required - The byte offset from the pointer's base address.
- `length` (int) - Required - The number of bytes to read.

### Returns
- `byte[]` - The byte array read from memory.

### Exceptions
- `InvalidMemoryAccessException` - Thrown if the address is unmapped.

### Usage Example
```java
byte[] data = ptr.getByteArray(0, 0x100);
```
```

--------------------------------

### McpServer Constructor

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/mcp.md

Creates a new MCP server instance bound to the given emulator and port.

```APIDOC
## McpServer(Emulator<?> emulator, int port)

### Description
Creates a new MCP server instance for the given emulator, listening on the specified port.

### Method
Constructor

### Parameters
- **emulator** (Emulator<?>) - Required - The emulator instance to associate with the server.
- **port** (int) - Required - The TCP port on which the server will listen.

### Usage Example
```java
McpServer server = new McpServer(emulator, 9239);
```
```

--------------------------------

### Access memory leak report programmatically with tracker.getLeaks()

Source: https://github.com/zhkl0228/unidbg/blob/master/README.md

Retrieve the list of AllocationRecord objects before the tracker closes. The example asserts that no leaks are present, failing if a leak is detected.

```java
try (MemoryTracker tracker = emulator.traceMemoryLeaks()) {
    module.callFunction(emulator, "targetFunction", arg1, arg2);
    List<AllocationRecord> leaks = tracker.getLeaks();
    assert leaks.isEmpty() : "Memory leak detected!";
}
```

--------------------------------

### LoadedIpa.setCallFinishLaunchingWithOptions(boolean)

Source: https://github.com/zhkl0228/unidbg/blob/master/_autodocs/api-reference/ios-emulator.md

Sets whether to call the finishLaunchingWithOptions method during entry.

```APIDOC
## LoadedIpa.setCallFinishLaunchingWithOptions(boolean)

### Description
Sets whether to call the finishLaunchingWithOptions method during entry.

### Method
setCallFinishLaunchingWithOptions

### Signature
public void setCallFinishLaunchingWithOptions(boolean callFinishLaunchingWithOptions);

### Parameters
- **callFinishLaunchingWithOptions** (boolean) - Required - true to call the method, false otherwise.
```
Tokens:
Raw