runidbg
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 19 GitHub stars
Code Gecti
- Code scan — Scanned 8 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
High-performance Android ARM64 .so emulator, zero-copy binary tracer, QuickJS engine, async multi-core RPC & MCP server in pure Rust
[!WARNING]
免责声明:本项目(runidbg)仅用于二进制安全研究、逆向工程学习、性能评测及经授权的安全测试。严禁将本项目用于任何违反法律法规或未经授权的用途;因使用本项目产生的任何后果与法律责任均由使用者自行承担。
⚡ runidbg (runidbg-arm64-emu-tracer)
Rust + unidbg = runidbg · 纯 Rust 实现的高性能 Android ARM64 .so 仿真器、零拷贝二进制 Tracer 与 QuickJS 脚本引擎
内置异步多核 RPC 服务 · MCP AI 逆向闭环 · GDB RSP 远程调试 · 统一设备画像模拟
简体中文 | English | 完整使用指南 | AI Agent Skill
| 🚀 冷启动速度 | 🔥 全模块 Trace 吞吐 | 💾 单实例 RPC 内存 | ⚙️ 多核 RPC 吞吐 | 📦 单条 Trace 体积 |
|---|---|---|---|---|
77 ms (22.6× vs unidbg) |
17.03 M insns/s (114× vs unidbg) |
21.7 MB (省 82%) |
1,141 QPS (10 核) | 32 B / insn (省 3.7×) |
🤝 欢迎提交不兼容样本与反馈
runidbg 仍在快速演进中,非常欢迎通过 Issue / PR 提交在仿真中遇到报错、缺失符号/系统调用/JNI 或结果不一致的 Android ARM64 .so 样本与最小复现脚本,帮助我们持续完善兼容性与生态覆盖!
反馈时请先脱敏去除真实 Cookie / Token 等敏感凭据,推荐附带:
- 最小复现脚本(QuickJS 脚本或 Rust 用例)与脱敏测试输入;
EnvDiag诊断输出(JSON.stringify(emu.diag.report(), null, 2),自动列出缺失文件、系统属性、Syscall 与 JNI);- 崩溃现场报告(如发生异常,附
emu.lastCrash()?.formatted输出的寄存器、反汇编、调用栈与面包屑)。
✨ 核心特性
- 🦀 Android ARM64 原生仿真底座:基于 Unicorn 2.1 +
goblin,完整支持 ELF 动态链接(.init_array、IRELATIVE、符号重定位、DT_NEEDED递归加载、TLSTPIDR_EL0)、高频 libc/libm HLE 加速(含真实 AAPCS64vsnprintf/__snprintf_chk/sscanf/asprintf/atoll)、VMA/MMU 内存管理与防反调试。 - 📱 统一设备画像与双模式时钟(
DeviceProfile):内置pixel5/pixel8pro/s24ultra/xiaomi14真机画像与任意字段覆盖,一处配置自动联动 30+ 系统属性、/proc/cpuinfo、/proc/meminfo、/proc/version、/sys/devices/system/cpu/online与uname;支持确定性虚拟时钟与宿主机实时时钟(realClock)一键切换。 - 🧬 JNI 1.6 完整环境:支持
JNI_OnLoad、RegisterNatives、容器安全的引用生命周期管理、内置常用 Java 模型(String构造与方法、Thread.currentThread()、基础类型装箱valueOf等)以及可插拔 JS/Rust JNI Hook。 - ⚡ 零拷贝二进制 Tracer:支持
fast/reg_delta/full三级分层追踪、mmap双流落盘(.idx+.ext,结束时精确截断无尾部零填充)、毫秒级离线检索(dump/search)以及 IDA Pro / Binary Ninja 覆盖率脚本一键导出。 - 📜 QuickJS 零配置脚本引擎 + TypeScript 智能提示:写 JS 即可完成逆向分析,内置
Emu/Module/jni/mem/regs/hook(Frida 风格attach、replace、code、mem、syscall)/vfs/trace/fs/require(),并通过runidbg-cli init-types导出完整runidbg.d.ts。 - 🌐 生产级异步多核 RPC 服务:基于
tokio+axum+ 无锁 MPMC Worker 池(--workers auto),内置 Keep-Alive、队列背压503、Unicorn 硬超时与指令预算504、JSON-RPC 2.0 Batch、Prometheus/metrics、滚动热重载及async导出。 - 🤖 MCP AI 逆向闭环 & 调试工具链:原生支持 stdio 与 Streamable HTTP 双模式 MCP(14 个逆向工具,含
bad64反汇编、函数级 Trace、一次性 Hook 抓取、崩溃现场诊断)、EnvDiag缺环境自动诊断器、APK 一键内存加载与 ARM64 GDB RSP 远程调试服务端。
📊 性能实测对比(vs Java unidbg)
[!NOTE]
测试口径:Apple Silicon(10 核 ARM64 macOS)、JDK 21(unidbg 0.9.9)vsrunidbg-cli --release。样本为同一份 ~2 MB stripped Android ARM64 安全签名.so(含libc++_shared.so依赖)。以下三组均在两边 100% 产出相同有效签名结果的同一调用路径上同口径对齐实测。
1. 冷启动与进程内热态调用
| 指标 | Java unidbg |
Rust runidbg-cli |
提升倍率 |
|---|---|---|---|
环境初始化 + .so 加载 |
1,666 ms | 40 ms | 41.7× |
JNI_OnLoad |
72 ms | 37 ms | 1.9× |
| 总冷启动耗时 | 1,738 ms | 77 ms | 22.6× |
| 进程内单核热态调用(50 次均值) | 3.80 ms(263.4 QPS) | 1.30 ms(769.2 QPS) | 2.92× |
2. HTTP RPC 并发服务对比(100% 返回值校验通过)
Java 侧使用 JDK 21 内置
HttpServer封装单实例unidbg(synchronized),Rust 侧直接使用runidbg-cli serve。
| 服务配置 | 校验通过 | 吞吐 (QPS) | p50 延迟 | p95 延迟 | 常驻内存 (RSS) | 对比 |
|---|---|---|---|---|---|---|
Java unidbg(1 worker) |
100/100 | 254.7 | 38.35 ms | 41.03 ms | 122.1 MB | 基线 1× |
Rust runidbg(--workers 1) |
100/100 | 628.7 | 15.83 ms | 15.99 ms | 21.7 MB | 2.47× QPS · 省 82% 内存 |
Rust runidbg(--workers auto=10) |
200/200 | 1,141.0 | 8.74 ms | 35.94 ms | 127.5 MB | 4.48× QPS · 10 实例 ≈ Java 1 实例内存 |
xychart-beta
title "HTTP RPC Throughput (QPS, Higher is Better)"
x-axis ["unidbg (1w)", "runidbg (1w)", "runidbg (10w auto)"]
y-axis "QPS" 0 --> 1250
bar [255, 629, 1141]
3. 全模块指令级 Trace 对比([base, base+size])
| 引擎 / 模式 | 耗时 | 记录条数 | 归一化吞吐 | 单条体积 | 吞吐倍率 |
|---|---|---|---|---|---|
Java unidbg(traceCode 文本流) |
1,851.1 ms | 275,381 | 0.149 M insns/s | ~118 B/条(31 MB) | 1× |
Rust runidbg(fast 二进制 mmap) |
64 ms | 1,090,194 | 17.03 M insns/s | 32 B/条(33 MB) | 114× |
Rust runidbg(reg_delta 二进制 mmap) |
212 ms | 1,090,194 | 5.14 M insns/s | 32 B/条(33 MB) | 34.5× |
Rust runidbg(full 双流 + 20.1 万内存 R/W) |
233 ms | 1,090,194 + 201,209 ext | 4.68 M insns/s | 32 B/条(33 MB + 6.1 MB) | 31.4× |
xychart-beta
title "Full-Module Instruction Trace Throughput (M insns/s)"
x-axis ["unidbg traceCode", "runidbg full", "runidbg reg_delta", "runidbg fast"]
y-axis "M insns/s" 0 --> 18
bar [0.15, 4.68, 5.14, 17.03]
⚖️ 与 Java unidbg 全面对比
| 维度 | runidbg(本项目) |
Java unidbg |
|---|---|---|
| 运行性能与内存 | ✅ 原生 Rust,冷启动快 22.6×、单核热态快 2.9×、RPC 内存仅 1/5.6(21.7 MB vs 122.1 MB) | ⚠️ JVM + JNI/JNA 跨边界开销,冷启动 ~1.7s,单实例 ~122 MB |
| 指令级 Trace | ✅ 零拷贝 mmap 二进制双流 + 离线 bad64 解码,吞吐高 31×–114×,自带 dump/search/IDA/BN 导出 |
⚠️ 热路径实时 Capstone 文本反汇编落盘,吞吐 ~0.15 M/s,文本体积大 3.7× |
| 脚本开发体验 | ✅ 零编译 QuickJS + 完整 runidbg.d.ts 智能提示 + Frida 风格 Hook + EnvDiag 自动生成补环境 JS |
⚠️ 需配置 Maven/JDK 工程并编写/编译 Java 代码,迭代周期更长 |
| 工程化与 AI 集成 | ✅ 原生内置多核异步 HTTP/JSON-RPC 2.0、Prometheus /metrics、热重载、MCP 14 工具、GDB RSP、APK 加载 |
⚠️ 核心定位为 Java 库,RPC 服务池、监控、AI Agent 接入需自行二次封装 |
| 平台与架构支持 | ⚠️ 目前仅支持 Android ARM64(aarch64),暂不支持 ARM32 与 iOS |
✅ 支持 Android ARM32 / ARM64 以及 iOS(Mach-O / ObjC) |
| 成熟度与样本生态 | ⚠️ 项目较新,已验证 Cronet / Conscrypt / MMKV / SQLite / WebP / Zstd / 真实 MSSDK 等,但冷门系统库与长尾样本覆盖仍在持续扩充 | ✅ 多年社区沉淀,公开案例、教程、Android 系统类桩与边缘 syscall 覆盖非常成熟 |
| Java 字节码执行 | ⚠️ 无内置 ART/Dalvik 解释器,Java 侧回调依赖内置模型与 JS Hook 补全 | ⚠️ 同样不直接解释执行 DEX 字节码,依赖 AbstractJni 补环境 |
[!TIP]
怎么选?
- 优先选
runidbg:目标是 Android ARM64.so,追求极致启动/并发/Trace 性能,希望用 JS/TS 快速迭代、一键起高并发 RPC 服务,或需要接入 AI Agent(MCP)自动化逆向。- 优先选
unidbg:需要仿真 ARM32 或 iOS Mach-O,或目标依赖大量社区现成 Java 补环境代码与历史方案。
🏗️ 项目架构
flowchart TB
subgraph Entry["接入与协议层 (CLI / Script / Service / Debugger)"]
CLI["runidbg-cli\nrun / serve / mcp / debug / trace"]
RPC["Async RPC Server (tokio + axum)\nKeep-Alive · Batch · /metrics · Hot Reload"]
MCP["MCP Server (stdio / HTTP)\n14 Reverse-Engineering Tools"]
GDB["GDB RSP Stub (TCP)\nIDA Pro · Binary Ninja · pwndbg"]
end
subgraph ScriptLayer["QuickJS 脚本与多核调度层 (src/script/)"]
Pool["Worker Pool (async-channel MPMC)\n默认 1 实例 · 支持 --workers auto"]
Session["JsSession + bootstrap.js\nrpc.exports · Promise · require() · LogSink"]
Bridge["Native Bridge & Hooks\nattach · replace · code · mem · syscall · JNI"]
end
subgraph Facade["高层仿真门面与分析引擎"]
Emu["AndroidEmulator\nUnicorn 硬超时 · 指令预算 · 统一调度"]
Snap["EmuSnapshot\nCPU + 可写页毫秒级快照回放"]
Tracer["BinaryTracer (mmap + bad64)\nfast / reg_delta / full · IDA/BN 导出"]
Diag["EnvDiag\n缺失 JNI / VFS / Prop / Syscall 诊断与模板生成"]
end
subgraph Runtime["Android ARM64 运行时底座"]
Loader["DynamicLinker + ApkPackage\nELF 重定位 · DT_NEEDED 内存库 · AXML"]
HLE["TrampolineTable\nHLE libc / libm 加速跳板"]
JNI["JniVm (JNI 1.6)\nObjectTable · va_list · RegisterNatives"]
OS["DeviceProfile + VirtualFs + Syscall\n30+ 系统属性 · /proc · uname · SVC · 防反调试"]
Core["Unicorn 2.1 ARM64 + MemoryManager (VMA/MMU) + CpuContext"]
end
CLI --> RPC
CLI --> MCP
CLI --> GDB
CLI --> Session
RPC --> Pool --> Session
MCP --> Session
Session --> Bridge --> Emu
GDB --> Emu
Emu --> Snap
Emu --> Tracer
Emu --> Diag
Emu --> Loader
Emu --> HLE
Emu --> JNI
Emu --> OS
Loader --> Core
HLE --> Core
JNI --> Core
OS --> Core
📂 展开查看完整源码目录结构
src/
├── lib.rs # 库入口与核心导出
├── main.rs # 最小命令行示例入口(直接加载 .so 并执行指定符号)
├── emulator.rs # AndroidEmulator / AndroidEmulatorBuilder 门面
├── cpu.rs # ARM64 寄存器与调用约定封装
├── crash.rs # Guest 崩溃报告捕获(反汇编、寄存器、调用栈与面包屑)
├── logging.rs # 结构化日志初始化(compact / json)
├── diag.rs # 缺环境自动诊断器与 JS 补环境模板生成
├── debug/gdbstub.rs # ARM64 GDB Remote Serial Protocol 远程调试服务端
├── memory.rs # VMA 虚拟内存管理与访存辅助
├── snapshot.rs # 内存 + 寄存器快照保存与恢复
├── error.rs # 统一错误类型
├── loader/ # ELF 解析、动态链接器、APK 一键加载与 HLE Trampoline
├── os/ # 设备画像(DeviceProfile)、SVC 系统调用、VFS 虚拟文件系统、协作调度
├── jni/ # JNI 1.6 Env、对象表、va_list 解析与 Hook 处理
├── tracer/ # 高速二进制追踪引擎、记录格式与离线 Reader
├── script/ # QuickJS 脚本引擎、RPC 与 MCP
│ ├── mod.rs # JsSession / JsRunner / RUNIDBG_DTS 门面
│ ├── bridge.rs # QuickJS ↔ Rust 原生桥接实现
│ ├── hooks.rs # 原生函数/指令/内存/Syscall Hook 与 TB 缓存刷新
│ ├── jni_bridge.rs # JS JNI Hook 桥接
│ ├── bootstrap.js # JS 运行时封装与 rpc.exports / Promise 调度
│ ├── runidbg.d.ts # TypeScript 类型声明
│ ├── rpc.rs # 异步 HTTP + JSON-RPC 2.0 + 多 Worker 池 + Metrics + 热重载
│ └── mcp.rs # MCP stdio / Streamable HTTP 服务端(14 个逆向工具)
└── bin/runidbg-cli.rs # 统一命令行工具(run / serve / mcp / debug / trace 分析)
🧩 Feature 开关
| Feature | 默认启用 | 说明 |
|---|---|---|
js |
✅ | QuickJS 脚本引擎(rquickjs) |
rpc |
✅ | 异步高并发 HTTP / JSON-RPC 2.0 服务(tokio、axum、async-channel、serde_json) |
mcp |
✅ | MCP stdio / HTTP JSON-RPC 2.0 服务端(serde_json) |
apk |
✅ | APK 一键解析与内存加载(zip) |
纯核心库最小构建(不引入 JS / HTTP / ZIP 依赖,仍包含核心仿真、DeviceProfile、Tracer、EnvDiag 与 GDB Stub):
cargo build --no-default-features
🚀 快速上手
1. 用 QuickJS 编写仿真 + RPC 脚本(20 行即可跑通)
/// <reference path="./runidbg.d.ts" />
const emu = Emu.create({
packageName: "com.example.app",
device: "pixel8pro", // 内置 pixel5 / pixel8pro / s24ultra / xiaomi14,也支持自定义对象覆盖
realClock: true, // 启用宿主机实时时钟(默认确定性虚拟时钟)
searchPaths: ["./libs"],
});
emu.diag.enable(); // 开启缺环境自动诊断
const mod = emu.load("./libs/libtarget.so");
emu.jniOnLoad(mod);
emu.jni.hook("com/example/Env", {
getVersion() { return "1.0.0"; },
});
rpc.exports = {
sign(url) {
const u = emu.jni.newString(String(url));
const ret = emu.call(mod.base + 0x12340, emu.jni.envPtr, 0, u);
return emu.jni.getStringArray(ret);
},
};
# 导出 TypeScript 类型声明获得 IDE 补全
cargo run --release --bin runidbg-cli -- init-types examples/scripts
# 直接运行示例脚本(内置 Cronet / TikTok MSSDK 脱敏测试样例)
cargo run --release --bin runidbg-cli -- run examples/scripts/cronet.js
cargo run --release --bin runidbg-cli -- run examples/scripts/tiktok_metasec.js
2. 启动高并发多核 RPC 服务
# 默认单实例(workers = 1,常驻内存 ~22 MB)
cargo run --release --bin runidbg-cli -- serve examples/scripts/rpc_demo.js \
--listen 127.0.0.1:8080
# 生产多核模式(自动匹配 CPU 核数 + 硬指令预算 + 原子热重载)
cargo run --release --bin runidbg-cli -- serve examples/scripts/rpc_demo.js \
--listen 0.0.0.0:8080 \
--workers auto \
--max-queue 2048 \
--timeout-ms 15000 \
--max-insns 5000000 \
--allow-reload
常用接口:
GET /health:服务状态、Worker 数、队列负载、热重载版本与导出方法GET /metrics/GET /metrics?format=prom:JSON 或 Prometheus 指标与延迟分桶GET /exports:列出rpc.exports全部导出方法POST /call/<method>:直接调用导出方法(Body 为 JSON 参数数组)POST /rpc:标准 JSON-RPC 2.0(支持单条与 Batch 数组并行调用)POST /admin/reload:先校验后原子滚动热重载(需--allow-reload)POST /eval:动态执行 JS(需--allow-eval)
3. 离线二进制 Trace 分析与 IDA / Binary Ninja 导出
# 查看指令反汇编、寄存器增量与关联内存 R/W(自动探测同级 .ext)
runidbg-cli dump trace_full.idx --skip 0 --limit 50
# 毫秒级检索指定寄存器值 / 访存地址 / PC
runidbg-cli search trace_full.idx --val 0x03000001
# 导出 IDA Pro / Binary Ninja 执行覆盖率高亮脚本
runidbg-cli export-ida trace_full.idx --base 0x40000000 --out ida_cov.py
runidbg-cli export-bn trace_full.idx --base 0x40000000 --out bn_cov.py
4. 接入 MCP 客户端(stdio 或 Streamable HTTP)
{
"mcpServers": {
"runidbg": {
"command": "/path/to/target/release/runidbg-cli",
"args": ["mcp", "--cwd", "/path/to/workspace"]
}
}
}
或启动 Streamable HTTP MCP 供远程 Agent 接入:
runidbg-cli mcp --http 127.0.0.1:8090 --cwd .
5. GDB RSP 远程调试(直连 IDA Pro / Binary Ninja / pwndbg)
runidbg-cli debug samples/libstatic-webp.so WebPGetDecoderVersion --listen 127.0.0.1:1234
# 在 gdb-multiarch / pwndbg 中连接:
# target remote 127.0.0.1:1234
🧪 测试与校验
# 全量测试(39/39 通过,覆盖 Cronet / Conscrypt / MMKV / SQLite / WebP / Zstd / TikTok MSSDK / JS / RPC / MCP / GDB / APK / DeviceProfile)
cargo test
# 全 feature 组合 Clippy 零警告校验
cargo clippy --all-targets -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo clippy --no-default-features --features js --all-targets -- -D warnings
cargo clippy --no-default-features --features mcp --all-targets -- -D warnings
🙏 致谢
- 特别致谢 unidbg 及其作者
zhkl0228:runidbg(Rust + unidbg)的命名、Android 沙箱架构与 JNI 桥接思路均深受unidbg启发。尤其令人由衷佩服的是,在那个还没有 AI 辅助编程、全靠纯手搓代码的年代,独自啃下 Android ARM32/ARM64 与 iOS 仿真并多年持续维护出如此优秀的开源项目,背后需要极其扎实的底层技术功底与罕见的毅力。 - 同时感谢 Unicorn Engine、QuickJS /
rquickjs、goblin、bad64等优秀开源项目。
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi