Metadata-Version: 2.4
Name: pyunidbg
Version: 0.2.0
Summary: Pure-Python multi-architecture native library emulator (Android/iOS) with JNI, hooks, GDB and a web UI
Author-email: Brahim Bendali aka elvi7major <bendalisoftpro@gmail.com>
Maintainer-email: Brahim Bendali aka elvi7major <bendalisoftpro@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/elvi7major/PyUniDbg
Project-URL: Repository, https://github.com/elvi7major/PyUniDbg
Project-URL: Documentation, https://github.com/elvi7major/PyUniDbg/tree/main/docs
Project-URL: Changelog, https://github.com/elvi7major/PyUniDbg/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/elvi7major/PyUniDbg/issues
Keywords: android,ios,emulator,unicorn,reverse-engineering,jni,native,arm64,frida,debugger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Disassemblers
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: unicorn>=2.1.0
Requires-Dist: capstone>=5.0.3
Requires-Dist: keystone-engine>=0.9.2
Requires-Dist: lief>=0.14.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: rich>=13.0.0
Provides-Extra: web
Requires-Dist: fastapi>=0.110.0; extra == "web"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Requires-Dist: websockets>=12.0; extra == "web"
Provides-Extra: integrations
Requires-Dist: requests>=2.28.0; extra == "integrations"
Provides-Extra: config
Requires-Dist: PyYAML>=6.0; extra == "config"
Provides-Extra: concolic
Requires-Dist: z3-solver>=4.12.0; extra == "concolic"
Provides-Extra: pwn
Requires-Dist: pwntools>=4.12.0; extra == "pwn"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.15.8; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: pyunidbg[concolic,config,dev,integrations,pwn,web]; extra == "all"
Dynamic: license-file

# PyUniDbg

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

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)]()

PyUniDbg loads Android `.so` (and iOS `dylib` / Mach-O) native libraries on
your desktop machine, runs them under [Unicorn Engine](https://www.unicorn-engine.org/),
and exposes a Python-first API for hooking, tracing, and instrumentation
similar in spirit to [unidbg](https://github.com/zhkl0228/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)

```bash
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

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

---

## Quick Start

```python
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

```python
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

```bash
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](docs/cli.md) for every command and option.

## Web interface

```bash
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](docs/whats-new-0.2.0.md)
- [Getting Started](docs/getting-started.md)
- [CLI Reference](docs/cli.md)
- [Architecture](docs/architecture.md)
- [API Reference](docs/api-reference.md)
- [Android Emulator](docs/android.md)
- [Hooks Guide](docs/hooks.md)
- [JNI Reference](docs/jni.md)
- [Syscall Reference](docs/syscalls.md)
- [Debugging & Analysis](docs/debugging.md)
- [Integrations (IDA / Ghidra / Binja / Radare2)](docs/integrations.md)
- [Examples](examples/)

## Examples

- [`examples/basic_usage.py`](examples/basic_usage.py) — minimal emulator
  setup, memory and JNI string demo.
- [`examples/real_world_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](ROADMAP.md) for what's coming next and
[CHANGELOG.md](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](CONTRIBUTING.md) first.

## License

PyUniDbg is licensed under the **Apache License, Version 2.0**.
See [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.

## Acknowledgments

- [Unicorn Engine](https://www.unicorn-engine.org/) — CPU emulation.
- [Capstone](https://www.capstone-engine.org/) — disassembly.
- [Keystone](https://www.keystone-engine.org/) — assembly / patching.
- [LIEF](https://lief-project.github.io/) — ELF / Mach-O parsing.
- [unidbg](https://github.com/zhkl0228/unidbg) — original inspiration.
