bsm2006/apk-shield
GitHub: bsm2006/apk-shield
一个基于 Python 与 React 构建的 Android APK 恶意软件自动化分析平台，通过静态特征提取、风险评分、欺诈映射及 AI 解读生成可读的安全报告。
Stars: 0 | Forks: 0
# 🛡️ APK Shield — AI 驱动的 APK 恶意软件分析平台
一个可用于生产环境的 Android APK 恶意软件分析、逆向工程、风险评分、欺诈情报和 AI 驱动的报告系统。
## 🏗️ 架构
```
boiproject/
├── backend/ # Python FastAPI
│ ├── main.py # FastAPI app entrypoint
│ ├── requirements.txt
│ ├── Dockerfile
│ └── app/
│ ├── database.py # SQLAlchemy (SQLite/PostgreSQL)
│ ├── models.py # DB models
│ ├── schemas.py # Pydantic schemas
│ ├── analysis/
│ │ ├── apk_analyzer.py # Static analysis (Androguard + ZIP parser)
│ │ ├── risk_scorer.py # Weighted risk scoring engine
│ │ ├── fraud_mapper.py # Fraud type mapping engine
│ │ ├── similarity_engine.py # Cosine similarity engine
│ │ └── ai_explainer.py # OpenAI/Gemini explanation layer
│ └── routes/
│ ├── upload.py # POST /api/upload/
│ ├── analyze.py # POST/GET /api/analyze/
│ ├── score.py # GET /api/score/
│ ├── explain.py # GET/POST /api/explain/
│ ├── history.py # GET /api/history/
│ └── report.py # GET /api/report/
├── frontend/ # React + Vite + Tailwind
│ ├── src/
│ │ ├── pages/
│ │ │ ├── UploadPage.jsx # File upload with drag-and-drop
│ │ │ ├── DashboardPage.jsx # Analytics dashboard
│ │ │ ├── ReportPage.jsx # Full analysis report viewer
│ │ │ └── HistoryPage.jsx # Historical analyses
│ │ ├── components/
│ │ │ └── Layout.jsx # Sidebar navigation
│ │ └── api/client.js # Axios API client
│ ├── Dockerfile
│ └── nginx.conf
├── docker-compose.yml # One-command deployment
└── .env # Environment configuration
```
## 🚀 快速开始（单条命令）
```
# 克隆/导航到项目
cd boiproject
# （可选）为真实的 AI 解释设置 AI API key
echo "GEMINI_API_KEY=your_key_here" >> .env
# 运行一切
docker-compose up --build
# 打开浏览器
open http://localhost:3000
```
就是这样！上传任何 APK 并获取即时分析结果。
## 🖥️ 本地开发（不使用 Docker）
### 后端
```
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
后端 API: http://localhost:8000
API 文档: http://localhost:8000/docs
### 前端
```
cd frontend
npm install
npm run dev
```
前端: http://localhost:3000 (将 API 代理到端口 8000)
## 🔑 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | `sqlite:///./apk_analysis.db` | 数据库连接字符串 |
| `AI_PROVIDER` | `gemini` | `gemini` 或 `openai` |
| `GEMINI_API_KEY` | *(空)* | Google Gemini API 密钥 |
| `OPENAI_API_KEY` | *(空)* | OpenAI API 密钥 |
| `SECRET_KEY` | dev key | 应用密钥 |
## 🔍 核心功能
### 1. APK 静态分析
- Android Manifest 权限提取
- 危险权限识别
- API 调用模式检测
- 嵌入式 URL 提取
- 混淆检测（DexGuard/ProGuard 指标）
- Multi-DEX 检测
- Service、receiver、activity 枚举
### 2. 风险评分引擎 (0–100)
加权多因素评分：
| 组件 | 权重 | 因素 |
|-----------|--------|---------|
| 权限 | 30% | 数量、严重程度、危险权限比例 |
| API 调用 | 25% | 可疑 API 模式（SMS、管理员、反射） |
| URL | 20% | 原始 IP、可疑 TLD、C2 endpoint |
| 混淆 | 15% | 代码隐藏指标 |
| 行为 | 10% | 持久化、无障碍滥用、管理员权限 |
**风险等级：**
- 🟢 **安全** (0–24)：允许
- 🟡 **可疑** (25–54)：标记待审核
- 🔴 **拦截** (55–100)：立即拦截
### 3. 欺诈映射引擎
将技术行为映射到欺诈类型：
| 技术行为 | 欺诈类型 |
|-------------------|------------|
| READ_SMS + SmsManager | OTP 窃取 |
| SYSTEM_ALERT_WINDOW + AccessibilityService | 钓鱼/覆盖层攻击 |
| 位置 + 音频 + 后台服务 | 间谍软件 |
| DevicePolicyManager + 加密 | 勒索软件 |
| DexClassLoader + REQUEST_INSTALL | 增量加载器 |
| GET_ACCOUNTS + 键盘记录服务 | 凭证窃取程序 |
### 4. 威胁相似性引擎
- 将 APK 特征转换为 46 维数值向量
- 与所有已存储的 APK 进行余弦相似度比较
- 返回相似度排名前 5 的威胁及其相似度百分比
### 5. AI 解释层
- 支持 Google Gemini API 和 OpenAI GPT-3.5
- 生成人类可读的威胁摘要
- 提供具体的安全建议
- 回退到智能模板解释（不需要 API 密钥）
## 📡 API 参考
```
POST /api/upload/ Upload APK file
POST /api/analyze/{hash}?filename= Run full analysis pipeline
GET /api/analyze/{id} Get analysis by ID
GET /api/score/{id} Get detailed score breakdown
GET /api/explain/{id} Get AI explanation
POST /api/explain/{id}/regenerate Regenerate AI explanation
GET /api/history/ List all analyses (paginated)
GET /api/history/stats/dashboard Dashboard statistics
GET /api/report/{id}/json Full JSON report
DELETE /api/history/{id} Delete an analysis
```
## 🐳 Docker 部署
### 构建与运行
```
docker-compose up --build -d
docker-compose logs -f
```
### 停止
```
docker-compose down
```
### 使用 PostgreSQL（生产环境）
编辑 `docker-compose.yml` 取消注释 PostgreSQL 服务，然后：
```
DATABASE_URL=postgresql://apkuser:apkpassword@db:5432/apkdb docker-compose up --build
```
## ☁️ 云部署
### Railway
```
# 安装 Railway CLI
npm install -g @railway/cli
railway login
railway init
railway up
```
### Render
1. Fork 此代码库
2. 创建新的 Web Service → 连接代码库 → 将 root 设置为 `backend/`
3. 构建：`pip install -r requirements.txt`
4. 启动：`uvicorn main:app --host 0.0.0.0 --port $PORT`
5. 将前端部署为 Static Site → root: `frontend/` → 构建：`npm run build` → 发布：`dist/`
## 🔬 分析 Pipeline 流程
```
APK File Upload
↓
SHA256 Hash Computation
↓
Static Analysis (Androguard / ZIP Parser / Simulation)
↓ Extract: permissions, APIs, URLs, obfuscation, services
Risk Scoring Engine
↓ Weighted score 0-100 → SAFE/SUSPICIOUS/BLOCK
Fraud Mapping Engine
↓ Map behaviors → OTP theft, phishing, spyware, ransomware...
Feature Vectorization
↓ 46-dim numeric vector
Similarity Engine
↓ Cosine similarity → top-5 similar APKs
AI Explanation Layer
↓ Gemini/OpenAI → human-readable analysis + recommendations
Database Storage (SQLite/PostgreSQL)
↓
JSON Report + Dashboard Display
```
## 🧪 测试
运行完整的 pipeline 测试：
```
cd backend
source venv/bin/activate
python -c "
from app.analysis.apk_analyzer import analyze_apk_simulated
from app.analysis.risk_scorer import compute_risk_score
from app.analysis.fraud_mapper import map_fraud_types
import tempfile, os
with tempfile.NamedTemporaryFile(suffix='.apk', delete=False) as f:
f.write(b'PK' + b'\x00' * 500)
tmp = f.name
apk = analyze_apk_simulated(tmp)
score = compute_risk_score(apk)
fraud = map_fraud_types(apk)
print(f'Score: {score[\"risk_score\"]} | Level: {score[\"risk_level\"]}')
print(f'Frauds: {fraud[\"fraud_types\"]}')
os.unlink(tmp)
"
```
## 📊 技术栈
| 组件 | 技术 |
|-----------|------------|
| 后端 | Python 3.11, FastAPI, Uvicorn |
| 数据库 | SQLite (开发) / PostgreSQL (生产) |
| ORM | SQLAlchemy |
| 机器学习 | scikit-learn, numpy, pandas |
| APK 分析 | Androguard（可选）+ ZIP 解析器 |
| AI 层 | Google Gemini / OpenAI GPT-3.5 |
| 前端 | React 18, Vite, Tailwind CSS |
| 图表 | Recharts |
| 动画 | Framer Motion |
| 部署 | Docker, Docker Compose, Nginx |
## 🛡️ 安全说明
- APK 文件按哈希值存储（无文件名冲突）
- 最大文件大小：100 MB
- 文件仅在服务端处理
- 不向外部服务发送 APK 数据（AI 解释文本除外）
- 开发环境使用 SQLite 本地数据库；生产环境使用 PostgreSQL
*为 Android 安全研究用心打造 ❤️*
标签：Android恶意软件分析, APK静态分析, AV绕过, FastAPI, React, Syscalls, 云资产清单, 人工智能, 用户模式Hook绕过, 请求拦截, 逆向工具, 逆向工程