mobile-threat-hunter/dexllm
GitHub: mobile-threat-hunter/dexllm
面向 LLM 的 Android APK/DEX 高性能静态分析器，提供 DAD 级别的 Java 反编译、多维度搜索和对抗性输入防护，专为移动威胁狩猎和恶意软件分诊而构建。
Stars: 0 | Forks: 0
# dexllm
面向 LLM 的 **Android APK / DEX 静态分析器**：包含 C++ 核心（围绕
[LuckyPray/DexKit](https://github.com/LuckyPray/DexKit) 的 pybind11 封装）、内嵌且**完全移植的
DAD 对齐的 Java 反编译器**，以及用于 agent 集成的 MCP 和 FastAPI/SSE 后端。
专为**移动威胁狩猎 / 恶意软件分诊**而构建 —— 快速、低内存占用、可嵌入且
线程安全 —— 而非用于 Xposed 模块开发。
## 安装（无需 C++ 工具链）
提供适用于 **Linux**（`manylinux_2_28` x86_64）和 **macOS**（x86_64 + arm64，macOS 13.3+），
CPython **3.9–3.13** 的 wheel 包。`pip` 会自动选择与您的平台/Python 匹配的 wheel 包：
```
pip install dexllm --find-links https://github.com/mobile-threat-hunter/dexllm/releases/expanded_assets/v0.1.0
# + LLM backends (MCP server + FastAPI/SSE)；额外依赖从 PyPI 解析：
pip install "dexllm[all]" --find-links https://github.com/mobile-threat-hunter/dexllm/releases/expanded_assets/v0.1.0
```
或者从 [**Releases**](https://github.com/mobile-threat-hunter/dexllm/releases)
页面下载特定的 `.whl` 文件，并运行 `pip install ./that-file.whl`。每个版本还提供了源码分发包
（`.tar.gz`），用于在没有 wheel 包的平台上进行构建（需要 C++20 编译器）。
## 快速开始
```
import dexllm
# 通过内容探测文件而无需加载它（处理伪装的 / 无扩展名的 APKs）
dexllm.identify("/path/to/suspect") # → {format, is_apk, has_manifest, dex_count}
dk = dexllm.DexKit("/path/to/app.apk") # .apk/.jar/.zip, a bare .dex, or a disguised container
# 它涉及哪些 framework APIs？（能力 / 威胁分类）
for ref in dk.list_external_method_refs(framework_only=True)[:10]:
print(ref.java_signature)
# 反编译
print(dk.decompile_method_java("Lcom/example/Foo;->bar()V"))
print(dk.decompile_class_java("Lcom/example/Foo;"))
ast = dk.decompile_method_ast("Lcom/example/Foo;->bar()V") # nested AST + Java text
# 搜索
for m in dk.find_methods_using_strings(["http"]):
print(m)
for site in dk.find_call_sites_to_api("Landroid/util/Log;->d(Ljava/lang/String;Ljava/lang/String;)I"):
print(site)
```
LLM 后端（需要 `[all]` 额外依赖）：
```
python -m dexllm.mcp_server # MCP stdio (Claude Desktop / Cursor / Continue)
uvicorn dexllm.server:app --port 8000 # FastAPI + SSE web backend
```
## 文档
- [docs/usage.md](docs/usage.md) — 完整的 API 指南（L1–L7 搜索 + 反编译 + AST）。
- [docs/architecture.md](docs/architecture.md) — 端口适配器架构 / 反编译器 pipeline。
- [docs/dexkit-vs-art-dex-handling.md](docs/dexkit-vs-art-dex-handling.md) — dexllm 的 DEX
处理与 AOSP/ART 的对比（验证、multidex、跨 dex），包含完整的
`VerifyDex` 与 `DexFileVerifier` 逐项检查明细。
## 缘由
| | dexllm |
|---|---|
| 输入 | `.apk`/`.jar`/`.zip`，纯 `.dex`，或伪装/无扩展名的容器 —— 通过内容（PK / `dex\n` magic）识别，而非文件名；`identify()` 可在不加载的情况下进行探测 |
| APK 加载 | ~28 ms（惰性切片解析 + 加载时结构验证 —— 比 androguard 快约 100 倍；耗时随 APK 大小增加：Telegram 的 39 k 个类 / 5 个 dex 加载耗时约 120 ms） |
| 反编译 | DAD 质量的 Java 代码；逐方法反编译速度比 androguard 快 4.5 倍 |
| Multidex | 先到先得的重复类解析，确定性匹配 —— 与 ART/AOSP 一致，因此加壳工具造成的类冲突会反编译为实际运行的方法体 |
| 内存 | 在包含 39k 个类的应用上占用约 520 MB —— 可进程内嵌入，无需 JVM |
| 并行 | C++ 会释放 GIL → 可通过单个进程内实例实现真正的多线程反编译 |
| 搜索 | L1–L7（名称 / 字符串 / 注解 / 父类 / API 调用点 / xref）—— 比 androguard 快 3–6 倍 |
| AST | `decompile_method_ast` 返回完整的 androguard `dast.py` 嵌套 AST |
| LLM | `dexllm.tools` 目录 → MCP stdio server + FastAPI/SSE Web 后端 |
## 格式错误的 dex 验证（对比 ART `DexFileVerifier`）
dexllm 会处理对抗性输入，因此在核心解析之前，每个 dex 都会通过加载时结构验证器 ——
`VerifyDex` —— 进行处理。被拒绝的 dex 会抛出包含字节级原因
（`dk.verify_report()`）的异常；有效的 dex 不会受到影响。它是 AOSP ART
`DexFileVerifier` 的可读性极高的 1:1 移植，侧重于**崩溃安全**，而非执行可信度。
| 阶段 (ART `dex_file_verifier.cc`) | 对比 ART |
|---|---|
| `CheckHeader` / `CheckMap` | ✅ 一致 —— magic/版本/大小/字节序，节边界，映射顺序/对齐/必选项 |
| `CheckIntraSection` | ✅ 一致 —— string_data MUTF-8，id 索引，type_list，code_item，class_data，encoded_array · **⊕ 外加 `VerifyInsns`**（逐指令操作数边界检查，ART 将其保留在*runtime*方法验证器中，而非结构验证器中） |
| `CheckInterSection` | ✅ 一致 —— id 排序/唯一性，descriptor + 成员名称语法，class_def 语义（重复 / 自继承 / 定义者匹配） |
**特意未检查的内容** —— 与只读分析器无关的执行信任机制，或
超出结构范围的检查：adler32/SHA-1 校验和、指令*数据流*语义、annotations、
debug_info、call_site/method_handle、proto shorty-match、access-flag 位掩码，以及
偏移量→map-type 的交叉检查。
**已验证：** 干净的语料库 0 误拒 · 26/26 C++ 测试套件通过 · ASan 语料库 + 格式错误的 dex 模糊测试
**0 heap-overflow/UAF/SEGV**（在没有结构验证器的情况下，相同的模糊测试会导致 66/120 的用例发生段错误）。
验证器使加载时间增加约 58%（仍比 androguard 快约 100 倍）；反编译吞吐量不受影响。
## 对比 androguard 的基准测试
dexllm 将 androguard 的 DAD 反编译器移植到了 C++，因此该对比纯粹是关于运行时
（native 对比 Python）和输出一致性，**单线程、相同的 APK / 相同的方法**。
**APK：** `com.example.android.tvleanback.apk` — 4135 个类 · 500 个方法的反编译样本
（Ryzen 9 9950X，Python 3.13）：
| 操作 | dexllm | androguard | 加速比 |
|---|---|---|---|
| APK 加载（包含结构验证） | **27.8 ms** | 2.83 s | 102× |
| 反编译 — 方法 (500) | **28.4 ms** | 128.9 ms | 4.5× |
| └ 逐方法 | **0.06 ms** | 0.26 ms | 4.5× |
| 反编译 — 整个类 (200) | **77.6 ms** | 368.7 ms | 4.8× |
| 搜索：使用字符串 `"http"` 的方法 | **1.95 ms** | 8.28 ms | 4× |
| 搜索：`Log.d` 的调用点 | **0.27 ms** | 1.22 ms | 5× |
**对比 androguard 的输出一致性**（缩进归一化后）：方法字节级完全一致 **92.4 %** (462/500) ·
整个类的代码行重叠率 **94.0 %**。残余的差异属于语义等价（变量名
后缀），或者是 dexllm 输出了规范正确的 Java 代码而 androguard 出错的情况。
**并行反编译** — dexllm 在 `decompile_*` 期间释放了 GIL，因此线程可以在同一个共享实例上实现真正的
并行处理（androguard 根本无法使用线程）。对相同的 4135 个类进行的全 APK 反编译：
| dexllm | 实际耗时 | 加速比 |
|---|---|---|
| 顺序执行（1 线程） | 1.85 s | 1.0× |
| 16 线程（物理核心） | 178 ms | **10.3×** |
| 32 线程（SMT，共享实例） | 191 ms | 9.6× |
在接近物理核心数量时达到峰值；SMT 线程因调度器竞争而出现轻微退化。
端到端（并行反编译 + 加载）对比 androguard 单线程：**快约 59 倍**。
## 许可证
Apache-2.0。内置了引入的 [LuckyPray DexKit](https://github.com/LuckyPray/DexKit)
核心（遵循其自身的许可证）。
标签：DAST, Java反编译, MCP, 云安全监控, 云资产清单, 安卓安全, 恶意软件分析, 逆向工具, 逆向工程, 静态分析