Vortex-DBG

在非设备环境下，同时模拟 Android 原生库和 DEX/Java 类。

很多时候，当你对一款应用进行逆向工程时，提取原生库或某个 Java 类并直接**模拟**它，远比将其重写为白盒实现更有价值。通常这足以先对某些功能进行验证，然后再决定是否值得投入成本将其翻译为其他语言。这正是 Vortex-DBG 被创造出来的原因。 ## 文档 **[www.vortexdbg.reverselabs.dev](https://www.vortexdbg.reverselabs.dev)** 在文档中，你可以了解该项目，学习如何使用它来构建**用于生产环境**的内容，以及如何使用 **MCP** 集成。本 README 仅作为一个快速概述。 ## 工作原理（一图看懂生产级流程） ``` flowchart LR A["Target app (.apk)
classes.dex (Java)
lib*.so (native, huge)"] B["Vortex-DBG
native .so on a CPU emulator
DEX/Java on a host JVM
(bidirectional JNI bridge)"] C["The value you needed
off-device and automated:
keychain / token / signature"] A -- load --> B -- call --> C ``` 假设一款应用包含一个 DEX 类以及一个庞大且经过混淆的原生库，它们共同计算出你想要的某些内容，例如钥匙串、请求签名或加密 token。对所有这些进行逆向工程并将其重写为白盒实现不仅成本高昂，而且非常脆弱。相反，Vortex-DBG 将应用的 `.so` 加载到 CPU 模拟器上，并在真实的宿主机 JVM 上运行其 DEX/Java 类，通过双向 JNI 桥接将它们连接起来，因此你可以直接**调用函数并获取结果**，支持离线设备批量执行，无需在整个过程中使用 root 手机。 ## MCP 工具 除了生产环境应用，Vortex-DBG 还可通过 MCP 用于**实验和研究**。它已经内置了大量 MCP 工具，因此 AI 客户端（Claude Code、Cursor 或任何 MCP 客户端）可以为你驱动模拟器：探测原生（ARM）端和 Dalvik/Java (DVM) 端、设置断点、跟踪 JNI 桥接以及调用函数，所有这些都可以通过对话完成。 每个工具都使用 `vortexdbg-` 前缀进行命名空间划分。以下每个工具在 [`tests/MCP/`](tests/MCP) 下都有可运行的示例（包含六个演示应用和一个一键执行的 `run-all.sh`）。如需完整的参考和工作流程，请阅读[文档](https://www.vortexdbg.reverselabs.dev)。 ### 原生 (ARM) 工具 | 工具 | 功能 | 试用于 | |---|---|---| | `vortexdbg-check_connection` | 模拟器状态：架构、后端、状态、已加载模块 | [01app](tests/MCP/01app) | | `vortexdbg-list_modules` | 列出已加载的 `.so` 模块（可选名称过滤） | [01app](tests/MCP/01app) | | `vortexdbg-get_module_info` | 模块的基址、大小、导出数量、依赖项 | [01app](tests/MCP/01app) | | `vortexdbg-list_exports` | 模块的导出符号（可选过滤，反混淆） | [01app](tests/MCP/01app) | | `vortexdbg-find_symbol` | 按名称解析符号，或查找最接近某个地址的符号 | [01app](tests/MCP/01app) | | `vortexdbg-get_threads` | 列出模拟器线程/任务（运行时包含参数） | [06app](tests/MCP/06app) | | `vortexdbg-get_registers` | 读取所有通用寄存器 | [01app](tests/MCP/01app) | | `vortexdbg-get_register` | 按名称读取单个寄存器 | [01app](tests/MCP/01app) | | `vortexdbg-set_register` | 写入单个寄存器 | [01app](tests/MCP/01app) | | `vortexdbg-disassemble` | 反汇编某个地址处的 N 条指令 | [01app](tests/MCP/01app) | | `vortexdbg-disassemble_symbol` | 按模块和符号反汇编函数 | [01app](tests/MCP/01app) | | `vortexdbg-assemble` | 将指令文本汇编为机器码 | [01app](tests/MCP/01app) | | `vortexdbg-read_args` | 解码调用约定的参数寄存器 | [01app](tests/MCP/01app) | | `vortexdbg-read_memory` | 某个地址处内存的十六进制转储 | [01app](tests/MCP/01app) | | `vortexdbg-write_memory` | 将原始十六进制字节写入内存 | [01app](tests/MCP/01app) | | `vortexdbg-write_string` | 将以 null 结尾的 C 字符串写入内存 | [01app](tests/MCP/01app) | | `vortexdbg-read_string` | 读取以 null 结尾的 C 字符串 | [01app](tests/MCP/01app) | | `vortexdbg-read_std_string` | 读取 C++ libc++ 的 `std::string`（SSO 和堆） | [03app](tests/MCP/03app) | | `vortexdbg-read_pointer` | 跟随指针链并进行符号解析 | [04app](tests/MCP/04app) | | `vortexdbg-read_typed` | 读取类型化值（int8..int64, float, double, pointer） | [04app](tests/MCP/04app) | | `vortexdbg-search_memory` | 在内存中搜索十六进制模式或字符串 | [01app](tests/MCP/01app) | | `vortexdbg-list_memory_map` | 列出映射的内存区域及权限 | [01app](tests/MCP/01app) | | `vortexdbg-patch` | 汇编指令并将其写入内存 | [01app](tests/MCP/01app) | | `vortexdbg-allocate_memory` | 分配 RW 临时缓冲区（malloc/mmap） | [01app](tests/MCP/01app) | | `vortexdbg-free_memory` | 释放通过 allocate_memory 分配的缓冲区 | [01app](tests/MCP/01app) | | `vortexdbg-list_allocations` | 列出活动的内存分配 | [01app](tests/MCP/01app) | | `vortexdbg-add_breakpoint` | 在某个地址添加断点 | [01app](tests/MCP/01app) | | `vortexdbg-add_breakpoint_by_symbol` | 在模块符号处添加断点 | [01app](tests/MCP/01app) | | `vortexdbg-add_breakpoint_by_offset` | 在模块基址 + 偏移量处添加断点 | [01app](tests/MCP/01app) | | `vortexdbg-remove_breakpoint` | 移除断点 | [01app](tests/MCP/01app) | | `vortexdbg-list_breakpoints` | 列出断点及其反汇编 | [01app](tests/MCP/01app) | | `vortexdbg-continue_execution` | 从当前 PC 恢复执行 | [01app](tests/MCP/01app) | | `vortexdbg-step_over` | 步过当前指令 | [01app](tests/MCP/01app) | | `vortexdbg-step_into` | 执行 N 条指令后停止 | [01app](tests/MCP/01app) | | `vortexdbg-step_out` | 运行直到当前函数返回 | [01app](tests/MCP/01app) | | `vortexdbg-next_block` | 在下一个基本块处中断 (Unicorn) | [01app](tests/MCP/01app) | | `vortexdbg-step_until_mnemonic` | 运行直到下一个匹配的助记符 (Unicorn) | [01app](tests/MCP/01app) | | `vortexdbg-poll_events` | 获取排队的事件（breakpoint_hit, traces, completed） | [01app](tests/MCP/01app) | | `vortexdbg-trace_code` | 跟踪地址范围内的指令执行 | [01app](tests/MCP/01app) | | `vortexdbg-trace_read` | 跟踪地址范围内的内存读取 | [01app](tests/MCP/01app) | | `vortexdbg-trace_write` | 跟踪地址范围内的内存写入 | [01app](tests/MCP/01app) | | `vortexdbg-get_callstack` | 回溯，包含模块、偏移量和最近的符号 | [06app](tests/MCP/06app) | | `vortexdbg-call_function` | 在指定地址调用带有类型化参数的原生函数 | [01app](tests/MCP/01app) | | `vortexdbg-call_symbol` | 按模块和符号调用导出的函数 | [01app](tests/MCP/01app) | ### Dalvik / Java (DVM) 工具 | 工具 | 功能 | 试用于 | |---|---|---| | `vortexdbg-dvm_list_classes` | 列出在宿主机 JVM 上解析的 Dalvik 类 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_search_classes` | 按名称搜索已解析的类（子字符串或正则表达式） | [01app](tests/MCP/01app) | | `vortexdbg-dvm_class_hierarchy` | 某个类的超类链和接口 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_describe_class` | VM 为某个类涉及的方法和字段 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_describe_method` | 解码 JNI 方法签名（参数和返回值） | [01app](tests/MCP/01app) | | `vortexdbg-dvm_list_native_registrations` | 每个类的 RegisterNatives 绑定（方法到指针） | [02app](tests/MCP/02app) | | `vortexdbg-dvm_dex_surface` | 列出或搜索 DEX 类、方法和字符串 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_call_static` | 通过桥接调用静态 Java/native 方法 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_call_instance` | 在对象句柄上调用实例方法 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_oracle` | 调用方法并根据预期值断言结果 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_fuzz_method` | 对输入批量调用方法并制成字节差异表 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_make_object` | 创建 String/bytes/array 对象并返回句柄 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_new_object` | 构造应用对象并返回句柄 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_new_array_object` | 从句柄/字符串构建 `Object[]` | [01app](tests/MCP/01app) | | `vortexdbg-dvm_pin_ref` | 将句柄提升为全局引用 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_release_ref` | 从全局引用表中丢弃句柄 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_list_objects` | 列出活跃的 JNI 对象引用（本地和全局） | [01app](tests/MCP/01app) | | `vortexdbg-dvm_get_object` | 按句柄获取对象的类和值 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_inspect_object` | 句柄的深度视图：作用域、引用计数、值、长度 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_read_string` | StringObject 句柄对应的 Java String 值 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_read_array` | 数组句柄的类型化内容 | [04app](tests/MCP/04app) | | `vortexdbg-dvm_to_string` | 尽力将句柄渲染为 String | [01app](tests/MCP/01app) | | `vortexdbg-dvm_read_field` | 读取静态或实例字段 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_set_field` | 写入静态或实例字段 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_object_graph` | 所有按类或作用域分组的活跃引用 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_find_objects_by_class` | 给定类的活跃句柄 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_ref_table_stats` | 引用表计数和每个类的直方图 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_pending_exception` | 当前挂起的 JNI 异常 | [05app](tests/MCP/05app) | | `vortexdbg-dvm_resolve_native_handle` | 将 的 jobject/jmethodID/jfieldID 解析为其 DVM 实体 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_handle_to_native` | 将 DVM 句柄解析为其 native 对等物、作用域和引用计数 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_class_of_native` | 将 jclass 对等物或 `Java_` 符号解析为其 DVM 类 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_args_at_breakpoint` | 将 native 断点处的 JNI 参数解码为 DVM 对象 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_resolve_method` | 为一个纯粹的方法名查找 JNI 签名 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_trace_jni` | 记录 native 到 Java 的 JNI callback | [02app](tests/MCP/02app) | | `vortexdbg-dvm_jni_log` | 读取（并清除）已记录的 JNI trace 和中断事件 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_mock_jni` | 覆盖 JNI callback 的返回值 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_break_on_jni` | 在触发 JNI callback 时记录快照 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_spoof_env` | 安装一组设备身份模拟 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_snapshot` | 对 DVM 状态进行快照（类和引用） | [01app](tests/MCP/01app) | | `vortexdbg-dvm_diff` | 对比两个 DVM 快照 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_export` | 将对象、快照或对象图写入磁盘 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_call_phase` | 记录一系列工具调用并进行重放 | [01app](tests/MCP/01app) | 举个例子：假设你想模拟银行应用中的某个函数。你加载它的 `.so`，要求 AI 执行 `vortexdbg-add_breakpoint_by_symbol`，触发调用，然后使用 `vortexdbg-read_args` / `vortexdbg-dvm_call_static` / `vortexdbg-dvm_trace_jni` 来观察 native 和 Java 的交互，并提取出它计算的结果。这仅仅是个快速预览。有关完整的工作流程和完整的工具参考，请阅读[文档](https://www.vortexdbg.reverselabs.dev)。 ## 致谢 - [unidbg](https://github.com/zhkl0228/unidbg) - [unicorn](https://github.com/zhkl0228/unicorn) - [dynarmic](https://github.com/MerryMage/dynarmic) - [HookZz](https://github.com/jmpews/Dobby) - [xHook](https://github.com/iqiyi/xHook) - [AndroidNativeEmu](https://github.com/AeonLucid/AndroidNativeEmu) - [usercorn](https://github.com/lunixbochs/usercorn) - [keystone](https://github.com/keystone-engine/keystone) - [capstone](https://github.com/aquynh/capstone) - [idaemu](https://github.com/36hours/idaemu) - [jelf](https://github.com/fornwall/jelf) - [whale](https://github.com/asLody/whale) - [mman-win32](https://github.com/mcgarrah/mman-win32) ## 许可证 [Apache License 2.0](LICENSE)。Vortex-DBG 是基于 [unidbg](https://github.com/zhkl0228/unidbg) (Apache-2.0) 架构的衍生作品。请参阅 [NOTICE](NOTICE)。

标签：AI驱动, DEX, Kotlin, Unicorn2, 云资产清单, 代码模拟, 安卓, 逆向工程