ShravniThakur/ThreatIntelligenceSystem

# APK 威胁情报系统 **AI 驱动的 Android 恶意软件检测与分析平台** 一个综合性的恶意软件分析系统，结合了静态和动态 APK 分析、机器学习、恶意软件 DNA 指纹识别、intent 欺骗检测，以及由 GenAI 驱动的逆向工程，用于检测 Android 恶意软件、银行木马和虚假银行应用程序。 ## 架构 该系统由四个动态部分组成。其中两个需要您自己运行的部分位于此仓库中；另外两个是后端通过 HTTP 进行通信的外部服务。 | 组件 | 路径 | 说明 | |-------------|--------------|-----------------------------------------------------------------------| | Backend | `backend/` | FastAPI 应用 (`main.py`)，运行在 **:8001** — 负责编排分析流水线（单 worker，内存任务队列 + SSE 进度）。 | | Frontend | `frontend/` | Vite + React + Tailwind 控制台，运行在 **:5173**（开发环境）/ 生产环境下由后端提供服务。 | | MobSF | external | Mobile Security Framework，运行在 **:8000** — 执行实际的静态和动态 APK 分析。需在本地克隆并安装（见第 3 步）。 | | Ollama | external | 本地 LLM 运行时，运行在 **:11434** — 为 GenAI 逆向工程/报告层提供支持。无需 API key，可离线运行。 | | ML 模型 | `backend/model/` | 基于本地特征存储（真实的 APK 静态分析数据）训练的 LightGBM 多标签分类器。独立运行 — 如果缺少其依赖项，会优雅降级。 | | 示例 APK | `BankAPKS/` | 用于测试的真实银行 APK（已被 gitignore — 不在仓库中，见下文）。 | ## 前置条件 在每台机器上安装一次以下内容： - **Python 3.11+**（基于 3.13 开发）— 用于后端 - **Node.js 18+**（基于 22 开发）+ npm — 用于前端 - **MobSF** — 在本地克隆并安装（见第 3 步） - **[Ollama](https://ollama.com)** — GenAI 层的本地 LLM 运行时 - **Android emulator** (Android SDK + 一个 AVD) — **动态分析必需** ## 设置 ### 1. 克隆 ``` git clone https://github.com/ShravniThakur/ThreatIntelligenceSystem.git cd ThreatIntelligenceSystem ``` ### 2. 后端 ``` cd backend python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # then edit .env (see Configuration below) ``` ### 3a. MobSF（静态 + 动态分析引擎） MobSF 作为独立服务器运行 — 它 **不** 放在后端的 venv 中，也 **不** 包含在此仓库中。请在本地克隆并安装它（动态分析在模拟器上运行时需要本地安装）。 ``` # 将其 clone 到项目旁边（任意位置均可） git clone https://github.com/MobSF/Mobile-Security-Framework-MobSF.git mobsf cd mobsf ./setup.sh # one-time install (creates its own venv) ``` 然后在单独的终端中启动它（保持运行状态）： ``` cd mobsf ./run.sh 127.0.0.1:8000 ``` 在 检查它是否已启动。 **将 API key 同步到 `backend/.env`。** 本地安装的 key 派生自 `~/.MobSF/secret`。打印出当前的 key，并确保您的 `.env` 中的 `MOBSF_API_KEY` 与之匹配： ``` python3 -c "import hashlib; print(hashlib.sha256(open('$HOME/.MobSF/secret').read().encode()).hexdigest())" ``` ### 3b. Android emulator（动态分析必需） 动态分析会在运行中的 emulator 上运行 APK，该 emulator 必须使用 `-writable-system` 启动。在单独的终端中： ``` ~/Library/Android/sdk/emulator/emulator -avd Pixel_6_API_30 -writable-system -no-snapshot ``` 将 `Pixel_6_API_30` 替换为您的 AVD 名称（`emulator -list-avds`）。Emulator id（默认为 `emulator-5554`）必须与 `.env` 中的 `EMULATOR_NAME` / `MOBSF_ANALYZER_IDENTIFIER` 匹配。 ### 4. Ollama（本地 GenAI 层） ``` # 从 https://ollama.com 安装，然后： ollama serve # starts the API on http://localhost:11434 ollama pull gemma3 # download the model (or `ollama pull phi` for a smaller one) ``` ### 5. 前端 ``` cd frontend npm install # if the npm cache is root-owned: npm install --cache /tmp/npmcache ``` ### 6. 训练 ML 模型（一次性设置） 在运行后端服务器之前，您必须训练威胁分类器。该脚本会读取本地特征存储（`backend/feature_store.sqlite`，约 3,200 行真实的 APK 静态分析特征数据）和标签（`backend/labels.csv`），训练一个 LightGBM 多标签模型，并将产物写入 `backend/model/artifacts/`。 ``` cd backend source .venv/bin/activate # Windows: .venv\Scripts\activate python model/train.py ``` 除了 `requirements.txt` 中的推理依赖项外，训练还需要 `shap` 和 `matplotlib`（用于生成 SHAP 解释图表）： ``` pip install shap matplotlib ``` **当前模型（5 标签，基于内置数据集训练）：** 在留出的随机测试集上 macro-F1 达到 **0.92**（训练集 0.98 → 测试集 0.92，无过拟合迹象）。各标签测试集 F1 值：banking_trojan 0.97，spyware 0.95，obfuscated_loader 0.90，sms_stealer 0.80，benign 0.99。该分类器是 **实验性的且独立运行的** — 它会带有免责声明展示，并且 **不** 会输入到融合判定中。 ## 运行 在各自的终端中启动每个服务： ``` # 1. MobSF cd mobsf && ./run.sh 127.0.0.1:8000 （上面的步骤 3） # 2. Emulator ~/Library/Android/sdk/emulator/emulator -avd Pixel_6_API_30 -writable-system -no-snapshot # 3. Ollama ollama serve # 4. Backend cd backend && source .venv/bin/activate uvicorn main:app --host 0.0.0.0 --port 8001 --workers 1 # MUST be a single worker # 5. Frontend cd frontend && npm run dev # http://localhost:5173 ``` 然后打开 并上传一个 APK。 ### 直接运行流水线（CLI） 您也可以在不使用 Web UI 的情况下运行分析流水线 — 这对于批量运行或调试非常有用。在 MobSF + emulator 启动且 venv 激活的情况下： ``` cd backend source .venv/bin/activate # 分析一个 APK 并将完整报告保存在 reports/ 下 python feature_store_pipeline.py samples/app-debug.apk --save-report # 分析并导出提取的特征向量到 CSV python feature_store_pipeline.py samples/your-app.apk --save-report --export features.csv ``` ### 生产环境构建（single-origin） 如果 `frontend/dist` 存在，`backend/main.py` 会将其在 提供服务，因此您可以通过后端端口运行所有内容： ``` cd frontend VITE_API_BASE= npm run build # empty API base -> relative, same-origin calls # 现在只需运行 backend；打开 http://localhost:8001 ``` ## 配置 所有后端配置都位于 `backend/.env` 中（从 `backend/.env.example` 复制）。 | 变量 | 默认值 | 用途 | |------------------------------|--------------------------|------------------------------------------------------| | `MOBSF_API_KEY` | — | **必需。** MobSF REST API key（来自 MobSF UI）。 | | `MOBSF_URL` | `http://localhost:8000` | MobSF 的访问地址。 | | `MOBSF_HTTP_TIMEOUT` | `300` | 调用 MobSF 的 HTTP 超时时间（秒）。 | | `EMULATOR_NAME` | `emulator-5554` | Android emulator id（仅用于动态分析）。 | | `MOBSF_ANALYZER_IDENTIFIER` | `emulator-5554` | MobSF 分析器设备 id（仅用于动态分析）。 | | `MOBSF_DYNAMIC_RUN_SECONDS` | `90` | 动态分析期间运行 APK 的时间长度。 | | `FEATURE_STORE_DB` | `feature_store.sqlite` | SQLite 特征存储（自动创建）。 | | `OLLAMA_URL` | `http://localhost:11434` | 本地 Ollama API。 | | `OLLAMA_MODEL` | `gemma3` | 模型名称（必须先执行 `ollama pull`）。 | | `OLLAMA_TIMEOUT` | `600` | LLM 调用超时时间（秒）。 | 前端会读取 `VITE_API_BASE`（构建时）：未设置 → 默认为 `http://localhost:8001`；设置为空则表示使用同源（same-origin）的生产环境构建。 ## 项目结构 ``` . ├── backend/ FastAPI service + analysis pipeline │ ├── main.py API entrypoint (:8001) — job queue + SSE │ ├── feature_store_pipeline.py MobSF orchestration + feature extraction │ ├── fusion.py combines all detector scores │ ├── risk_scorer.py deterministic risk scoring │ ├── reverse_engineer.py GenAI reverse-engineering (Ollama) │ ├── social_engineer.py social-engineering / phishing analysis │ ├── intent_spoof.py fake-banking-app / intent-spoof detection │ ├── dna_fingerprint.py APK DNA fingerprinting (repackaged-clone detection) │ ├── campaign_store.py campaign clustering across analyses │ ├── report_generator.py final GenAI report │ ├── model/ ML classifier — LightGBM (predict.py / train.py) │ ├── bank_whitelist.json known-good bank app fingerprints │ ├── requirements.txt │ └── .env.example ← copy to .env ├── frontend/ Vite + React + Tailwind console (:5173) │ └── src/{pages,panels,components,lib} ├── BankAPKS/ test APKs (gitignored) └── mobsf/ MobSF install (gitignored — clone separately, see step 3) ``` ## 故障排除 - **启动时出现 `MOBSF_API_KEY` 错误** — 后端缺少此项将拒绝启动。请确保 MobSF 正在运行，并且 key 已写入 `backend/.env`。 - **`npm install` 报错 EACCES** — npm 缓存可能由 root 用户拥有；请使用 `npm install --cache /tmp/npmcache`。 - **GenAI 部分为空** — Ollama 未运行或模型未拉取（`ollama serve` + `ollama pull gemma3`）。 - **ML 分类器显示 "unavailable"** — 未安装 `pandas`/`scikit-learn`/`lightgbm`。它是可选的；流水线的其余部分仍能正常工作。

标签：AI风险缓解, Apex, AV绕过, FastAPI, 云资产清单, 威胁情报, 安卓恶意软件分析, 开发者工具, 机器学习, 逆向工具, 逆向工程, 静态与动态分析