VortexDBG

<p align="center"> <a href="README.md"><img src="https://img.shields.io/badge/lang-%E8%AF%AD%E8%A8%80-2ea44f" alt="English"></a> <a href="README.zh.md"><img src="https://img.shields.io/badge/%E8%AF%AD%E8%A8%80-%E7%AE%BE%E4%BD%93%E4%B8%AD%E6%96%87-blue" alt="简体中文"></a> </p> <p align="center"> <img src="icon/vortex-logo.png" alt="Vortex-DBG" width="400"/> </p> <h1 align="center">Vortex-DBG</h1> <p align="center"><em>模拟安卓原生库 <b>和</b> DEX/Java 类，一起，在设备外。</em></p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a> <img src="https://img.shields.io/badge/Kotlin-100%25-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin"> <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?logo=linux&logoColor=white" alt="Platform: macOS | Linux"> <img src="https://img.shields.io/badge/arch-ARM32%20%7C%20ARM64-success" alt="Arch: ARM32 | ARM64"> <img src="https://img.shields.io/badge/backends-Unicorn2%20%7C%20Dynarmic%20%7C%20Hypervisor-orange" alt="Backends"> <img src="https://img.shields.io/badge/JVM-8%20build%20%C2%B7%2021%2B%20run-red?logo=openjdk&logoColor=white" alt="JVM"> <img src="https://img.shields.io/badge/MCP-AI%20assisted-brightgreen" alt="MCP"> </p> 在逆向工程应用时，通常情况下，将原生库或 Java 类进行模拟比重写成白盒实现更值得。这往往足以验证某些内容，然后再决定是否值得将其翻译成另一种语言。这正是 Vortex-DBG 被创建的原因。 ## 文档 **[www.vortexdbg.reverselabs.dev](https://www.vortexdbg.reverselabs.dev)** 在文档中，您可以了解该项目的信息，以及如何使用它来构建生产环境中的项目，以及如何使用 **MCP** 集成。本 README 只是一个快速概览。 ## 工作原理（生产环境，一张图） ```mermaid flowchart LR A["<b>目标应用 (.apk)</b><br/>classes.dex (Java)<br/>lib*.so (原生，巨大)"] B["<b>Vortex-DBG</b><br/>原生 .so 在 CPU 模拟器上<br/>DEX/Java 在主机 JVM 上<br/>(双向 JNI 桥)"] C["<b>您需要的值</b><br/>设备外和自动化:<br/>密钥库 / token / 签名"] A -- 加载 --> B -- 调用 --> C ``` 假设某个应用有一个 DEX 类和一个巨大的、混淆的原生库，它们一起计算出您想要的内容，例如密钥库、请求签名或加密 token。逆向工程所有这些并将其重写成白盒实现是昂贵且脆弱的。相反，Vortex-DBG 将应用的 `.so` 加载到 CPU 模拟器上，并运行其 DEX/Java 类在真实的主机 JVM 上，通过双向 JNI 桥连接起来，这样您就可以简单地 **调用函数并获取值**，批量处理和设备外，无需 root 手机。 ## MCP 工具 除了生产环境外，Vortex-DBG 还用于 **通过 MCP 进行实验和研究**。它已经附带了一大套 MCP 工具，因此 AI 客户端（Claude Code、Cursor 或任何 MCP 客户端）可以为您驱动模拟器：poke 原生（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、指针） | [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/原生方法 | [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` | 句柄的深层视图：作用域、refCount、值、长度 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_read_string` | StringObject 句柄的 Java 字符串值 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_read_array` | 数组句柄的键入内容 | [04app](tests/MCP/04app) | | `vortexdbg-dvm_to_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` | native jobject/jmethodID/jfieldID 到其 DVM 实体 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_handle_to_native` | DVM 句柄到其原生对端、作用域和引用计数 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_class_of_native` | jclass peer 或 `Java_` 符号到其 DVM 类 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_args_at_breakpoint` | 在原生断点处解码 JNI 参数为 DVM 对象 | [01app](tests/MCP/01app) | | `vortexdbg-dvm_resolve_method` | 为裸方法名称查找 JNI 签名 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_trace_jni` | 记录原生到 Java 的 JNI 回调 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_jni_log` | 读取（并清除）记录的 JNI 跟踪和断点事件 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_mock_jni` | 覆盖 JNI 回调的返回值 | [02app](tests/MCP/02app) | | `vortexdbg-dvm_break_on_jni` | 记录快照时 JNI 回调触发 | [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` 观察原生和 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).