# apk-inspect

**Repository Path**: fiagainster/apk-inspect

## Basic Information

- **Project Name**: apk-inspect
- **Description**: 国内合规视角的 APK 批量静态初筛工具。按风险排序，每项告警带证据位置，输出 HTML/CSV 报告，支持 VT 查毒。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# apk-inspect — APK 批量初筛工具

拿到一堆来路不明的 APK，想知道哪些可疑、先看哪个？这个工具就是干这个的：
批量扫一遍，按风险分排好序，每一条发现都告诉你**为什么可疑、证据在哪**。

它只做**静态初筛**——不解压运行、不上传文件，适合研判前的分流。
它不追求 MobSF 那种大而全，专攻两件事：

1. **批量分流**：几十上百个包扫完自动按风险分排名，配合 VirusTotal 查毒快速缩小范围
2. **国内合规视角**：权限组合规则、第三方 SDK 指纹、涉黄涉赌关键词、IOC 情报提取（QQ/微信/电报/钱包地址）、并案关联

## 它能查出什么

| 检查项        | 说明                                                                 |
| ---------- | ------------------------------------------------------------------ |
| 权限与组件      | 申请了什么敏感权限、哪些组件暴露在外                                                 |
| 第三方 SDK    | 54 条国内常见 SDK 指纹（推送/统计/广告…）                                         |
| 硬编码密钥      | dex / assets / so 里写死的 AccessKey、私钥、JWT、内网地址                       |
| 加固识别       | 19 家加固厂商（360/梆梆/爱加密/腾讯乐固…），附脱壳建议                                   |
| 源码级问题      | 需 jadx：敏感 API 调用的具体位置（文件:行号）、WebView/SSL/弱加密缺陷                     |
| 数据外发确认     | 需 jadx：敏感数据读取点附近紧跟网络外发/动态加载调用时，升级为「敏感数据被外发」高置信发现，附 文件:行 → 文件:行 证据链 |
| IOC 情报     | URL / 域名 / IP / 手机号 / QQ / 微信 / 电报 / 加密钱包，多个样本共用即并案线索              |
| 违规关键词      | 涉黄 / 涉赌 / 诈骗引流词表，中英文都能命中                                           |
| 追踪器        | 内置 Exodus Privacy 428 条广告/统计 SDK 指纹                                |
| 签名证书       | v1/v2/v3 签名校验、证书主体/有效期/自签名（仿冒应用信号）                                 |
| VirusTotal | 可选：只查哈希不上传文件，合入 70 引擎检出结果                                          |

扫完输出：**汇总 CSV**（风险分排名）+ 明细 CSV + IOC 情报表 + **单文件 HTML 报告**（浏览器直接打开）+ JSON。结果按 APK 哈希缓存，重扫秒回。

## 快速开始

### 1. 准备环境

- **JDK 17+**（命令行输入 `java -version` 能看到 17 以上即可）
- **Maven 3.6+**（`mvn -v` 能跑就行）
- 可选：jadx 反编译器（不用它也能扫，只是少了源码级检查，见下文）

### 2. 构建

```bash
git clone https://gitee.com/fiagainster/apk-inspect.git
cd apk-inspect
mvn package
```

构建产物是 `target/apk-inspect-0.9.0.jar`，一个自包含的 fat jar，拿走单文件就能跑。

### 3.（推荐）配置 jadx，解锁源码级扫描

jadx 的二进制体积太大（约 90MB）不进仓库，需要手动放一次：

1. 到 https://github.com/skylot/jadx/releases 下载 **jadx-1.5.6** 的 zip
2. 解压后，把里面的 `lib/` 文件夹整个复制到本项目的 `tools/jadx/` 下
   （最终结构：`tools/jadx/lib/*.jar`，`bin/` 脚本仓库里已经有了）

放好就完事，工具会自动检测到它并开启源码级扫描，不需要配置任何路径。

### 4. 跑第一个扫描

```bash
# 命令行
java -jar target/apk-inspect-0.9.0.jar scan <APK文件或目录>

# 或者开图形界面（Windows 下直接双击 jar 也行）
java -jar target/apk-inspect-0.9.0.jar gui
```

扫完产物自动收进一个 **`apk-inspect-时间戳` 文件夹**（如 `apk-inspect-20260907-143105/`），里面有 6 个文件——**先看 HTML 报告**（`*.html`），浏览器打开就是排版好的研判视图；Excel 看 `apk-scan-summary.csv`。增量缓存放文件夹旁边的 `.apk-inspect-cache/`（固定位置，重扫秒回）。

大 APK 开源码扫描会慢（几十秒到几分钟），纯初筛分流可以加 `--no-source` 跳过反编译。

## 图形界面（推荐新手用）

```
java -jar target/apk-inspect-0.9.0.jar gui
```

