IKetutWidiyane/malware-detection-xgboost

# 使用 XGBoost 的恶意软件检测系统 一个全面的基于 Web 的恶意软件检测系统，它使用 **XGBoost 机器学习算法**，基于可移植可执行（PE）文件元数据特征，将 Windows 可执行文件分类为**恶意**或**良性**。 该系统使用 **FastAPI**（后端）、**Next.js**（前端）、**MySQL**（数据库）和 **XGBoost**（机器学习模型）构建。它提供用户身份验证、文件扫描、扫描历史记录、报告生成和管理功能。 ## 📋 概述 本项目通过提取和分析 PE 文件元数据而不执行文件，来实现**静态恶意软件分析**。训练好的 XGBoost 模型基于包括以下内容的综合特征提取来预测恶意软件： - **文件属性**：大小、熵、节区 - **PE 头**：导入、导出、资源、调试信息 - **字符串分析**：路径、URL、注册表项 - **字节分布**：直方图和字节级统计数据 - **导入/导出数据**：DLL 计数、数据目录 ## ✨ 主要功能 ### 🔐 身份验证与授权 - 用户注册和登录 - 基于 JWT 的身份验证 - 基于角色的访问控制（用户/管理员） - 安全的密码哈希 ### 🔍 恶意软件检测 - 拖放式文件上传界面 - 实时 PE 元数据提取 - 基于 XGBoost 的恶意软件预测 - 置信度概率评分 - 扫描结果：恶意/良性分类 ### 📊 文件验证 **支持的扩展名：** - `.exe`, `.dll`, `.sys`, `.scr`, `.ocx` **限制条件：** - 最大文件大小：30 MB - 服务端扩展名验证 ### 👤 用户功能 - 上传和扫描可执行文件 - 查看带有详细信息的个人扫描历史记录 - 搜索和过滤扫描记录 - 删除扫描记录 - 将报告导出为 PDF - 将历史记录导出为 CSV ### 👨‍💼 管理员控制面板 - 系统统计和分析数据 - 全局扫描活动监控 - 用户管理（查看、更新、删除） - 角色分配 - 全局报告生成 - 系统性能洞察 ### 🤖 机器学习 - XGBoost 分类模型 - 约 40 多项特征提取 - 模型评估指标（准确率、精确率、召回率、F1-Score） - 基于 EMBER 2018 数据集进行训练 - 用于预测的特征列对齐 # 🛠️ 技术栈 ## 后端 - **Python 3.10+** - **FastAPI** - Web 框架 - **SQLAlchemy** - ORM - **MySQL** - 数据库 - **XGBoost** - ML 模型 - **Scikit-learn** - ML 工具 - **Pefile** - PE 文件解析 - **ReportLab** - PDF 生成 ## 前端 - **Next.js 16** - React 框架 - **React 19** - UI 库 - **TypeScript** - 类型安全 - **Tailwind CSS** - 样式设计 - **Recharts** - 数据可视化 - **Lucide React** - 图标 # 📁 项目结构 ``` malware-detection-xgboost/ ├── frontend/ # Next.js frontend application │ ├── src/ │ │ ├── app/ # App routes and pages │ │ │ ├── layout.tsx # Root layout │ │ │ ├── page.tsx # Dashboard │ │ │ ├── login/ # Login page │ │ │ ├── register/ # Registration page │ │ │ ├── dashboard/ # User dashboard │ │ │ ├── history/ # Scan history │ │ │ └── admin/ # Admin panel │ │ ├── components/ # Reusable components │ │ │ ├── UploadDropzone.tsx # File upload │ │ │ ├── HistoryTable.tsx # Scan history table │ │ │ └── DashboardCharts.tsx# Dashboard charts │ │ └── lib/ │ │ ├── api.ts # API client │ │ ├── auth.ts # Auth utilities │ │ └── validation.ts # Form validation │ └── package.json │ ├── ml-service/ # FastAPI backend service │ ├── dataset/ │ │ └── ember2018/ # EMBER dataset │ ├── model/ │ │ ├── xgb_model.pkl # Trained XGBoost model │ │ └── feature_columns.pkl # Feature column mapping │ ├── evaluation_result/ # Model evaluation results │ ├── uploads/ # Uploaded files (temp) │ ├── reports/ # Generated reports │ │ │ ├── main.py # FastAPI app & routes │ ├── auth.py # Authentication routes │ ├── database.py # Database setup │ ├── models.py # SQLAlchemy models │ ├── schemas.py # Pydantic schemas │ ├── config.py # Configuration │ ├── security.py # Security utilities │ ├── extractor.py # PE metadata extraction │ ├── predictor.py # Malware prediction │ ├── train.py # Model training script │ ├── evaluate.py # Model evaluation │ ├── create_tables.py # Database initialization │ │ │ ├── requirements.txt # Python dependencies │ ├── .env # Environment variables (production) │ └── .env.local # Environment variables (development) │ ├── .gitignore └── README.md ``` # 📋 前置条件 确保已安装以下内容： - **Python 3.10+** ([下载](https://www.python.org/)) - **Node.js 20+** ([下载](https://nodejs.org/)) - **MySQL 8.0+** 或 **MariaDB** ([下载](https://www.mysql.com/)) - **Git** (用于版本控制) 验证安装： ``` python --version node --version npm --version mysql --version ``` # 🚀 安装与设置 ## 1️⃣ 克隆仓库 ``` git clone cd malware-detection-xgboost ``` ## 2️⃣ 数据库设置 创建 MySQL 数据库： ``` CREATE DATABASE malware_detection; USE malware_detection; ``` 更新 `ml-service/.env.local` 中的数据库凭据： ``` DATABASE_URL=mysql+pymysql://root:password@localhost/malware_detection ``` ## 3️⃣ 后端设置 ``` cd ml-service # 创建 virtual environment python -m venv venv # 激活 venv (Windows) venv\Scripts\activate # 激活 venv (macOS/Linux) source venv/bin/activate # 安装 dependencies pip install -r requirements.txt # 初始化 database python create_tables.py # 启动 FastAPI server uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` **后端运行于：** `http://localhost:8000` **API 文档：** `http://localhost:8000/docs` ## 4️⃣ 前端设置 ``` cd frontend # 安装 dependencies npm install # 启动 development server npm run dev ``` **前端运行于：** `http://localhost:3000` # ⚙️ 环境变量 ### 后端 (ml-service/.env.local) ``` APP_ENV=development DATABASE_URL=mysql+pymysql://root:@localhost/malware_detection SECRET_KEY=SECRET123 ALGORITHM=HS256 UPLOAD_DIR=uploads MAX_FILE_SIZE=31457280 FRONTEND_URL=http://localhost:3000 ``` ### 前端 (frontend/.env.local) ``` NEXT_PUBLIC_API_URL=http://localhost:8000 ``` # 🔧 配置文件 ### main.py - FastAPI 配置 - CORS middleware 设置 - 路由定义 - 身份验证中间件 - 文件上传 endpoint - 数据库会话管理 ### config.py - 环境配置 - 数据库连接 - JWT 设置 - 上传目录 - 文件大小限制 - 前端 URL ### extractor.py - 特征提取 - PE 文件分析 - 熵计算 - 字符串分析 - 导入/导出提取 - 字节分布分析 ### predictor.py - ML 预测 - 模型加载 - 特征对齐 - 概率预测 - 预测分类 # 📚 API Endpoints ### 身份验证 - `POST /register` - 用户注册 - `POST /login` - 用户登录 - `POST /logout` - 用户登出 ### 文件操作 - `POST /upload` - 上传和扫描文件 - `GET /history` - 获取扫描历史记录 - `GET /history/{id}` - 获取扫描详情 - `DELETE /history/{id}` - 删除扫描记录 ### 管理员 - `GET /admin/stats` - 系统统计信息 - `GET /admin/users` - 列出用户 - `PATCH /admin/users/{id}` - 更新用户角色 - `DELETE /admin/users/{id}` - 删除用户 ### 报告 - `GET /report/pdf` - 生成 PDF 报告 - `GET /report/csv` - 导出 CSV 历史记录 # 🤖 模型训练 ### 数据集 该模型基于约 120 万个样本的 **EMBER 2018** 数据集进行训练，位于： ``` ml-service/dataset/ember2018/ ``` ### 训练模型 ``` cd ml-service python train.py ``` **输出：** - `ml-service/model/xgb_model.pkl` - 训练好的模型 - `ml-service/model/feature_columns.pkl` - 特征映射 ### 评估模型 ``` python evaluate.py ``` **输出：** `ml-service/evaluation_result/` - `evaluation_report.txt` - 详细指标 - `metrics.csv` - 分类指标 # 🐛 故障排除 ### 上传文件失败 **检查：** 1. 后端服务器是否正在运行（`uvicorn main:app --reload`） 2. 用户是否已通过身份验证（先登录） 3. 文件格式是否受支持（.exe, .dll, .sys, .scr, .ocx） 4. 文件大小是否 < 30 MB 5. 后端日志中的错误消息 **解决方案：** ``` # 查看 backend console 获取详细错误 # Backend 将打印：✓ File saved, ✓ Metadata extracted 等 ``` ### 数据库连接错误 ``` ERROR: (pymysql.err.OperationalError) ``` **解决方案：** 1. 验证 MySQL 是否正在运行 2. 检查 `.env.local` 中的 DATABASE_URL 3. 验证凭据和数据库是否存在 ``` # 测试 MySQL connection mysql -u root -p -h localhost mysql> USE malware_detection; mysql> SHOW TABLES; ``` ### 未找到模型错误 ``` FileNotFoundError: model/xgb_model.pkl ``` **解决方案：** 确保两个模型文件都存在： ``` ml-service/model/xgb_model.pkl ml-service/model/feature_columns.pkl ``` 如果缺失，请重新训练模型： ``` python train.py ``` ### 控制台中的 CORS 错误 ``` Access to XMLHttpRequest blocked by CORS policy ``` **解决方案：** - 验证后端配置中的 `FRONTEND_URL` - 确保前端和后端端口与配置匹配 - 清除浏览器缓存并重启服务器 ### 导入错误 ``` ModuleNotFoundError: No module named 'pefile' ``` **解决方案：** ``` pip install -r requirements.txt # 或 pip install pefile pymysql python-jose passlib[bcrypt] reportlab ``` # 📦 构建与部署 ### 前端构建 ``` cd frontend npm run build npm run start ``` ### 后端部署 使用部署平台（Railway、Vercel 等）中的环境变量： ``` APP_ENV=production DATABASE_URL=mysql+pymysql://user:pass@host:3306/db SECRET_KEY= FRONTEND_URL=https://your-frontend.com ``` ### Docker（可选） 如果需要，创建 `Dockerfile` 以进行容器化。 # 📄 许可证 本项目是论文/skripsi 研究项目的一部分。 # 👨‍💻 贡献 如有任何问题或改进建议，请提交 issue 或发起 pull request。 # 📞 支持 如有任何疑问或问题，请参阅 `http://localhost:8000/docs` 上的 API 文档，或查看上方的故障排除部分。 评估结果： ``` ml-service/evaluation_result/ ``` 生成的文件： ``` evaluation_report.txt metrics.csv confusion_matrix.png ``` # 系统工作流程 1. 用户注册或登录系统。 2. 后端生成 JWT 访问令牌。 3. 用户上传可执行文件。 4. 后端验证文件扩展名和文件大小。 5. 从上传的文件中提取 PE 元数据。 6. 元数据被传递给训练好的 XGBoost 模型。 7. 模型预测该文件是恶意的还是良性的。 8. 扫描结果存储在数据库中。 9. 用户可以查看扫描历史记录、分析数据和生成的报告。 # API Endpoints | Method | Endpoint | Description | | ------ | ------------------------------ | ---------------------------- | | GET | `/` | API 状态 | | POST | `/register` | 注册新用户 | | POST | `/login` | 用户登录 | | POST | `/upload` | 上传并扫描文件 | | GET | `/history` | 获取扫描历史记录 | | GET | `/history/{history_id}` | 获取扫描详情 | | DELETE | `/history/{history_id}` | 删除扫描记录 | | DELETE | `/history` | 删除所有用户扫描历史 | | GET | `/stats` | 用户统计信息 | | GET | `/analytics` | 分析数据 | | GET | `/history/{history_id}/report` | 导出 PDF 报告 | | GET | `/history/report/all` | 导出所有报告 | | GET | `/history/export/csv` | 导出 CSV 历史记录 | | GET | `/admin/stats` | 全局统计信息 | | GET | `/admin/users` | 获取用户列表 | | PUT | `/admin/users/{user_id}/role` | 更新用户角色 | | DELETE | `/admin/users/{user_id}` | 删除用户 | # 用户角色 ## 用户 * 上传和扫描文件 * 查看个人扫描历史记录 * 查看扫描详情 * 删除个人历史记录 * 导出报告 ## 管理员 * 查看所有扫描活动 * 访问全局统计数据 * 管理用户 * 更新用户角色 * 删除用户 * 导出系统范围内的报告 # 安全说明 * 上传的文件将被临时存储并在处理后删除。 * 上传的文件永远不会被执行。 * 系统仅使用静态分析。 * `SECRET_KEY` 目前为了开发目的进行了硬编码，在生产环境中应将其移至环境变量中。 * 在部署前使用强数据库凭据。 # 支持的文件类型 ``` .exe .dll .sys .scr .ocx ``` # 生产构建 构建前端： ``` cd frontend npm run build ``` 运行生产构建： ``` npm run start ``` # 未来改进 * 动态恶意软件分析集成 * 实时威胁监控 * Docker 部署 * 云部署支持 * 高级特征提取 * 混合检测（静态 + 动态分析） # 作者 I Ketut Widiyane 毕业项目 — 使用 XGBoost、FastAPI、Next.js 和 MySQL 的恶意软件检测系统。

标签：Apex, AV绕过, DNS 反向解析, FastAPI, PE文件分析, XGBoost, 云安全监控, 机器学习, 网络信息收集, 自动化攻击, 逆向工具, 静态分析