Sangamesh-dev/ByteHunter
GitHub: Sangamesh-dev/ByteHunter
基于 LightGBM、XGBoost 等多模型集成与 SHAP 可解释性的 Windows PE 恶意软件检测引擎，提供威胁评分、类型分类、行为分析和 PDF 取证报告功能。
Stars: 0 | Forks: 0
# ByteHunter 🔍
**具备可解释 AI、行为模拟和 PDF 报告功能的 ML 驱动恶意软件检测引擎。**
ByteHunter 是一款全栈网络安全工具，它使用 ML 模型集成来分析 PE（Windows 可执行）文件——包括基于 EMBER 2018 数据集训练的 LightGBM、用于恶意软件类型分类的 XGBoost，以及用于提供可解释性的 SHAP。它具有实时 React 仪表板、扫描历史记录、行为 API 分析和可下载的 PDF 报告等功能。
## 演示
观看演示：https://drive.google.com/file/d/1OWp1ttLhegqNtXeZ25Bgwy7wKv7ZvdFw/view?usp=sharing
## 功能
- **多模型集成** — LightGBM (EMBER 2018)、XGBoost (BIG-2015)、Random Forest 和 Logistic Regression
- **SHAP 可解释性** — 显示哪些 PE 特征影响了判定结果（熵、导入表、入口点等）
- **行为模拟** — 检测可疑的 Win32 API 调用（代码注入、持久化、反调试）
- **批量扫描** — 一次最多上传 5 个文件并提供逐个文件的判定结果
- **扫描历史记录** — 基于 SQLite 的历史记录，支持按判定结果和风险级别进行筛选
- **PDF 报告** — 每次扫描均可下载取证报告
- **SHA-256 缓存** — 避免对以前扫描过的文件进行重复分析
- **Docker Compose** — 使用单个命令即可启动后端 + 前端
## 技术栈
| 层级 | 技术 |
|---|---|
| 后端 | FastAPI, Python 3.11 |
| ML 模型 | LightGBM, XGBoost, Scikit-learn, SHAP |
| 特征提取 | LIEF (PE 解析), EMBER 2018 特征集 |
| 数据库 | SQLite via aiosqlite |
| 报告生成 | ReportLab |
| 前端 | React (Vite), Tailwind CSS |
| 容器化 | Docker, Docker Compose |
| 调度 | APScheduler (模型热替换) |
## 项目结构
```
bytehunter/
├── backend/
│ ├── main.py # FastAPI app, endpoints
│ ├── analyzer.py # Core analysis pipeline
│ ├── features/
│ │ ├── ember_features.py # EMBER 2381-dim feature extractor
│ │ └── fallback_features.py # Fallback for non-PE files
│ ├── utils/
│ │ ├── db_manager.py # SQLite async CRUD
│ │ ├── report_gen.py # PDF generation (ReportLab)
│ │ ├── hash_utils.py # SHA-256, MD5, SHA-1
│ │ ├── malware_labels.py # Malware type label mappings
│ │ └── model_updater.py # Hot-swap model scheduler
│ ├── models/ # Trained model files (not committed)
│ ├── notebooks/ # Training notebook (model_training.ipynb)
│ ├── requirements.txt
│ └── Dockerfile
├── frontend/
│ ├── src/
│ │ ├── App.jsx
│ │ └── components/
│ │ ├── UploadZone.jsx
│ │ ├── ThreatScoreGauge.jsx
│ │ ├── VerdictBanner.jsx
│ │ ├── ShapChart.jsx
│ │ ├── BehaviorSim.jsx
│ │ ├── ExplanationCard.jsx
│ │ ├── ScanHistory.jsx
│ │ └── ...
│ ├── vite.config.js
│ └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```
## 入门指南
### 前置条件
- Docker + Docker Compose
- Python 3.11（用于本地开发）
- Node.js 18+（用于前端开发）
- EMBER 2018 模型文件（`ember_model_2018`）— 参见 [模型设置](#model-setup)
### 1. 克隆仓库
```
git clone https://github.com/YOUR_USERNAME/bytehunter.git
cd bytehunter
```
### 2. 设置环境变量
```
cp .env.example .env
```
根据需要编辑 `.env`：
```
CORS_ORIGINS=http://localhost:5173
MODELS_DIR=./backend/models
MAX_FILE_SIZE_MB=50
```
### 3. 模型设置
ByteHunter 需要将训练好的模型文件放置在 `backend/models/` 中：
| 文件 | 描述 |
|---|---|
| `ember_model_2018` | 基于 EMBER 2018 训练的 LightGBM 模型 |
| `xgboost_type_classifier.pkl` | XGBoost 恶意软件类型分类器 |
| `shap_explainer.pkl` | 用于 LightGBM 的 SHAP TreeExplainer |
| `random_forest.pkl` | Random Forest 集成模型 |
| `logistic_regression.pkl` | Logistic Regression 模型 |
要自行训练模型，请运行 Notebook：
```
cd backend/notebooks
jupyter notebook model_training.ipynb
```
### 4. 使用 Docker Compose 运行
```
docker-compose up --build
```
- 前端：http://localhost:5173
- 后端 API：http://localhost:8000
- API 文档：http://localhost:8000/docs
### 5. 本地运行（不使用 Docker）
**后端：**
```
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```
**前端：**
```
cd frontend
npm install
npm run dev
```
## API 接口
| 方法 | 接口 | 描述 |
|---|---|---|
| `GET` | `/api/health` | 模型加载状态检查 |
| `POST` | `/api/analyze` | 分析 1–5 个 PE 文件 |
| `GET` | `/api/history` | 获取扫描历史记录（按判定结果/风险筛选） |
| `GET` | `/api/history/{scan_id}` | 特定扫描的完整详情 |
| `GET` | `/api/report/{scan_id}` | 下载 PDF 取证报告 |
### 示例：分析文件
```
curl -X POST http://localhost:8000/api/analyze \
-F "files=@suspicious.exe"
```
### 示例响应
```
{
"filename": "suspicious.exe",
"verdict": "MALICIOUS",
"threat_score": 0.94,
"risk_level": "HIGH",
"malware_type": "Trojan",
"sha256": "abc123...",
"shap_features": [...],
"behavior_indicators": [
{ "api": "CreateRemoteThread", "name": "Code Injection", "severity": "HIGH" }
],
"scan_id": "uuid-here"
}
```
## ML 流水线
```
PE File
│
▼
LIEF Parser → EMBER 2381-dim feature vector
│
├──► LightGBM → Threat Score (0.0 – 1.0)
│
├──► XGBoost → Malware Type (Trojan, Ransomware, Spyware...)
│
├──► SHAP → Top features driving the verdict
│
└──► Fallback → Entropy + string heuristics (non-PE files)
```
**提取的特征类别：**
- 常规 PE 元数据（导入、导出、调试、TLS、重定位）
- PE 头字段（机器类型、节区数量、编译时间戳、镜像基址）
- 节区熵（`.text`、`.data`、`.rsrc` 等）
- 字节直方图（256 维）
- 字节熵直方图（16 维滑动窗口）
- 字符串特征（URL、注册表键、函数名称）
## 安全说明
## 路线图
- [ ] 集成 VirusTotal API 用于哈希查询
- [ ] YARA 规则扫描
- [ ] 网络流量分析（PCAP 支持）
- [ ] 用户身份验证 + 多租户扫描历史记录
- [ ] 部署到云端（Render + Vercel）
## 许可证
MIT License — 详见 [LICENSE](./LICENSE)。
## 作者
**Sangamesh Girish Dandin**
人工智能理学硕士 — National College of Ireland
[LinkedIn](https://www.linkedin.com/in/sangamesh-girish-dandin-553b45247/) · [GitHub](https://github.com/Sangamesh-dev)
标签：AMSI绕过, Apex, AV绕过, Conpot, DNS 反向解析, DNS枚举, Docker, EMBER数据集, FastAPI, LightGBM, PDF报告, PE文件分析, React, SHAP, Syscalls, Windows安全, XAI, XGBoost, 云安全监控, 人工智能安全, 可解释人工智能, 合规性, 威胁检测, 安全防御评估, 数字取证, 无服务器架构, 无线安全, 机器学习, 沙箱模拟, 版权保护, 网络安全, 网络安全工具, 自动化脚本, 自定义DNS解析器, 行为模拟, 请求拦截, 逆向工具, 隐私保护, 集成学习, 静态分析