PyUniDbg

Pure-Python multi-architecture native library emulator with JNI, hooks, a GDB server, and a built-in web UI.

PyUniDbg loads Android .so (and iOS dylib / Mach-O) native libraries on your desktop machine, runs them under Unicorn Engine, and exposes a Python-first API for hooking, tracing, and instrumentation similar in spirit to unidbg — but without any Java dependency.

Features

• Pure Python — no JVM, no native build step required.
• Multi-architecture — arm, arm64, x86, x86_64.
• ELF / Mach-O loading — full segment mapping, dynamic linker, init arrays.
• Complete JNI layer — JNIEnv, JavaVM, jstrings, jbyteArray, jclass…
• Linux/Android syscalls — open, read, mmap, fstat (full struct), ptrace, signals…
• libc emulation — pthread, stdio, stdlib, string, wchar, memory…
• Hooks — function, syscall, code, memory-read/write, address ranges.
• Frida-compatible scripting — Interceptor, Memory, Module, Process, NativePointer, Stalker, Java.
• Debugging — breakpoints, single-step, watchpoints, GDB-stub server, DAP/LLDB bridge.
• Snapshots & time-travel — save/restore CPU + memory state, diff snapshots.
• Coverage / tracing / taint — drcov export, instruction-level tracing, taint analysis.
• Anti-debug bypass — /proc/self/status, ptrace, signals, timing checks.
• IDE bridges — IDA Pro, Ghidra, Binary Ninja, Radare2.
• Web UI — browser-based session manager with terminal, disassembly, scripting tab.

Installation

From PyPI (once published)

pip install pyunidbg                 # core engine only
pip install "pyunidbg[web]"          # + FastAPI web UI
pip install "pyunidbg[all]"          # everything (web, integrations, concolic, pwn, dev)

From source

git clone https://github.com/elvi7major/PyUniDbg.git
cd PyUniDbg
pip install -e ".[dev]"

Quick Start

from pyunidbg import AndroidEmulator

emu = AndroidEmulator(arch="arm64")

# Load a native library
module = emu.load_library("libnative.so")

# Allocate a JNI string and call a JNI function
jstr   = emu.jni.new_string_utf("Hello World")
result = emu.call(
    module.find_symbol("Java_com_example_Native_encrypt").address,
    args=[emu.jni.env_ptr, emu.jni.jclass_ptr, jstr],
)
print("encrypted jstring ptr =", hex(result))

Hooking

from pyunidbg import AndroidEmulator, HookAction

emu = AndroidEmulator(arch="arm64")

@emu.hook.function("strlen")
def _trace_strlen(emu, address, args):
    print("strlen(", emu.memory.read_string(args[0]), ")")
    return HookAction.CONTINUE

@emu.hook.syscall("openat")
def _trace_open(emu, dfd, path_ptr, flags, mode):
    print("open(", emu.memory.read_string(path_ptr), ")")
    return HookAction.CONTINUE

Command-line interface

pyunidbg run    libnative.so
pyunidbg call   libnative.so -f Java_com_example_getSign --args "input" --context
pyunidbg scan   libnative.so --jni --apk app.apk --with-address
pyunidbg info   libnative.so --exports
pyunidbg debug  libnative.so -p 1234           # GDB stub
pyunidbg analyze libnative.so --coverage -o coverage.drcov --format drcov

The CLI is also reachable via python -m pyunidbg. See docs/cli.md for every command and option.

Web interface

pip install "pyunidbg[web]"
pyunidbg-web --port 8080

Open http://localhost:8080 and you get a full session manager with terminal, disassembly, hex view, hook manager, scripting tab and live log streaming.

Architecture

+-------------------------------------------------------+
|                     PyUniDbg                          |
+-------------------------------------------------------+
|  High-Level API  (CLI / Frida-bridge / Web UI / Apps) |
+-------------------------------------------------------+
|  JNI layer       |  Syscall layer  |  libc/libart     |
+-------------------------------------------------------+
|  Memory Manager  |  Virtual FS     |  Snapshot system |
+-------------------------------------------------------+
|  ELF / Mach-O loader   |   Dynamic linker             |
+-------------------------------------------------------+
|  CPU Emulator (Unicorn Engine)                        |
|  ARM    |   ARM64   |   x86   |   x86_64              |
+-------------------------------------------------------+

Documentation

• What's New in 0.2.0
• Getting Started
• CLI Reference
• Architecture
• API Reference
• Android Emulator
• Hooks Guide
• JNI Reference
• Syscall Reference
• Debugging & Analysis
• Integrations (IDA / Ghidra / Binja / Radare2)
• Examples

Examples

• examples/basic_usage.py — minimal emulator setup, memory and JNI string demo.
• examples/real_world_demo/ — end-to-end demo against a self-built native library that mirrors real-world Android app patterns (anti-debug, sign generation, XOR string decryption, init-array constructors).

Project status

Beta — the core emulator and Android layer are stable; iOS support and some integrations are still maturing. See ROADMAP.md for what's coming next and CHANGELOG.md for the per-release history.

Known limitations

• iOS / Mach-O loading and the Objective-C runtime are functional for simple binaries but have less coverage than the Android path.
• The x86 and x86_64 backends are new in 0.2.0; the SysV / cdecl ABIs and most libc are wired up, but expect rougher edges than arm / arm64.
• The optional pyunidbg[concolic] extra requires z3-solver, and pyunidbg[pwn] requires pwntools — both are heavy native installs that may need extra tooling on Windows / macOS.
• The web UI (pyunidbg[web]) is single-user by design; do not expose it to untrusted networks without your own authentication layer.

Disclaimer

PyUniDbg is intended for legitimate security research, education and software analysis on binaries you own or are authorised to analyse. By using the project you accept full responsibility for compliance with applicable laws, regulations and licence agreements. Reverse-engineering third-party software may be restricted in your jurisdiction.

Contributing

Pull requests, bug reports, and documentation improvements are very welcome — please read CONTRIBUTING.md first.

License

PyUniDbg is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE for details.

Acknowledgments

• Unicorn Engine — CPU emulation.
• Capstone — disassembly.
• Keystone — assembly / patching.
• LIEF — ELF / Mach-O parsing.
• unidbg — original inspiration.