**脚本**（auto-detects OS/arch）：```bash
curl -sSL https://raw.githubusercontent.com/JuneLeGency/dexfinder/main/install.sh | bash

**二进制文件**: 从 [Releases](https://github.com/JuneLeGency/dexfinder/releases) 下载。

## 快速开始```bash
# Show APK overview
dexfinder --dex-file app.apk --stats

# Find all calls to getDeviceId (IMEI)
dexfinder --dex-file app.apk --query "getDeviceId"

# Trace call chains as merged tree
dexfinder --dex-file app.apk --query "getDeviceId" --trace

# Trace as flat call stacks (Java crash style)
dexfinder --dex-file app.apk --query "getDeviceId" --trace --layout list

# Exact JNI signature query
dexfinder --dex-file app.apk \
  --query "Landroid/telephony/TelephonyManager;->getDeviceId()Ljava/lang/String;" \
  --trace --depth 8

# Hidden API detection
dexfinder --dex-file app.apk --api-flags hiddenapi-flags.csv

## 输出控制

三个独立的轴，可自由组合：```
--format  (text / json / model / html / sarif)    what to output
--layout  (tree / list)                           how to arrange traces
--style   (java / dex)                            how to display names
--color   (auto / always / never)                 terminal colors

`--scope=all`（默认值）等同 `callee` + `string`。默认排除 `caller` 方向，因为它回答的是截然不同的问题。当需要时，请显式使用 `--scope=caller` 或 `--scope=everything`。

**理解输出标签：**

| 标签 | 含义 |
|---|---|
| `[METHOD]` | 一个**被调用**的方法匹配你的查询（被调用者匹配）。缩进行为调用者。 |
| `[FIELD]` | 一个**被访问**的字段匹配你的查询。缩进行为访问者。 |
| `[CALLER→]` | 一个**调用方法**匹配你的查询。缩进行显示它正在调用的 API。 |
| `[STRING]` | 代码中的字符串常量匹配你的查询。缩进行为使用它的位置。 |
| `[STRING_TABLE]` | 字符串存在于 DEX 字符串表中，但在代码中没有 `const-string` 引用（可能位于注解中、被 R8 优化掉等）。 |

## 示例

### 1. 扫描 APK 统计信息```bash
dexfinder --dex-file app.apk --stats

Loaded 31 DEX file(s): 183913 classes, 1250566 method refs
Method references: 680610
Field references:  625572
String constants:  654353
Referenced types:  192586
Time: 3.9s

### 3. 跟踪调用链——树状视图```bash
dexfinder --dex-file app.apk \
  --query "Landroid/telephony/TelephonyManager;->getDeviceId()Ljava/lang/String;" \
  --trace --depth 5

android.telephony.TelephonyManager.getDeviceId()
└── com.example.aopsdk.TelephonyManager.getDeviceId(TelephonyManager.java)
    ├── com.example.session.PhoneInfo.getImei(PhoneInfo.java)
    ├── com.example.logging.ClientIdHelper.initClientId(ClientIdHelper.java)
    │   └── com.example.logging.ContextInfo.<init>(ContextInfo.java)
    │       ├── com.example.logging.LogStrategyManager.getInstance(LogStrategyManager.java)
    │       └── com.example.logging.LogContextImpl.<init>(LogContextImpl.java)
    ├── com.example.msp.DeviceInfo.k(DeviceInfo.java)
    │   └── com.example.msp.DeviceInfo.<init>(DeviceInfo.java)
    │       └── com.example.msp.DeviceInfo.getInstance(DeviceInfo.java)
    │           ├── com.example.msp.TidHelper.getIMEI(TidHelper.java)
    │           ├── com.example.msp.TidHelper.getIMSI(TidHelper.java)
    │           └── com.example.msp.DeviceCollector.collectData(DeviceCollector.java)
    └── com.example.weex.WXEnvironment.getDevId(WXEnvironment.java)
        └── com.example.weex.WXEnvironment.<clinit>(WXEnvironment.java)

### 5. 使用DEX签名样式进行跟踪```bash
dexfinder --dex-file app.apk --query "getDeviceId" --trace --depth 3 --style dex