- 把 APK 文件/文件夹**拖进窗口**即可开扫，支持 Ctrl 多选批量导入
- 左侧表格按风险分排名（绿→黄→橙→红徽标），点任意行右侧显示全部发现
- 扫完可点 **VT 查毒**（需要 API key，见下文）、**导出报告**（选个位置，自动建 `时间戳` 文件夹收纳全部产物，可选直接打开）、**标记误报**（登记一次，以后扫描自动排除）
- 规则目录点「打开目录」自动生成模板文件，改完下次扫描即生效
- 多次扫描结果累积在同一张表里，「清空结果」一键重置

## 命令行

```bash
# 扫描（目标可以是单个 APK，也可以是目录——递归收集所有 .apk）
java -jar target/apk-inspect-0.9.0.jar scan <APK或目录> [--out 汇总.csv] [--no-source] [--no-cache]

# 保留反编译源码到报告目录 sources/，方便人工复核
java -jar target/apk-inspect-0.9.0.jar scan <APK或目录> --keep-sources

# 版本回归对比：同一个应用新旧版本各扫一次，两份明细 CSV 相减
java -jar target/apk-inspect-0.9.0.jar diff 旧明细.csv 新明细.csv [--out 变化.csv]

# VirusTotal 哈希查毒（免费 key，自动限速）
java -jar target/apk-inspect-0.9.0.jar vt 汇总.csv [--out vt增强.csv]
```

常用开关说明：

- `--no-source`：关闭源码级扫描（批量初筛提速，实测能从十几分钟降到几分钟）
- `--no-cache`：关闭增量缓存（默认开启：改了规则或 APK 内容没变就不重扫）
- `--config <目录>`：指定规则目录（默认取 jar 旁边的 `config/`）

## 配置

### VirusTotal（可选，但很值得配）

到 https://www.virustotal.com 免费注册拿个 API key，然后三选一：

- 设置环境变量 `VT_API_KEY`
- 或把 key 写进 `config/vt-api-key.txt`（**别提交到仓库**，.gitignore 已排除）

免费额度 4 次/分钟、500 次/天，工具自动限速，同一哈希只查一次。
注意：**未检出 ≠ 安全**，只做分流参考。

### 自定义规则

规则目录默认是 jar 旁边的 `config/`，界面点「打开目录」会自动生成带注释的模板。
**缺哪个文件就用哪个的内置版本**，互不影响，常用的几个：

| 文件                                        | 作用                                                |
| ----------------------------------------- | ------------------------------------------------- |
| `rules.json`                              | 权限组合规则，如「READ_CONTACTS + INTERNET 同时申请 = 疑似上传通讯录」 |
| `keywords.json`                           | 违规内容关键词词表                                         |
| `secret-rules.json` / `source-rules.json` | 追加自定义密钥/源码特征                                      |
| `ignore-list.json`                        | 误报忽略清单（界面点「标记误报」会自动写入）                            |
| `exodus-trackers.json`                    | 追踪器指纹库（想更新可从 Exodus 官网下载）                         |
| `sdk-fingerprints.csv`                    | 第三方 SDK 指纹，一行一条：`包名前缀,名称,类别`                      |

规则文件都有对应模板和格式说明，照着改就行。

## 想改代码？

```bash
mvn test    # 122 个测试用例
```

- 加一种新的检测能力：实现 `core/Analyzer` 接口，在 `config/AnalyzerChainFactory` 里加一行注册即可，CLI 和 GUI 自动生效
- 关键解析器都在 `core/` 下：AXML（二进制 manifest）、ARSC（资源表）、dex 字符串池提取、ELF、zip 修复——对加壳/反分析样本有降级处理链，正常 apk-parser 解析失败不会直接放弃
- 更详细的迭代记录见 `../docs/apk-inspect-优化计划.md`
- 规则鲁棒性度量（`mec` 子命令）是独立课题，文档见 `../rule-robustness/`；本仓库作为其参照实现与数据来源保留

## 已知局限

- 只做静态分析，不运行 APK；加固包的源码扫描会自动跳过（反编译无效，但加固识别本身仍工作）
- 风险分是启发式加权，不是"恶意概率"——它告诉你**先看哪个**，结论要人下
- 敏感 API 命中需要人工核对（调用了不等于违规，比如崩溃上报收集设备 ID 可能是正常业务）
- 被彻底篡改 zip 结构的样本，只能登记"结构篡改"信号和 SHA-256
- VirusTotal 检出数和追踪器命中都不是恶意证据，只是研判信号

## 致谢

- [VirusTotal](https://www.virustotal.com) — 哈希查毒 API（查毒功能依赖其服务）
- [jadx](https://github.com/skylot/jadx)（GPL-3.0）— 反编译
- [Exodus Privacy](https://reports.exodus-privacy.eu.org)（CC0）— 追踪器指纹
- [APKLeaks](https://github.com/s1r1us/APKLeaks)（Apache-2.0）— 部分密钥特征规则移植