mohammadfarooquerahi/ShieldSourceFYP
GitHub: mohammadfarooquerahi/ShieldSourceFYP
面向中小企业的全栈网络安全应急响应平台，结合角色化工作流与机器学习日志分析，支持事件上报、专家研判和自动化攻击分类。
Stars: 0 | Forks: 0
# Shield-Source 🛡️
### 网络安全应急响应系统
**毕业设计 (FYP) — 计算机科学学士**
## 📌 项目概述
Shield-Source 是一个全栈网络安全应急响应平台，支持以下功能：
- **用户**报告网络安全事件（黑客攻击、恶意软件、勒索软件、网络钓鱼、数据窃取、未经授权的访问）并上传可疑的日志文件。
- **网络安全专家**审查分配的事件，分析证据并编写取证记录。
- **管理员**管理用户、分配专家并监控整体事件仪表板。
- **ML 微服务**自动将上传的日志文件分类为攻击类别（SQL Injection、Brute Force、DDoS、Path Traversal、Normal），并提供置信度分数和严重性评级。
### 系统架构
```
┌─────────────────┐ HTTP/REST ┌─────────────────────┐
│ React Frontend │ ◄─────────────────► │ Node.js/Express API│
│ (Port 3000) │ │ (Port 5000) │
└─────────────────┘ └────────┬────────────┘
│ HTTP POST /analyze
▼
┌─────────────────────┐
│ Python ML Service │
│ Flask + sklearn │
│ (Port 8000) │
└────────┬────────────┘
│
┌────────▼────────────┐
│ MySQL 8 Database │
│ shield_source DB │
└─────────────────────┘
```
## 👥 团队信息
| 角色 | 职责 |
|-------------------|-----------------------------------------|
| 团队负责人 | 系统架构与 Node.js 后端 |
| 前端开发 | React UI 与仪表板 |
| ML 工程师 | Python ML 服务与日志分析 |
| 数据库工程师 | MySQL schema 与查询优化 |
## ✅ 前置条件
在设置项目之前，请确保已安装以下所有工具：
| 工具 | 版本 | 下载链接 |
|--------------|----------|-----------------------------------------------|
| Node.js | 18.x LTS | https://nodejs.org |
| Python | 3.9+ | https://python.org |
| MySQL Server | 8.0+ | https://dev.mysql.com/downloads/mysql/ |
| Git | 最新版 | https://git-scm.com |
## 🗂️ 项目结构
```
shield-source/
├── client/ # React frontend (Vite/CRA)
│ ├── src/
│ └── package.json
│
├── server/ # Node.js Express backend API
│ ├── controllers/
│ ├── routes/
│ ├── middleware/
│ └── package.json
│
├── ml-service/ # Python Flask ML microservice
│ ├── app.py # Flask application entry point
│ ├── requirements.txt # Python dependencies
│ ├── utils/
│ │ └── log_parser.py # Log file feature extractor
│ └── model/
│ ├── train_model.py # Model training script
│ ├── classifier.pkl # Trained model (generated)
│ └── label_encoder.pkl# Label encoder (generated)
│
├── database/
│ └── schema.sql # MySQL schema (run once)
│
└── README.md
```
## ⚙️ 设置说明
### 步骤 1 — 克隆代码库
```
git clone https://github.com/your-team/shield-source.git
cd shield-source
```
### 步骤 2 — 设置 MySQL 数据库
1. 打开 MySQL Workbench 或 MySQL CLI。
2. 运行 schema 脚本：
```
mysql -u root -p < database/schema.sql
```
3. 验证数据库是否已创建：
```
USE shield_source;
SHOW TABLES;
```
预期表：`users`、`incidents`、`files`、`expert_notes`、`ml_predictions`
**由 schema 脚本生成的默认账户：**
| 邮箱 | 密码 | 角色 |
|-------------------------------|-----------|--------|
| admin@shieldsource.local | admin123 | admin |
| expert@shieldsource.local | expert123 | expert |
### 步骤 3 — 设置 Node.js 后端
```
cd server
npm install
```
在 `server/` 目录中创建 `.env` 文件：
```
# 服务器
PORT=5000
NODE_ENV=development
# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=shield_source
# JWT
JWT_SECRET=your_super_secret_jwt_key_change_this_in_production
JWT_EXPIRES_IN=7d
# ML Service
ML_SERVICE_URL=http://localhost:8000
# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE_MB=50
```
启动后端：
```
npm run dev # Development (nodemon auto-reload)
# 或
node server.js # Production
```
API 将在以下地址可用：`http://localhost:5000`
### 步骤 4 — 设置 Python ML 微服务
```
cd ml-service
```
#### 4a. 创建 Python 虚拟环境（推荐）
```
# Windows
python -m venv venv
venv\Scripts\activate
# Linux / macOS
python3 -m venv venv
source venv/bin/activate
```
#### 4b. 安装依赖项
```
pip install -r requirements.txt
```
#### 4c. 训练 ML 模型（启动服务前必须完成）
```
python model/train_model.py
```
预期输出：
```
============================================================
Shield-Source ML Model Training
============================================================
[1/5] Generating synthetic training data …
Dataset shape : (700, 8)
[2/5] Encoding labels …
[3/5] Splitting data …
[4/5] Training RandomForestClassifier (200 trees) …
[5/5] Evaluating on test set …
Accuracy : 0.9929 (99.29%)
✔ Saved classifier → model/classifier.pkl
✔ Saved label encoder → model/label_encoder.pkl
============================================================
```
#### 4d. 启动 ML 服务
```
python app.py
```
ML 服务将在以下地址可用：`http://localhost:8000`
**生产环境（Linux/macOS — 使用 Gunicorn）：**
```
gunicorn -w 4 -b 0.0.0.0:8000 app:app
```
**生产环境（Windows — 使用 Waitress）：**
```
pip install waitress
waitress-serve --port=8000 app:app
```
### 步骤 5 — 设置 React 前端
```
cd client
npm install
npm run dev # Development server on http://localhost:3000
```
## 🌐 API Endpoints
### Node.js 后端（端口 5000）
| 方法 | Endpoint | 鉴权 | 描述 |
|--------|-----------------------------------|----------|------------------------------------|
| POST | `/api/auth/register` | 无 | 注册新用户 |
| POST | `/api/auth/login` | 无 | 登录，获取 JWT token |
| GET | `/api/incidents` | JWT | 列出所有事件（按角色过滤） |
| POST | `/api/incidents` | JWT | 创建新事件 |
| GET | `/api/incidents/:id` | JWT | 获取事件详情 |
| PUT | `/api/incidents/:id/status` | Expert | 更新事件状态 |
| POST | `/api/incidents/:id/assign` | Admin | 为事件分配专家 |
| POST | `/api/incidents/:id/files` | JWT | 上传日志文件 |
| GET | `/api/incidents/:id/files` | JWT | 列出事件的相关文件 |
| POST | `/api/incidents/:id/notes` | Expert | 添加专家取证记录 |
| GET | `/api/incidents/:id/notes` | JWT | 获取事件的所有记录 |
| GET | `/api/incidents/:id/predictions` | JWT | 获取事件的 ML 预测结果 |
| GET | `/api/admin/users` | Admin | 列出所有用户 |
| PUT | `/api/admin/users/:id/role` | Admin | 更改用户角色 |
### Python ML 服务（端口 8000）
| 方法 | Endpoint | 描述 |
|--------|-------------------|------------------------------------------|
| GET | `/health` | 服务存活检查 |
| POST | `/analyze` | 分析日志文件，返回预测结果 |
| POST | `/analyze/batch` | 一次性分析多个日志文件 |
#### POST `/analyze` — 请求体
**选项 A — 以字符串形式发送日志内容：**
```
{
"log_content": "192.168.1.1 GET /index.php?id=1 UNION SELECT...",
"file_id": 42
}
```
**选项 B — 发送服务器端文件路径：**
```
{
"file_path": "/absolute/path/to/server/uploads/abc123.log",
"file_id": 42
}
```
#### POST `/analyze` — 响应
```
{
"file_id": 42,
"threat_type": "SQL_Injection",
"confidence_score": 0.9750,
"severity": "high",
"features": {
"total_lines": 120,
"error_lines": 15,
"sql_keywords": 45,
"auth_failures": 2,
"unique_ips": 3,
"high_freq_ip_lines": 8,
"path_traversal": 0
}
}
```
#### 严重程度级别
| 威胁类型 | 严重性 | 含义 |
|----------------|----------|------------------------------------------|
| Normal | low | 未检测到攻击 |
| Brute_Force | medium | 凭据填充 / 密码喷洒 |
| SQL_Injection | high | 数据库数据泄露风险 |
| Path_Traversal | high | 文件系统暴露风险 |
| DDoS | critical | 服务可用性受到攻击 |
## 🧪 测试 ML 服务
使用 `curl` 或 Postman 手动测试 endpoints：
```
# 健康检查
curl http://localhost:8000/health
# 分析日志内容
curl -X POST http://localhost:8000/analyze \
-H "Content-Type: application/json" \
-d "{\"log_content\": \"GET /page?id=1 UNION SELECT username FROM users-- \nSELECT * FROM admin\nDROP TABLE users\", \"file_id\": 1}"
```
## 🔒 安全提示
1. **切勿提交 `.env` 文件** — 将其添加到 `.gitignore` 中
2. **密码**以 bcrypt 哈希值（成本因子 10）存储 — 绝不使用明文
3. **文件上传**会重命名为 UUID 以防止文件名注入
4. 为每个上传的文件存储 **SHA-256 哈希值**以进行完整性验证
5. **JWT token** 默认在 7 天后过期
6. **ML 服务**不应暴露在公共互联网中 — 通过 Node.js 后端进行代理
## 📊 ML 模型详情
| 参数 | 值 |
|------------------|-----------------------------------------------|
| 算法 | Random Forest Classifier |
| 树数量 | 200 estimators |
| 训练样本 | 700（合成的、均衡的） |
| 类别 | Normal, SQL_Injection, Brute_Force, DDoS, Path_Traversal |
| 特征数量 | 7 |
| 预期准确率 | ~99%（合成数据） |
| 序列化 | joblib (classifier.pkl) |
### 特征向量
| 特征 | 描述 |
|---------------------|----------------------------------------------|
| `total_lines` | 日志总行数 |
| `error_lines` | 包含 ERROR/CRITICAL/FATAL 关键词的行数 |
| `sql_keywords` | 包含 SQL injection 关键词的行数 |
| `auth_failures` | 包含登录失败/认证失败文本的行数 |
| `unique_ips` | 日志中不同的 IP 地址数量 |
| `high_freq_ip_lines`| 来自出现超过 10 次的 IP 的行数 |
| `path_traversal` | 包含 `../` 或 `..\` 序列的行数 |
## 🚀 运行所有服务（快速开始）
打开三个终端窗口：
**终端 1 — 数据库：**（如果 MySQL 服务已启动，则已在运行）
**终端 2 — 后端 API：**
```
cd server && npm run dev
```
**终端 3 — ML 服务：**
```
cd ml-service
venv\Scripts\activate # Windows
python app.py
```
**终端 4 — 前端：**
```
cd client && npm run dev
```
在浏览器中打开：**http://localhost:3000**
## 📝 许可证
本项目作为毕业设计的一部分，仅用于学术目的。
*Shield-Source — 通过智能应急响应保护数字资产*
标签：Apex, MITM代理, 事件响应系统, 库, 应急响应, 机器学习, 网络安全, 自定义脚本, 逆向工具, 隐私保护