Daniel217-coder/Hybrid-Forensic-Investigation-Framework
GitHub: Daniel217-coder/Hybrid-Forensic-Investigation-Framework
HFIF 是一个混合取证调查框架，整合 Android 恶意软件静态/动态分析、运行时产物收集与可解释风险评分，生成面向案件的可追溯报告。
Stars: 0 | Forks: 0
# HFIF — 混合取证调查框架
**Android APK（静态 + 真机动态） • 运行时产物 • 可解释风险评分 • 可选 VT/YARA/Deepfake**
HFIF 是一个**面向案件**的取证框架，以可复现的工作流分析 Android 应用程序及相关证据。该项目围绕**单案件证据**、**派生的 JSON 产物**和 **HTML 报告**进行组织。
当前版本主要关注：
- 使用 Androguard 进行 **静态 APK 初步分析**
- 在**物理 Android 手机**上使用 **Frida Gadget + ADB 转发**进行**真机动态分析**
- **对分析师友好的 HTML 报告**
- 基于加权信号、协同条件和良性感知上限的**风险评分**
## 目录
- [1. 项目范围](#1-project-scope)
- [2. 仓库结构](#2-repository-structure)
- [3. 开发环境](#3-environment-used-in-development)
- [4. 已安装的工具](#4-tools-installed)
- [5. Python 依赖项](#5-python-dependencies)
- [6. 安装说明](#6-installation)
- [7. 核心命令](#7-core-commands)
- [8. 真机动态分析工作流](#8-real-device-dynamic-analysis-workflow)
- [9. 框架测试方法](#9-how-we-tested-the-framework)
- [10. 实践中使用的示例测试命令](#10-example-test-commands-used-in-practice)
- [11. 产物与报告](#11-artifacts-and-reports)
- [12. 评分模型](#12-scoring-model)
- [13. GUI — 测试应用程序](#13-gui--testing-the-application)
- [14. 故障排除](#14-troubleshooting)
- [15. 论文可复现性说明](#15-notes-for-dissertation-reproducibility)
- [16. 参考资料/工具](#16-references--tools)
## 1. 项目范围
HFIF 专为混合取证工作流而设计，可在同一案件中分析多种证据来源：
1. **APK 静态分析** — 清单、权限、组件、字符串、代码提示、证书和可解释的静态风险。
2. **APK 动态分析** — 在**真实的 Android 设备**（而非模拟器）上使用 **Frida Gadget** 和 **ADB** 捕获运行时行为。
3. **案件报告** — 模块特定的 HTML 报告和最终的综合案件报告。
4. **可选扩展** — YARA、VirusTotal 富化、内存相关产物 和 deepfake/媒体分析。
当前动态流水线的设计目标是保守评分：
- **良性应用程序应保持在 20 分以下**，除非存在强烈的高置信度证据。
- **恶意应用程序应超过 60–70 分**，当存在确凿的运行时指标或强组合时。
## 2. 仓库结构
该项目采用模块化和面向案件的结构：
```
src/
apk_static.py # static APK analysis
apk_dynamic.py # lightweight dynamic path (ADB-based)
frida_auto.py # real-device Frida Gadget runner
dyn_smoke_test.py # ADB sanity check for real device
case_manager.py # case creation / evidence / artifact helpers
report_html.py # module report generation
case_report.py # consolidated case report
env_report.py # environment/version summary
cybershadow_dyn.js # Frida JavaScript hooks
ui/app.py # desktop GUI
ui/deepfake_ui.py # optional deepfake UI
```
## 3. 开发环境
该框架主要在以下环境中开发和测试：
- **主机操作系统：** Windows 11
- **Python：** 3.10+
- **动态目标：** **通过 USB 和 ADB 连接的真实 Android 手机**
- **动态模型：** **嵌入在 APK 中的 Frida Gadget**，然后通过 **ADB 端口转发**进行附加
- **为何使用真机：** 这避免了仅存在于模拟器的许多产物，并更好地反映了现代 Android 应用程序的真实行为
重要实用说明：当前的动态工作流特意围绕**物理设备分析**构建，因为在非 root 的生产手机上，`frida-server` 的附加/生成通常不可靠。代码库通过启动 `frida_auto.py` 作为动态运行器并直接从 `src.main` 暴露 `apk-dynamic` 和 `run-apk --dynamic` 来反映这一点。
## 4. 已安装的工具
本节解释 **Python 之外安装了什么**、**为什么**以及**在哪里下载**。
### 4.1 必需的外部工具
#### ADB / Android SDK Platform-Tools
**作用：** 设备检测、USB 调试、启动应用、logcat 捕获、Frida Gadget 的端口转发。
**下载地址：**
- **选项 A（独立版 — 推荐）：** 从 Google 下载 *SDK Platform-Tools*：
https://developer.android.com/tools/releases/platform-tools —
将 ZIP 解压到任意位置（例如 `C:\platform-tools`）并将该文件夹添加到系统 `PATH` 中。
- **选项 B（通过 Android Studio）：** 如果已安装 Android Studio，工具位于：
`C:\Users\\AppData\Local\Android\Sdk\platform-tools\`
**验证：**
```
adb version
adb devices
```
#### Frida
**作用：** 从 Python 进行运行时代理插桩以及手动附加/调试命令。
**如何安装：** Frida 是一个 Python 包 — 无需单独下载：
```
pip install frida frida-tools
```
**验证：**
```
frida --version
python -c "import frida; print('frida', frida.__version__)"
```
#### Objection
**作用：** 在真机上安装之前，使用 Frida Gadget 对 APK 进行补丁。
**如何安装：**
```
pip install objection
```
**验证：**
```
objection version
```
#### Apktool
**作用：** APK 补丁/重构建（在重打包期间由 Objection 内部使用）。
**下载地址：** https://apktool.org/ (或 https://github.com/iBotPeaches/Apktool/releases)。
在 Windows 上：将 `apktool.bat` 和 `apktool.jar` 放在位于 `PATH` 中的文件夹内。
**验证：**
```
apktool --version
```
### 4.2 可选辅助工具
#### JADX
用于在验证/调试期间手动检查 APK 内容。
下载地址：https://github.com/skylot/jadx/releases
#### YARA
用于产物或提取内容的可选特征扫描。
Python 绑定通过 `pip install yara-python` 安装。
#### VirusTotal API
仅用于可选的富化。离线操作不需要。
如果需要 VT 富化，请在 https://www.virustotal.com/ 创建免费的 API 密钥并将其放入 `inputs/api_keys/.env` 中，格式如下：
```
VT_API_KEY=your_key_here
```
#### Volatility 3
计划用于未来的内存取证集成（可选）。
## 5. Python 依赖项
当前代码快照直接使用以下 Python 包：
### 核心 Python 包
- `androguard` — 静态 APK 解析和清单/代码提取
- `frida` 和 `frida-tools` — 运行时代理插桩支持
- `rich` — CLI 输出/控制台友好性
`env` 命令通过 `src/env_report.py` 报告 `androguard`、`customtkinter`、`tkinterweb` 和 `rich` 等包的版本。
### GUI 包
- `customtkinter`
- `tkinterweb`
### 可选 deepfake/媒体包
- `torch`
- `torchvision`
- `opencv-python`
- `pillow`
- `numpy`
### 说明
- 静态分析从 `androguard.core.apk` 导入 `APK`。
- 动态 Frida 分析在 `src/frida_auto.py` 中导入 `frida`。
- GUI 导入 `customtkinter` 和 `tkinterweb`。
- Deepfake UI 可选导入 `cv2`、`torch`、`torchvision` 和 `PIL`。
## 6. 安装说明
### 仓库中已包含的内容
在安装之前，了解克隆后您**已经拥有**什么会很有帮助：
| 项目 | 路径 | 说明 |
|------|------|------|
| 示例测试 APK | `cases/CASE_001/evidence/org.mozilla.fennec_fdroid_1490020.apk` | Firefox F-Droid（用于校准的良性应用） |
| YARA 演示规则 | `rules/yara/cybershadow_demo.yar` | 可直接使用 — GUI 默认使用此文件夹 |
| Frida JS hooks | `src/cybershadow_dyn.js` | 动态分析期间使用的 Frida 脚本 |
| 重打包工具 | `tools/repack_with_gadget.py` | 由 重打包+安装 按钮使用 |
| VT API 密钥模板 | `inputs/api_keys/.env.example` | 复制为 `.env` 并添加您的密钥（如果需要 VirusTotal 富化） |
**您需要自行提供的内容：**
- 您自己的待分析 APK 文件（或使用包含的示例）
- VirusTotal API 密钥（可选 — 仅用于 VT 富化）
- Frida Gadget `.so` 文件（仅当您需要重打包 APK 时 — 参见 [第 14.12 节](#1412-repack-fails--gadget-soxz-not-found-inputsfrida-gadgetso.xz)）
- 物理Android 手机或模拟器（仅用于动态/MemLite 分析）
### 6.1 克隆仓库并创建虚拟环境（推荐）
```
git clone https://github.com/Daniel217-coder/Hybrid-Forensic-Investigation-Framework.git
cd Hybrid-Forensic-Investigation-Framework
python -m venv .venv
```
### 6.2 激活环境
**Windows (PowerShell):**
```
.\.venv\Scripts\Activate.ps1
```
**Windows (CMD):**
```
.venv\Scripts\activate.bat
```
**Linux/macOS:**
```
source .venv/bin/activate
```
### 6.3 一次性安装所有 Python 依赖项
最简单的方法 — 安装所有内容（静态、动态、GUI、deepfake、YARA）：
```
pip install -r requirements.txt
```
此命令安装：`androguard`、`frida`、`yara-python`、`customtkinter`、`tkinterweb`、`torch`、`torchvision`、`opencv-python`、`pillow`、`numpy`、`rich`、`fastapi`、`uvicorn`、`pydantic`、`python-dotenv`。
### 6.4 （替代方案）手动安装核心包
```
pip install androguard rich frida frida-tools fastapi uvicorn pydantic python-dotenv
```
### 6.5 （替代方案）单独安装 GUI 包
```
pip install customtkinter tkinterweb
```
### 6.6 （替代方案）单独安装 deepfake/媒体包
```
pip install torch torchvision opencv-python pillow numpy
```
### 6.7 安装 Objection 以进行 APK 补丁（动态分析需要）
```
pip install objection
```
### 6.8 安装/准备 Android platform tools（动态分析需要）
确保 `adb` 可以通过 PATH 或 `ADB_PATH` 使用。
**Windows PowerShell 示例：**
```
$env:ADB_PATH="C:\Users\\AppData\Local\Android\Sdk\platform-tools\adb.exe"
$env:PATH += ";C:\Users\\AppData\Local\Android\Sdk\platform-tools"
```
### 6.9 验证环境
安装后，运行这两个命令确认一切正常：
```
python -m src.main env
python -m src.dyn_smoke_test
```
`env` 的预期输出：
```
{
"python": "3.12.x ...",
"packages": {
"androguard": "4.x.x",
"customtkinter": "5.x.x",
"tkinterweb": "4.x.x",
"rich": "14.x.x"
}
}
```
## 7. 核心命令
命令行入口点是 `src.main`。当前的 CLI 暴露了案件管理、静态分析、动态分析、报告生成和环境报告。
显示所有命令：
```
python -m src.main --help
```
### 7.1 案件管理
创建新案件：
```
python -m src.main new-case --id CASE_001 --base cases
```
手动添加证据：
```
python -m src.main add-evidence --case cases/CASE_001 --file path/to/app.apk --type apk
```
### 7.2 静态 APK 分析
```
python -m src.main apk-static --case cases/CASE_001 --apk path/to/app.apk --tag run1 --verbose
```
### 7.3 动态 APK 分析（真机）
```
python -m src.main apk-dynamic \
--case cases/CASE_001 \
--package com.example.app \
--tag dyn1 \
--serial \
--capture 90 \
--preflight 30 \
--drive monkey \
--monkey-events 1200 \
--throttle-ms 90 \
--endpoint 127.0.0.1:27042 \
--gadget-name Gadget \
--script src/cybershadow_dyn.js
```
### 7.4 一键式流水线
这会运行静态分析、可选的动态分析并生成案件报告。
```
python -m src.main run-apk \
--case cases/CASE_001 \
--apk path/to/app.apk \
--tag run1 \
--dynamic \
--serial \
--capture 90 \
--drive monkey
```
### 7.5 报告
```
python -m src.main report-html --case cases/CASE_001
python -m src.main case-report --case cases/CASE_001 --risk-mode latest
```
### 7.6 计算最终风险（聚合所有模块）
这将案件中的所有产物（静态、动态、YARA、MemLite、VT）聚合为单一风险分数：
```
python -m src.main risk --case cases/CASE_001 --tag run1
```
在 GUI 中，**计算最终风险** 按钮会自动从 Tag 字段发送标签。
### 7.7 环境/冒烟测试
```
python -m src.main env
python -m src.dyn_smoke_test
```
### 7.8 本地 API（用于 GUI/设备编排）
GUI 和多项功能（VT 富化、设备发现、重打包/安装工作流）通过 **本地 FastAPI 后端** 通信。GUI 和 API 是 **两个独立的进程** — 两者必须同时运行。
**启动 API 服务器（终端 1）：**
```
python -m uvicorn src.api_local:app --host 127.0.0.1 --port 8000
```
启动后，API 可用于：
- **Swagger UI（交互式文档）：** http://127.0.0.1:8000/docs
- **健康检查：** http://127.0.0.1:8000/health
**可用的 API 端点：**
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/health` | 服务器健康检查 |
| GET | `/env` | Python 环境/版本 |
| GET | `/devices` | 列出已连接的 ADB 设备 |
| POST | `/cases` | 创建新案件 |
| POST | `/run/static` | 运行静态 APK 分析（异步作业） |
| POST | `/run/dynamic_adb` | 运行仅 ADB 动态分析（异步作业） |
| POST | `/run/dynamic_frida` | 运行 Frida 动态分析（异步作业） |
| POST | `/run/repack_install` | 使用 Gadget 重打包 APK + 安装（异步作业） |
| POST | `/apk/check_repack` | 检查 APK 是否已包含 Frida Gadget |
| POST | `/apk/install` | 通过 ADB 安装 APK |
| POST | `/apk/uninstall` | 通过 ADB 卸载包 |
| GET | `/jobs` | 列出所有作业 |
| GET | `/jobs/{job_id}` | 获取特定作业的状态 |
| POST | `/vt/enrich` | VirusTotal 富化（需要 VT_API_KEY）**启动 GUI（终端 2）：**
```
python -m src.ui.app
```
## 8. 真机动态分析工作流
这是当前项目的**推荐工作流**。
### 步骤 1 — 连接设备
启用：
- 开发者选项
- USB 调试
然后验证：
```
adb devices
```
输出示例：
```
List of devices attached
emulator-5554 device ← this is an emulator
R5CR1234567 device ← this is a physical phone (Samsung, Pixel, etc.)
```
**第一列是 ``** — 这是您在所有要求 `--serial` 的命令中复制和使用的值。
例如，如果 `adb devices` 显示 `emulator-5554`，那么您的命令将变为：
```
python -m src.main apk-dynamic --serial emulator-5554 ...
```
### 步骤 2 — 使用 Frida Gadget 对 APK 打补丁
使用 Objection 的示例：
```
objection patchapk --source path/to/app.apk --architecture arm64-v8a
```
然后安装打补丁后的 APK：
```
adb install -r path/to/patched.apk
```
### 步骤 3 — 通过 HFIF 运行动态分析
```
python -m src.main apk-dynamic --case cases/CASE_001 --package com.example.app --tag dyn1 --serial
```
### 步骤 4 — 调试时的手动回退
如果您想手动测试 Gadget 路径：
```
adb -s forward --remove-all
adb -s forward tcp:27042 tcp:27042
adb -s forward tcp:27043 tcp:27043
adb -s shell "monkey -p com.example.app -c android.intent.category.LAUNCHER 1"
frida -H 127.0.0.1:27042 -n Gadget -l src/cybershadow_dyn.js
```
### 动态运行器的实际行为
当前的真机动态运行器：
- 为端口 `27042` 和 `27043` 重新应用 ADB 转发
- 清除并捕获 `logcat`
- 启动应用
- 等待 Gadget 监听器可用
- 通过 Frida 附加到 Gadget
- 可选地使用 `monkey` 驱动应用
- 监控运行时/网络事件
- 对观察到的行为进行评分
- 保存 JSON 产物并更新案件报告
## 9. 框架测试方法
本节用于论文可复现性。
### 9.1 静态模块验证
通过在 APK 样本上运行 `apk-static` 并验证以下内容来验证静态模块：
- manifest 解析
- 权限提取
- 可疑组件导出检测
- 代码提示提取
- 评分解释
- 产物/报告生成
### 9.2 真机动态验证
动态分析在**通过 ADB 连接的物理 Android 设备**上进行测试，而非模拟器。这一点很重要，因为论文特意从基于模拟器的执行转移，以减少反分析产物并提高真实性。
动态验证过程包括：
1. 通过 ADB 连接手机，
2. 使用冒烟测试验证连接性，
3. 使用 Frida Gadget 对 APK 打补丁，
4. 安装打补丁后的 APK，
5. 启动应用，
6. 通过转发的本地端口附加，
7. 使用受控的 `monkey` 事件刺激 UI，
8. 收集 Frida 事件、logcat 输出和轻量级网络观察，
9. 保存 JSON 产物和综合 HTML 报告。
### 9.3 评分校准实验
最重要的动态实验集中在**误报减少**上。
校准下的评分策略是：
- **良性应用程序应保持在 20 分以下**，当仅观察到弱/正常行为时，
- **恶意软件/广告软件应超过 60–70 分**，当出现强烈指标或可疑组合时，
- **单独的网络活动不得推高良性分数**。
### 9.4 论文评估数据集
在论文实验中，框架在 Android 应用程序集上进行了评估，包括：
- **1100 个良性应用**，以及
- **1100 个广告软件/恶意应用**
对于动态测试，数据集在物理设备上于**时间受限的刺激**下执行。
在校准期间讨论的良性基线应用程序示例包括常见的日常应用，例如：
- Calculator
- Facebook
- WhatsApp（官方）
这些基线应用很重要，因为评分目标明确是将良性样本保持在高风险范围之外。
### 9.5 实验中使用的可选外部基线
作为比较，VirusTotal 多数投票式查找也被用作**外部基线**，而非主要的离线检测器。
## 10. 实践中使用的示例测试命令
以下是验证和论文实验期间使用的代表性命令。
### 10.1 环境健全性检查
```
python -m src.main env
python -m src.dyn_smoke_test
adb devices
```
### 10.2 仅静态测试
```
python -m src.main new-case --id CASE_STATIC_001 --base cases
python -m src.main apk-static --case cases/CASE_STATIC_001 --apk datasets/benign/app1.apk --tag benign_001 --verbose
python -m src.main case-report --case cases/CASE_STATIC_001 --risk-mode latest
```
### 10.3 真机上的动态测试
```
python -m src.main new-case --id CASE_DYN_001 --base cases
python -m src.main apk-dynamic --case cases/CASE_DYN_001 --package com.example.target --tag dyn1 --serial --capture 90 --preflight 30 --drive monkey --monkey-events 1200 --throttle-ms 90
python -m src.main case-report --case cases/CASE_DYN_001 --risk-mode latest
```
### 10.4 完整流水线测试
```
python -m src.main run-apk --case cases/CASE_PIPE_001 --apk datasets/adware/sample1.apk --tag adware_001 --dynamic --serial --capture 90 --drive monkey
```
### 10.5 手动 Frida Gadget 检查
```
adb -s forward --remove-all
adb -s forward tcp:27042 tcp:27042
adb -s forward tcp:27043 tcp:27043
frida -H 127.0.0.1:27042 -n Gadget -l src/cybershadow_dyn.js
```
### 10.6 批处理式论文运行
在更广泛的论文工作流中，重复的数据集运行是通过 PowerShell 自动化的。典型的模式是：
```
python -m src.main run-apk --case cases/CASE_xxx --apk --tag --dynamic --serial
```
如果您维护了单独的批处理运行器（如 `run_dataset.ps1`），请在此处将其记录为迭代 benign 和 adware 文件夹并调用上述核心 HFIF 命令的包装器。
## 11. 产物与报告
HFIF 按案件存储所有内容：
```
cases/CASE_001/
├── case.json
├── evidence/
├── artifacts/
│ ├── apk_static__.json
│ ├── apk_dynamic____.json
│ └── other optional artifacts
├── reports/
├── module HTML reports
└── case__CASE_001.html
```
### 存储内容
- **evidence/** — 原始添加的文件
- **artifacts/** — 分析模块的 JSON 输出
- **reports/** — 面向分析师的 HTML 报告
## 12. 评分模型
HFIF 使用具有协同和良性感知上限的可解释加权评分。
概念上：
```
R_raw = min(100, R0 + Σ(w_i * s_i) + Σ(b_j * c_j))
if malicious_unlock == 0:
R = min(R_raw, 19)
else:
R = R_raw
```
### 实际解释
- **软信号** 接收低权重。
- **硬信号** 接收强权重。
- **可疑组合** 接收额外提升。
- 如果不存在硬解锁触发器，最终分数将被上限限制在 20 以下，以保护良性应用程序免受误报。
### 动态评分意图
校准期间使用的策略逻辑示例：
- 单独的网络存在：非常低的权重
- SMS 访问：硬触发器
- 进程执行：硬触发器
- 动态代码加载：硬触发器
- 网络 + SMS：严重组合
- 网络 + exec/dynamic-load：可疑组合
### 严重性分级
- **0–34：** LOW（低）
- **35–59：** MEDIUM（中）
- **60–79：** HIGH（高）
- **80–100：** CRITICAL（严重）
### GUI/UI 分级
- **<20：** 绿色
- **<50：** 黄色
- **<75：** 橙色
- **>=75：** 红色
## 13. GUI — 测试应用程序
测试 HFIF 的主要方式是通过**桌面 GUI**（`src/ui/app.py`），同时并行运行**本地 API 服务器**（`src/api_local.py`）。大多数分析命令通过 GUI 按钮触发，结果在内置报告查看器中查看。
### 13.1 前置条件
```
pip install customtkinter tkinterweb
```
（已包含在 `requirements.txt` 中。）
### 13.2 如何启动（两个终端）
您始终需要**两个并排打开的终端**：
**终端 1 — 启动本地 API 服务器：**
```
python -m uvicorn src.api_local:app --host 127.0.0.1 --port 8000
```
等待直到您看到 `Uvicorn running on http://127.0.0.1:8000`。
**终端 2 — 启动 GUI：**
```
python -m src.ui.app
```
### 13.3 GUI 布局概览
窗口标题为 **CYBERSHADOW - Forensic Analysis Hub**（暗色主题）。它有两个面板：
**左侧面板 — 4 个控制选项卡：**
| 选项卡 | 用途 |
|-----|---------|
| **APK Analyzer** | 静态分析、YARA、MemLite、完整流水线、VT 富化、最终风险、报告 |
| **Dynamic (Frida)** | 在真机或模拟器上进行 Frida Gadget 动态分析 |
| **Deepfake - Image** | 单图像 deepfake 检测 |
| **Deepfake - Video** | 视频逐帧 deepfake 分析 |
**右侧面板 — 3 个输出选项卡：**
| 选项卡 | 显示内容 |
|-----|-------------|
| **Console Log** | 实时 CLI 输出（暗背景上的绿色文本） |
| **Quick Summary** | 解析的分数、严重性、产物路径、关键发现 |
| **Report Viewer** | 内置 HTML 查看器，带有按钮：Load Case Report（加载案件报告）、Load Selected Artifact Report（加载选定的产物报告）、Load Latest APK Report（加载最新的 APK 报告）、Open Reports Folder（打开报告文件夹）、Open Artifacts Folder（打开产物文件夹） |
**顶部栏：** 进度条 + **Score**（分数）徽章 + **Severity**（严重性）徽章（在分析运行时实时更新）。
### 13.4 APK Analyzer 选项卡 — 所有按钮说明
这是主选项卡。顶部的字段是：
| 字段 | 填写内容 | 示例 |
|-------|----------------|---------|
| **Case Folder** | 案件目录的路径（如果缺失则自动创建） | `.\cases\CASE_001` |
| **Case Verdict Mode** | 如何在多次运行中聚合风险 | `latest` / `max` / `mean` |
| **APK File** | 待分析的 `.apk` 文件路径 | `C:\Downloads\app.apk` |
| **Tag** | 此分析运行的短标签 | `run1` |
| **YARA Rules** | 包含 `.yar` 规则文件的文件夹（默认：`.\rules\yara`） | `.\rules\yara` |
| **ADB Serial (MemLite)** | 用于内存相关捕获的设备序列号 | `emulator-5554` |
| **Package override (MemLite)** | 覆盖 MemLite 的包名 | `com.example.app` |
复选框：
- **Include YARA (full pipeline)** — 默认选中
- **Include MemLite (full pipeline)** — 默认选中
**第 1 行 — 主操作按钮：**
| 按钮 | 功能 |
|--------|-------------|
| **RUN FULL PIPELINE** | 按顺序运行所有内容：静态分析 → YARA 扫描（如果选中）→ MemLite（如果选中）→ 生成 APK 报告 → 生成案件报告 → 计算最终风险。这是**一键完成分析**。 |
| **STOP** | 停止正在运行的分析。 |
**第 2 行 — 单独模块按钮（一次运行一个）：**
| 按钮 | 功能 |
|--------|-------------|
| **Run Static Only** | 仅运行静态 APK 分析（权限、清单、代码提示、评分）。 |
| **Run YARA Only** | 仅对案件产物运行 YARA 特征扫描。 |
| **Run MemLite Only** | 仅运行 MemLite（通过 ADB 从设备捕获内存相关产物）。 |
| **Compute Final Risk** | 将所有现有产物（静态、动态、YARA、MemLite）聚合为单一风险分数并生成最终案件报告。 |
**第 3 行 — APK 管理 + VT：**
| 按钮 | 功能 |
|--------|-------------|
| **Repack + Install (keep)** | 使用 Frida Gadget 重打包 APK 并将其安装在设备上（通过 API）。 |
| **Uninstall** | 从设备卸载目标包（通过 API）。 |
| **VirusTotal Enrich** | 将 APK 哈希发送到 VirusTotal 并保存检测结果（需要 `.env` 中的 `VT_API_KEY`）。 |
**底部：**
| 按钮 | 功能 |
|--------|-------------|
| **LOAD REPORT INTO VIEWER** | 在内置的 Report Viewer 选项卡中打开生成的 HTML 报告。 |
按钮下方有一个 **Artifacts (generated)** 部分，列出了案件中的所有 JSON 产物。您可以选择一个以在 Quick Summary 中预览它或加载其关联的报告。
### 13.5 Dynamic (Frida) 选项卡 — 所有字段和按钮
| 字段 | 填写内容 | 默认值 |
|-------|----------------|---------|
| **Package Name** | 目标应用的 Android 包名 | (空) |
| **Dynamic Tag** | 此动态运行的标签 | `dyn` |
| **Preflight (sec)** | 应用启动后附加 Frida 前等待的秒数 | `30` |
| **Capture (sec)** | 监控运行时行为的时长 | `90` |
| **Drive** | 在捕获期间如何刺激应用 | `monkey+allow` |
| **Monkey events** | 随机 UI 事件的数量 | `2500` |
| **Throttle (ms)** | monkey 事件之间的延迟 | `80` |
| **Seed URL** | 分析期间在应用中打开的可选 URL | `https://example.com` |
| **Target device** | 通过 API 从 `adb devices` 填充的下拉列表 | (自动检测) |
| **Frida JS Script** | Frida hooks 脚本的路径 | `src\cybershadow_dyn.js` |
**按钮：**
| 按钮 | 功能 |
|--------|-------------|
| **RUN DYNAMIC (FRIDA)** | 运行完整的 Frida Gadget 动态分析：ADB forward → 启动应用 → 附加 Frida → monkey 刺激 → 收集事件 → 评分 → 生成报告。 |
| **STOP** | 停止正在运行的动态分析。 |
| **Refresh devices** | 查询 API (`/devices`) 并刷新设备下拉列表。 |
### 13.6 如何测试应用程序 — 推荐工作流
这是通过 GUI 测试 HFIF 的分步过程：
#### 步骤 1 — 启动 API + GUI
打开两个终端。在 1 中：
```
python -m uvicorn src.api_local:app --host 127.0.0.1 --port 8000
```
在终端 2 中：
```
python -m src.ui.app
```
#### 步骤 2 — 运行 Run Static Only（APK Analyzer 选项卡）
1. 将 **Case Folder** 设置为 `.\cases\CASE_001`（或任何名称）。
2. 点击 **Browse APK** 并选择您的 `.apk` 文件。
3. 将 **Tag** 设置为类似 `static_run1` 的内容。
4. 点击 **Run Static Only**。
5. 观察 **Console Log** 选项卡 — 完成后，顶部的 **Score** 和 **Severity** 徽章会更新。
6. 产物 `apk_static__static_run1.json` 出现在 Artifacts 列表中。
#### 步骤 3 — 运行 Run YARA Only
1. **YARA Rules** 字段默认为 `.\rules\yara` — 此文件夹已存在于仓库中，并包含 `cybershadow_demo.yar`（用于测试的演示规则）。
2. 点击 **Run YARA Only**。
3. 案件中会创建一个 `yara__*.json` 产物。
#### 步骤 4 — 运行 Run MemLite Only
1. 如果您连接了设备/模拟器，在 **ADB Serial (MemLite)** 中输入其序列号。
2. 如果 APK 包名与检测到的不同，可选择输入 **Package override**。
3. 点击 **Run MemLite Only**。
4. 将创建一个 `memlite__*.json` 产物。
#### 步骤 5 — 单独运行动态分析（Dynamic 选项卡）
1. 切换到 **Dynamic (Frida)** 选项卡。
2. 点击 **Refresh devices** — 您的设备/模拟器应出现在下拉列表中。
3. 输入 **Package Name**（例如 `com.example.app`）。
4. 确保 APK 已使用 Frida Gadget 打补丁并安装在设备上（如果需要，使用 APK Analyzer 选项卡中的 **Repack + Install**）。
5. 点击 **RUN DYNAMIC (FRIDA)**。
6. 运行器将：转发 ADB 端口 → 启动应用 → 等待 Gadget → 附加 Frida → 使用 monkey 刺激 → 收集事件 → 评分 → 保存产物。
7. 将创建一个 `apk_dynamic__dyn__*.json` 产物。
#### 步骤 6 — 运行 Full Pipeline（一次性运行）
您可以点击 APK Analyzer 选项卡中的 **RUN FULL PIPELINE**，而不是单独执行步骤 2–5。这会按顺序运行所有内容：
1. 静态分析
2. YARA 扫描（如果复选框被选中）
3. MemLite（如果复选框被选中）
4. APK HTML 报告生成
5. 案件 HTML 报告生成
6. 最终风险计算
#### 步骤 7 — 计算最终风险
在所有模块运行完毕（静态、动态、YARA、MemLite）后，点击 **Compute Final Risk**。这将：
- 读取案件中的所有产物
- 使用选定的 **Case Verdict Mode**（`latest` / `max` / `mean`）聚合它们
- 生成一个 `risk_aggregate__*.json` 产物
- 生成最终的综合案件报告 HTML
#### 步骤 8 — 查看报告
1. 在 **Report Viewer** 选项卡（右侧面板）中，点击 **Load Case Report** 以查看综合报告。
2. 或点击 **Load Latest APK Report** 查看最新的模块报告。
3. 或者在 Artifacts 列表中选择一个特定的产物，然后点击 **Load Selected Artifact Report**。
4. 使用 **Open Reports Folder** 或 **Open Artifacts Folder** 在资源管理器中直接浏览生成的文件。
最终案件报告显示：
- 总体风险分数和严重性级别
- 每个模块的分数（静态、动态、YARA、MemLite）
- 带有解释和权重的详细发现
- 触发或未触发的协同条件
#### 典型的完整测试会话
```
Terminal 1: python -m uvicorn src.api_local:app --host 127.0.0.1 --port 8000
Terminal 2: python -m src.ui.app
In GUI (APK Analyzer tab):
1. Case Folder: .\cases\TEST_APP
2. Browse APK: select your test APK
3. Tag: v1
4. Click "Run Static Only" → wait for Score badge to update
5. Click "Run YARA Only" → yara artifact created
6. Click "Run MemLite Only" → memlite artifact created
7. Click "Compute Final Risk" → risk_aggregate artifact + case report
In GUI (Dynamic tab):
8. Refresh devices → select emulator or phone
9. Package Name: com.example.app
10. Click "RUN DYNAMIC (FRIDA)" → dynamic artifact created
Back in APK Analyzer tab:
11. Click "Compute Final Risk" → now includes dynamic results too
In GUI (Report Viewer tab):
12. Click "Load Case Report" → view the final consolidated report
```
### 13.7 Swagger UI — 无需 GUI 测试 API
如果您更喜欢直接测试 API 端点，请在启动 API 服务器后在浏览器中打开 http://127.0.0.1:8000/docs。Swagger 提供了一个交互式界面，您可以在其中：
- 创建案件 (`POST /cases`)
- 运行静态/动态分析 (`POST /run/static`、`POST /run/dynamic_adb`、`POST /run/dynamic_frida`)
- 检查作业状态 (`GET /jobs/{job_id}`)
- 列出已连接的设备 (`GET /devices`)
- 重打包 + 安装 APK (`POST /run/repack_install`)
- VT 富化 (`POST /vt/enrich`)
## 14. 故障排除
这是真机分析最重要的实用部分。
### 14.1 找不到 `adb`
**症状：**
- `adb: command not found`
- 冒烟测试立即失败
- 动态分析在设备检测前退出
**修复：**
- 安装 Android Platform-Tools
- 将 `adb` 添加到 PATH
- 或设置 `ADB_PATH`
**PowerShell 示例：**
```
$env:ADB_PATH="C:\Users\\AppData\Local\Android\Sdk\platform-tools\adb.exe"
$env:PATH += ";C:\Users\\AppData\Local\Android\Sdk\platform-tools"
```
验证：
```
adb version
python -m src.dyn_smoke_test
```
### 14.2 设备在 `adb devices` 中不可见
**症状：**
- 未列出设备
- 动态运行显示未找到设备
**修复：**
1. 重新连接 USB 电缆，
2. 启用 USB 调试，
3. 在手机上接受 RSA 提示，
4. 重启服务器：
```
adb kill-server
adb start-server
adb devices
```
### 14.3 设备显示 `offline`
**症状：**
- `adb devices` 将手机列为 `offline`
- 动态运行器重试但没有进展
**修复：**
```
adb kill-server
adb start-server
adb devices
```
然后重新连接手机并解锁屏幕。
### 14.4 PowerShell 执行策略阻止 venv 激活
**症状：**
- 无法加载 `Activate.ps1`
**修复：**
```
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
```
### 14.5 `frida module missing`
**症状：**
- 动态运行器报告缺少 `frida` Python 模块
**修复：**
```
pip install frida frida-tools
```
验证：
```
python -c "import frida; print('frida ok')"
frida --version
```
### 14.6 Gadget 不可达 / 监听器未检测到
**症状：**
- 动态分析报告 Gadget 未就绪
- 端口 `27042` 未监听
- Frida 附加失败
**修复：**
1. 确认 APK 已使用 Gadget 打补丁，
2. 安装打补丁后的 APK，而非原始 APK，
3. 手动启动应用一次，
4. 重新应用端口转发：
```
adb -s forward --remove-all
adb -s forward tcp:27042 tcp:27042
adb -s forward tcp:27043 tcp:27043
```
5. 手动测试：
```
frida -H 127.0.0.1:27042 -n Gadget -l src/cybershadow_dyn.js
```
### 14.7 `objection patchapk` 失败
**常见原因：**
- Objection 版本过时
- 缺少 Apktool
- 不支持的 APK 打包/保护
**修复：**
```
pip install -U objection
apktool --version
```
如果补丁仍然失败：
- 确认 APK 未损坏，
- 检查 ABI 选择（大多数现代手机为 `arm64-v8a`），
- 检查控制台输出的签名/重构建错误。
### 14.8 Android 13+ 上列出包时出现 `SecurityException`
某些版本限制跨用户/配置文件列出包。包含的冒烟测试已通过尝试当前用户然后回退到用户 `0` 来处理此问题。
如果您手动调试，建议使用：
```
adb shell am get-current-user
adb shell pm list packages --user 0
```
### 14.9 应用启动但动态捕获为空
**可能的原因：**
- 包名错误
- Frida 脚本路径错误
- 打补丁的应用未安装
- Gadget 从未启动
- 应用立即崩溃
**检查：**
```
adb shell monkey -p com.example.app -c android.intent.category.LAUNCHER 1
adb logcat
frida -H 127.0.0.1:27042 -n Gadget -l src/cybershadow_dyn.js
```
同时验证 `src/cybershadow_dyn.js` 是传递给运行器的脚本。
### 14.10 打补丁后应用启动时崩溃
**可能的原因：**
- 重打包引入的不兼容性，
- 签名不匹配，
- 反篡改或保护器保护，
- 原生库/运行时不匹配。
**修复：**
- 重新安装前卸载以前的版本，
- 使用正确的架构再次打补丁，
- 检查 `adb logcat` 以获取真正的异常，
- 先在没有 HFIF 的情况下验证应用以确认它可以启动。
### 14.11 VT 富化失败 — "No connection could be made" (WinError 10061)
**症状：**
```
[ERROR] VirusTotal enrich failed:
```
**原因：**
GUI 将 `POST /vt/enrich` 发送到 `http://127.0.0.1:8000`，但本地 FastAPI 后端未运行。GUI 和 API 服务器是 **两个独立的进程** — 两者必须同时运行。
**修复：**
在使用任何调用后端的 GUI 功能之前，在单独的终端中启动 API 服务器：
```
python -m uvicorn src.api_local:app --host 127.0.0.1 --port 8000
```
然后重新启动 GUI 或重试操作。
### 14.12 重打包失败 — "Gadget .so/.xz not found: inputs\frida-gadget.so.xz"
**症状：**
```
FileNotFoundError: Gadget .so/.xz not found: inputs\frida-gadget.so.xz
```
**原因：**
Frida Gadget 共享库不包含在仓库中，必须单独下载。重打包工具期望它在 `inputs/frida-gadget.so.xz`。
**修复：**
1. 检查您的设备/模拟器 ABI：
```
adb shell getprop ro.product.cpu.abi
```
2. 从 Frida GitHub 发布页面（`https://github.com/frida/frida/releases`）下载匹配的 gadget：
| ABI | 文件 |
|-----|------|
| `arm64-v8a` | `frida-gadget--android-arm64.so.xz` |
| `armeabi-v7a` | `frida-gadget--android-arm.so.xz` |
| `x86_64` | `frida-gadget--android-x86_64.so.xz` |
| `x86` | `frida-gadget--android-x86.so.xz` |
3. 重命名并放置文件：
```
inputs\frida-gadget.so.xz
```
重打包工具接受 `.so` 和 `.so.xz` — 它会自动解压 `.xz`。
### 14.13 重打包失败 — "zipalign not found"
**症状：**
```
FileNotFoundError: Android SDK tool not found: zipalign. Install Android SDK Build-Tools and set ANDROID_SDK_ROOT...
```
**原因：**
Shell 环境中未设置 `ANDROID_SDK_ROOT`，或者 SDK 已安装但 **Build-Tools**（包含 `zipalign` 和 `apksigner` 的组件）尚未安装。请注意，`platform-tools`（包含 `adb`）是与 `build-tools` 分开的 SDK 组件。
**修复 — 选项 A：** 在 `.env` 中设置路径（由 API 自动加载）：
```
ANDROID_SDK_ROOT=D:\Android\Sdk
```
重打包工具自动扫描 `$ANDROID_SDK_ROOT/build-tools//`。
**修复 — 选项 B：** 通过 Android Studio SDK Manager 安装 Build-Tools：
Android Studio → SDK Manager → SDK Tools 选项卡 → 选中 **Android SDK Build-Tools** → Apply。
**修复 — 选项 C：** 仅通过命令行工具安装（无 Android Studio）：
```
sdkmanager "build-tools;35.0.0"
```
安装后验证：
```
where zipalign # Windows
which zipalign # Linux/macOS
```
### 14.14 重打包后应用启动崩溃 — 模拟器上的 ABI 不匹配
**症状：**
```
dlopen failed: library "libfrida-gadget.so" not found
java.lang.UnsatisfiedLinkError: dlopen failed: library "libfrida-gadget.so" not found
```
**原因：**
Frida Gadget 被注入到 `lib/arm64-v8a/` 中（因为原始 APK 的原生库是 arm64），但 Android 模拟器的**主要 ABI 是 x86_64**。Android 以 x86_64 启动进程，查找 `lib/x86_64/libfrida-gadget.so`，但找不到它。
**修复：**
1. 确认模拟器 ABI：
```
adb shell getprop ro.product.cpu.abi # primary ABI (e.g. x86_64)
adb shell getprop ro.product.cpu.abilist # full list
```
2. 下载匹配的 gadget（例如 `frida-gadget--android-x86_64.so.xz`）并将其放在 `inputs/frida-gadget.so.xz`。
3. 通过 API 或 GUI 重打包时，显式设置 `abi` 以匹配模拟器的主要 ABI：
```
{ "abi": "x86_64" }
```
`src/api_local.py` 中的默认值已更新为 `"x86_64"` 以便于模拟器操作。对于**物理手机**（几乎总是 `arm64-v8a`），重打包时将其覆盖为 `arm64-v8a`。
### 14.15 Swagger UI 返回 422 且包含 Windows 文件路径
**症状：**
```
{ "type": "json_invalid", "msg": "JSON decode error", "ctx": { "error": "Invalid \\escape" } }
```
**原因：**
Windows 路径使用反斜杠（`\`），这是 JSON 中的转义字符。将原始 Windows 路径粘贴到 Swagger 的请求体中会导致 JSON 解析失败。
**修复：**
在 Swagger UI 中输入路径时，将每个反斜杠加倍：
```
{ "apk_path": "C:\\Users\\Administrator\\Downloads\\app.apk" }
```
或者使用正斜杠，Windows 也接受：
```
{ "apk_path": "C:/Users/Administrator/Downloads/app.apk" }
```
### 14.16 Deepfake UI 错误
**症状：**
- 缺少 `torch`、`cv2` 或 `PIL`
**修复：**
```
pip install torch torchvision opencv-python pillow numpy
```
## 15. 论文可复现性说明
对于本项目的论文/报告版本：
1. **明确说明动态分析是在物理 Android 设备上执行的**，而不仅仅是在模拟器上。
2. **记录确切的主机环境**：操作系统、Python 版本和主要工具。
. **显式列出已安装的工具**：ADB、Frida、Objection、Apktool、Androguard、可选的 GUI/deepfake 包。
4. **描述测试工作流**：打补丁 APK → 安装 → 转发端口 → 附加 → 刺激 → 收集 → 评分 → 报告。
5. **记录数据集组成**：良性样本 vs 广告软件/恶意软件样本。
6. **提及良性应用被用作校准基线**以减少误报。
7. **保持风险评分规则明确**：除非确凿证据解锁分数，否则良性 <20。
8. **保留生成的 JSON 产物和 HTML 报告**以供复现。
## 16. 参考资料/工具
我们在 README 或论文中根据需要使用了这些参考资料：
- Android SDK Platform-Tools (ADB)
- Frida
- Frida Gadget
- Objection
- Apktool
- JADX
- Androguard
- YARA
- VirusTotal API
- Volatility 3
如果您需要更严格的学术附录，请添加：
- 工具名称，
- 在框架中的用途，
- 它是必需的还是可选的，
- 安装方法，
- 验证命令。
## 最后的实用说明
对于本项目，最稳定的路径是：
1. **直接从 HFIF 进行静态分析**
2. **在真机上进行动态分析**
3. **Frida Gadget 嵌入目标 APK**
4. **ADB 转发到本地端口 27042/27043**
5. **每次运行后生成案件报告**
标签：ADB 调试, Androguard, Android 恶意软件分析, APK 静态分析, Frida 注入, HTML 报告生成, Python 安全工具, SecList, YARA 规则, 内存取证, 凭据扫描, 可解释风险评分, 应用程序安全, 数字取证, 案件导向调查, 深度伪造检测, 混合取证调查框架, 目录枚举, 真机动态分析, 移动安全, 网络安全, 自动化脚本, 设备指纹, 运行时工件收集, 逆向工具, 隐私保护