Landroid/telephony/TelephonyManager;->getDeviceId()Ljava/lang/String;
└── TelephonyManager.getDeviceId(Landroid/telephony/TelephonyManager;)Ljava/lang/String;
    ├── PhoneInfo.getImei(Landroid/content/Context;)Ljava/lang/String;
    ├── ClientIdHelper.initClientId(Landroid/content/Context;)Ljava/lang/String;
    └── DeviceInfo.k(Landroid/content/Context;)V

```json
{
  "targets": [{
    "api": "android.telephony.TelephonyManager.getDeviceId()",
    "tree": {
      "method": "android.telephony.TelephonyManager.getDeviceId(TelephonyManager.java)",
      "callers": [
        { "method": "com.example.aopsdk.TelephonyManager.getDeviceId(TelephonyManager.java)",
          "callers": [
            { "method": "com.example.session.PhoneInfo.getImei(PhoneInfo.java)" },
            { "method": "com.example.logging.ClientIdHelper.initClientId(ClientIdHelper.java)" }
          ]}
      ]
    }
  }]
}

```json
{
  "targets": [{
    "api": "android.telephony.TelephonyManager.getDeviceId()",
    "chains": [
      ["com.example.session.PhoneInfo.getImei(PhoneInfo.java)",
       "com.example.aopsdk.TelephonyManager.getDeviceId(TelephonyManager.java)",
       "android.telephony.TelephonyManager.getDeviceId(TelephonyManager.java)"],
      ["com.example.logging.ClientIdHelper.initClientId(ClientIdHelper.java)",
       "com.example.aopsdk.TelephonyManager.getDeviceId(TelephonyManager.java)",
       "android.telephony.TelephonyManager.getDeviceId(TelephonyManager.java)"]
    ]
  }]
}

```json
{
  "target": "Landroid/telephony/TelephonyManager;->getDeviceId()Ljava/lang/String;",
  "chain": [
    { "method": { "dex_signature": "...", "class": "...", "name": "getImei",
                   "param_types": ["Landroid/content/Context;"], "return_type": "Ljava/lang/String;",
                   "java_readable": "com.example.session.PhoneInfo.getImei(...)" }},
    { "method": { "dex_signature": "...", "java_readable": "...TelephonyManager.getDeviceId(...)" }},
    { "method": { "dex_signature": "...", "java_readable": "...TelephonyManager.getDeviceId(...)" }}
  ],
  "depth": 2
}

**输出跟踪中反混淆后的名称：**```bash
# Tree trace with deobfuscated names
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt --trace --depth 3

com.example.kotlin.KotlinCases$$ExternalSyntheticLambda1.<init>(int)
└── com.example.TestEntry.runAllTests(TestEntry.java)
    └── com.example.MainActivity.onCreate(MainActivity.java)

**与其他标志的所有组合：**```bash
# Original name + trace as flat list
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt --trace --layout list

# Original name + DEX signature style
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt --trace --style dex

# Original name + JSON tree + show-obf
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt --show-obf --trace --format json

# Original name + reverse direction (what does this class call?)
dexfinder --dex-file app.apk --query "com.example.kotlin.KotlinCases" --mapping mapping.txt --scope caller

### 11. 搜索字符串常量 (content:// URIs, API密钥等)```bash
# Find content:// URIs in code
dexfinder --dex-file app.apk --query "content://com.android.contacts" --scope string

# Include strings only in DEX table (optimized out by R8, annotations, etc.)
dexfinder --dex-file app.apk --query "content://com.android.contacts" --scope everything

[STRING] "content://com.android.contacts/" (1 ref)
       Lcom/example/imageloader/BaseImageDownloader;->getStreamFromContent(Ljava/lang/String;)Ljava/io/InputStream;
[STRING_TABLE] "content://com.android.contacts" (in DEX string table, no code reference found)

### 13. 整合所有内容```bash
# Deobfuscated JSON tree of location API usage, filtered to your code
dexfinder --dex-file app.apk \
  --query "android.location.LocationManager#requestLocationUpdates" \
  --trace --depth 8 \
  --format json --layout tree --style java \
  --mapping mapping.txt --show-obf \
  --class-filter "Lcom/mycompany/"

在任何浏览器中打开 — 可折叠的调用树、搜索栏、深色主题。

### 15. SARIF for GitHub Code Scanning```bash
dexfinder --dex-file app.apk --api-flags hiddenapi-flags.csv --format sarif > results.sarif
# Upload to GitHub:
# gh api repos/OWNER/REPO/code-scanning/sarifs -f "[email protected]"

### 17. 使用 --fail-on 的 CI 门控```bash
# Fail CI if any blocked hidden APIs are used
dexfinder --dex-file app.apk --api-flags hiddenapi-flags.csv --fail-on blocked
# Exit code: 0 = clean, 2 = violations found

CLI flags 始终覆盖配置文件的值。

## 从源代码构建```bash
git clone https://github.com/JuneLeGency/dexfinder.git
cd dexfinder
go build -o dexfinder ./cmd/dexfinder/
go test ./...

**脚本安装** (自动检测系统):```bash
curl -sSL https://raw.githubusercontent.com/JuneLeGency/dexfinder/main/install.sh | bash

**二进制下载**: [Releases](https://github.com/JuneLeGency/dexfinder/releases)

## 快速开始```bash
# 查看 APK 概况
dexfinder --dex-file app.apk --stats

# 查找所有 getDeviceId 调用（获取 IMEI）
dexfinder --dex-file app.apk --query "getDeviceId"

# 追踪调用链（合并树形视图）
dexfinder --dex-file app.apk --query "getDeviceId" --trace

# 追踪调用链（展开为独立调用栈）
dexfinder --dex-file app.apk --query "getDeviceId" --trace --layout list

# 用精确 JNI 签名查询
dexfinder --dex-file app.apk \
  --query "Landroid/telephony/TelephonyManager;->getDeviceId()Ljava/lang/String;" \
  --trace --depth 8

### `--layout` 对比（配合 `--trace`）

**tree** — 合并共同路径，一棵树展示全貌：```
android.telephony.TelephonyManager.getDeviceId()
└── ...aopsdk...TelephonyManager.getDeviceId(TelephonyManager.java)
    ├── PhoneInfo.getImei(PhoneInfo.java)
    ├── ClientIdHelper.initClientId(ClientIdHelper.java)
    │   └── ContextInfo.<init>(ContextInfo.java)
    └── DeviceInfo.k(DeviceInfo.java)
        └── DeviceInfo.getInstance(DeviceInfo.java)
            ├── TidHelper.getIMEI(TidHelper.java)
            └── DeviceCollector.collectData(DeviceCollector.java)

### `--style` 对比

**java** (默认): `com.example.Foo.method(Foo.java)`
**dex**: `Foo.method(Ljava/lang/String;)V`

### JSON 输出```bash
# JSON 树
dexfinder --dex-file app.apk --query "getDeviceId" --trace --format json

# JSON 列表
dexfinder --dex-file app.apk --query "getDeviceId" --trace --format json --layout list

`--scope=all`（默认）= `callee` + `string`。`caller` 方向被故意排除在默认之外，因为它回答的是完全不同的问题。需要时用 `--scope=caller` 或 `--scope=everything` 显式启用。

**输出标签含义：**

| 标签 | 含义 |
|---|---|
| `[METHOD]` | 你搜的方法**被别人调用了**。缩进行是调用者。 |
| `[FIELD]` | 你搜的字段**被别人访问了**。缩进行是访问者。 |
| `[CALLER→]` | 你搜的方法名出现在某个**调用方**中，缩进行显示它调了什么 API。 |
| `[STRING]` | 代码中的字符串常量匹配。缩进行是使用该字符串的方法。 |
| `[STRING_TABLE]` | 字符串仅存在于 DEX 字符串表中，代码里没有 `const-string` 引用（可能在注解中、被 R8 优化掉等）。 |

## 更多用法

### 反混淆（--mapping）

加载 `--mapping` 后，**输入和输出**都支持原始（未混淆）名称。

**用原始名查询 → 自动转换为混淆名搜索 DEX：**```bash
# 用原始简短类名查（mapping 内部将 "KotlinCases" 转为 "LJ7;"）
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt

# 用原始 Java 全名查
dexfinder --dex-file app.apk --query "com.example.app.utils.Helper" --mapping mapping.txt

# 用混淆名查也正常工作
dexfinder --dex-file app.apk --query "LJ7;" --mapping mapping.txt

**同时显示混淆名和原始名：**```bash
dexfinder --dex-file app.apk --query "KotlinCases" --mapping mapping.txt --show-obf --trace

com.example.KotlinCases.fetchLocationAsync(KotlinCases.java)
└── com.example.KotlinCases$testCoroutines$3.invokeSuspend(KotlinCases.java)  [obf: G7.e]

**输入×输出矩阵：**

| 查询输入 | 无 mapping | `--mapping` | `--mapping --show-obf` |
|---|---|---|---|
| 混淆名 `LJ7;` | ✓ 混淆输出 | ✓ 反混淆输出 | ✓ 两者并列 |
| 原始简名 `KotlinCases` | ✗ 找不到 | ✓ 自动转换 + 反混淆输出 | ✓ 自动转换 + 两者并列 |
| 原始全名 `com.example...` | ✗ 找不到 | ✓ 自动转换 + 反混淆输出 | ✓ 自动转换 + 两者并列 |

### Hidden API 检测```bash
# 下载 CSV（一次性）
curl -o hiddenapi-flags.csv \
  https://dl.google.com/developers/android/baklava/non-sdk/hiddenapi-flags.csv

# 全量检测（直接链接 + 反射检测）
dexfinder --dex-file app.apk --api-flags hiddenapi-flags.csv

### 按包名过滤```bash
# 只扫描自己的代码
dexfinder --dex-file app.apk --query "getDeviceId" --class-filter "Lcom/mycompany/"

### HTML 报告```bash
dexfinder --dex-file app.apk --query "getDeviceId" --trace --format html --output report.html

### APK 版本对比```bash
dexfinder --dex-file new.apk --diff old.apk --query "getDeviceId"

+ 1 added method(s)
  + Lcom/new/Feature;->trackDevice()V

- 1 removed method(s)
  - Lcom/old/Legacy;->getIMEI()V

Summary: +1 added, -1 removed, ~0 changed

## 性能

Apple M 系列芯片，单线程：

| APK 大小 | DEX 数 | 类数 | 方法引用 | 扫描 | Hidden API |
|---|---|---|---|---|---|
| ~1 MB | 1 | ~2K | ~18K | **24ms** | — |
| ~10 MB | 2 | ~25K | ~100K | **335ms** | — |
| ~300 MB | 30+ | ~180K | ~1.2M | **3.9s** | **5.4s** |

与 veridex (C++) 在同一 ~300MB APK 上对比：
- veridex precise: **27s**（无法追踪 Binder/AIDL 反射）
- veridex imprecise: **>32 分钟**（笛卡尔积爆炸，被 kill）
- **dexfinder: 5.4s**（反向索引优化）

## 全部参数

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--dex-file` | APK/DEX/JAR 文件路径 **（必需）** | — |
| `--query` | 搜索关键字（Java / DEX/JNI / 简单名称） | — |
| `--trace` | 启用调用链追踪（需配合 `--query`） | `false` |
| `--depth` | 调用链最大深度 | `5` |
| `--layout` | 追踪布局: `tree`（合并树）或 `list`（展开列表） | `tree` |
| `--style` | 命名风格: `java`（可读）或 `dex`（JNI 签名） | `java` |
| `--format` | 输出格式: `text`、`json`、`model`、`html`、`sarif` | `text` |
| `--output` | 输出到文件而非 stdout | — |
| `--color` | 颜色模式: `auto`、`always`、`never` | `auto` |
| `--mapping` | ProGuard/R8 mapping.txt 路径 | — |
| `--show-obf` | 同时显示混淆名和反混淆名 | `false` |
| `--api-flags` | hiddenapi-flags.csv 路径 | — |
| `--class-filter` | 类描述符前缀过滤（逗号分隔） | — |
| `--exclude-api-lists` | 排除的 API 级别 | — |
| `--scope` | 搜索范围: `all`、`callee`、`caller`、`string`、`string-table`、`everything` | `all` |
| `--diff` | 对比另一个 APK/DEX，显示 API 差异 | — |
| `--fail-on` | 检测到指定级别 API 时返回非零退出码（CI 卡点） | — |
| `--stats` | 仅显示统计摘要 | `false` |
| `--version` | 显示版本号 | `false` |

### 配置文件

在项目根目录创建 `.dexfinder.yaml` 设置默认值：```yaml
mapping: ./build/outputs/mapping.txt
class-filter: "Lcom/mycompany/"
api-flags: ./hiddenapi-flags.csv
style: java
depth: 8
color: auto

## 许可证

Apache License 2.0