Areej-zeb/Aegis-Enterprise-Threat-Detection-and-Security-Advisory

## ✨ 功能特性

### 🎯 **核心能力** - **实时威胁检测**，采用 ML 分类 - **多种攻击支持**：DDoS、端口扫描、暴力破解、SQL 注入 - **XGBoost 模型**，具有 79% 的 F1-score 准确率 - **SHAP 可解释性**，实现模型透明化 - **WebSocket 流式传输**，支持亚秒级告警

### 🖥️ **双仪表板系统** - **React 仪表板** - 现代、响应式 UI - **Streamlit 仪表板** - ML 监控与分析 - **5 个交互视图**：概览、实时告警、分析、可解释性、威胁情报 - **自动刷新**开关，适用于 SOC 运维

## 🚀 快速开始 ### 📋 前置条件

🐍 Python	3.9+（已在 3.10、3.11、3.12、3.13 上测试）
🌐 Node.js	16+（用于 React 仪表板）
💻 OS	Windows、Linux、macOS、WSL

### ⚡ 一键设置 ``` # 1️⃣ 克隆仓库 git clone https://github.com/Areej-zeb/Aegis-Enterprise-Threat-Detection-and-Security-Advisory.git cd Aegis-Enterprise-Threat-Detection-and-Security-Advisory # 2️⃣ 安装 Python 依赖 pip install -r requirements.txt # 3️⃣ 为 unified backend 安装 Node 依赖 cd backend/unified npm install cd ../.. # 4️⃣ 安装前端依赖 cd frontend_react npm install cd ../.. # 5️⃣ 配置 MongoDB (编辑 backend_auth/.env) # MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/ # JWT_SECRET=your_secret_key # 6️⃣ 运行系统 # Windows: START_AEGIS.bat # Linux/macOS: chmod +x start-aegis.sh && ./start-aegis.sh ``` ### 🌐 访问入口 | 服务 | URL | 描述 | |---------|-----|-------------| | **React 仪表板** | http://localhost:5173 | 现代 Web 界面 | | **统一后端** | http://localhost:5000 | Express 代理 + 认证 | | **后端 API** | http://localhost:8000 | FastAPI 端点 | | **API 文档** | http://localhost:8000/docs | 交互式 API 文档 | ### 🔑 默认凭据 ``` Email: admin@aegis.local Password: admin123 ``` 或通过注册创建新账户。 ## 🔧 手动设置

🚀 统一后端设置

``` # 1️⃣ 导航至 unified backend cd backend/unified # 2️⃣ 安装 Node.js 依赖 npm install # 3️⃣ 配置环境 (.env) # MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/ # JWT_SECRET=your_secret_key # PORT=5000 # 4️⃣ 启动后端服务器 npm start ``` 统一后端： - 在端口 5000 上运行 Express - 从端口 8000 代理 Python 服务（IDS、Pentest） - 处理身份验证和路由 - 管理 WebSocket 连接

⚛️ React 前端设置

``` # 1️⃣ 导航至 React 应用 cd frontend_react # 2️⃣ 安装 Node.js 依赖 npm install # 3️⃣ 启动开发服务器 npm run dev ```

🐍 Python 后端设置（可选）

``` # 1️⃣ 创建虚拟环境 python -m venv venv # 2️⃣ 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 3️⃣ 安装依赖 pip install -r requirements.txt # 4️⃣ 设置环境变量 # Windows: set PYTHONPATH=%cd% set MODE=demo # Linux/macOS: export PYTHONPATH=$(pwd) export MODE=demo # 5️⃣ 启动后端服务器 (运行在端口 8000) python -m uvicorn backend.ids.serve.app:app --reload --host 0.0.0.0 --port 8000 ```

### 🔍 故障排除

常见问题与解决方案

| 问题 | 解决方案 | |-------|----------| | **端口已被占用** | `pkill -f uvicorn && pkill -f streamlit` | | **找不到模块** | `pip install -r requirements.txt --force-reinstall` | | **权限被拒绝** | `chmod +x start-aegis.sh` | | **找不到 Python** | 在 Windows 上使用 `py` 代替 `python` | | **虚拟环境问题** | 删除 `venv` 文件夹并重新创建 |

## 🏗️ 系统架构 ``` graph TB A[🌐 Network Traffic] --> B[📡 FastAPI Backend
Port 8000] B --> C[🧠 XGBoost ML Models] B --> D[📊 React Dashboard
Port 5173] B --> E[📈 Streamlit Dashboard
Port 8501] B --> F[🔌 WebSocket Stream] C --> G[🎯 Threat Detection] C --> H[📋 SHAP Explainability] D --> I[👤 Modern Web UI] E --> J[📊 ML Analytics] style B fill:#e1f5fe style C fill:#f3e5f5 style D fill:#e8f5e8 style E fill:#fff3e0 ``` ### 🔧 技术栈

**🔙 后端** - FastAPI + Uvicorn - XGBoost ML 模型 - WebSocket 流式传输 - SHAP 可解释性

**🎨 前端** - React + TypeScript - Streamlit 分析 - 实时更新 - 响应式设计

**🤖 ML 管道** - XGBoost 分类器 - 79% F1-Score - 多攻击检测 - 特征工程

## 📁 项目结构 ``` 🛡️ Aegis/ ├── 🔙 backend/ │ └── ids/ │ ├── serve/ │ │ ├── app.py # 🚀 FastAPI main application │ │ ├── detection_service.py # 🎯 ML detection engine │ │ └── stream.py # 🔌 WebSocket streaming │ ├── models/ │ │ ├── xgb_baseline.py # 🤖 XGBoost model training │ │ └── cnn_lstm.py # 🧠 Deep learning models │ └── config.yaml # ⚙️ System configuration ├── 🎨 frontend_react/ │ ├── src/ │ │ ├── components/ # ⚛️ React components │ │ ├── pages/ # 📄 Dashboard pages │ │ ├── hooks/ # 🪝 Custom React hooks │ │ └── theme/ # 🎨 Design system │ └── package.json # 📦 Node.js dependencies ├── 📊 frontend_streamlit/ │ └── aegis_dashboard.py # 📈 ML analytics dashboard ├── 🎯 artifacts/ │ ├── Syn/ # 🔥 SYN flood models │ ├── mitm_arp/ # 🕵️ MITM detection models │ └── baseline_ml_stateful/ # 📊 Ensemble models ├── 🌱 seed/ │ ├── alerts.json # 🚨 Demo alert data │ └── shap_*.json # 🔍 SHAP explainability ├── 📊 evaluation/ │ ├── phase1_dataset_evaluation.py # 📈 Model metrics │ ├── phase2_scenario_evaluation.py # 🎭 Scenario testing │ └── phase3_system_evaluation.py # 🏗️ System performance ├── 🚀 scripts/ │ ├── run_backend.sh # 🔙 Backend launcher │ ├── run_frontend.sh # 🎨 Frontend launcher │ └── train_*.sh # 🤖 Model training ├── 📋 requirements.txt # 🐍 Python dependencies ├── 🚀 start-aegis.sh # 🐧 Linux/macOS launcher ├── 🚀 start-aegis.bat # 🪟 Windows launcher └── 📖 README.md # 📚 This documentation ``` ## 🔧 手动设置 如果自动脚本不起作用： ``` # 1. 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 2. 安装依赖 pip install -r requirements.txt # 3. 设置环境变量 export PYTHONPATH=$(pwd) export MODE=demo # 4. 启动后端 (终端 1) uvicorn backend.ids.serve.app:app --reload --host 0.0.0.0 --port 8000 # 5. 启动仪表板 (终端 2) cd frontend_react npm install npm run dev ``` ## 🌐 访问 - **仪表板**：http://localhost:5173 - **后端 API**：http://localhost:8000 - **API 文档**：http://localhost:8000/docs ## 🛑 停止 在运行脚本的终端中按 `Ctrl+C`。 ## 📊 演示模式 系统默认以**演示模式**运行，该模式： - 每 2 秒生成随机的真实网络告警 - 启动时预加载 20 条种子告警 - 模拟各种攻击类型（DDoS、端口扫描、暴力破解等） 非常适合演示和测试！ ## ⚡ 实时监控与自动刷新 ### 架构设计 - **后端（端口 8000）**：7x24 小时连续运行，捕获流量并生成告警 - **仪表板（端口 5173）**：具有 5 个专用选项卡的 Web 界面 - **实时告警选项卡**：带有开关式自动刷新的实时威胁源 - **其他选项卡**：稳定的分析视图，无自动重新加载干扰 ### 自动刷新开关（实时告警选项卡） **实时告警**选项卡包含一个**“启用自动刷新”**复选框： - ✅ **启用**（默认）：每 2 秒自动获取新告警 - ⬜ **禁用**：显示当前告警，不自动更新 - 企业级设计允许 SOC 分析师暂停监控以进行详细调查 ### 如何使用 1. **实时监控**：导航至“实时告警”选项卡，确保勾选“启用自动刷新” 2. **全局刷新**：点击侧边栏中的“🔄 Refresh Dashboard”按钮（更新所有选项卡） 3. **浏览器刷新**：按 F5 重新加载整个应用程序 ### 生产部署 在真实的企业环境中： - 后端连接到网络传感器并 7x24 小时运行 - SOC 分析师在主动监控期间启用自动刷新 - 分析师可以暂停以调查特定威胁而不丢失上下文 - 其他选项卡保持稳定，以便进行不间断的深入分析 ## 🧠 ML 模型性能 ### 🎯 主要特征（SHAP 分析）

**🔥 最重要的特征** 1. `pkt_rate` - 每秒数据包数 (0.42) 2. `syn_ratio` - SYN 数据包比率 (0.31) 3. `byte_rate` - 每秒字节数 (0.25) 4. `flow_duration` - 连接持续时间 (0.18) 5. `avg_pkt_size` - 平均数据包大小 (0.14)

**🎭 检测到的攻击类型** - 🔥 **SYN Flood** - TCP SYN 攻击 - 🕵️ **MITM ARP** - ARP 欺骗攻击 - 🌐 **DNS Exfiltration** - 通过 DNS 的数据渗出 - 🚪 **Port Scanning** - 网络侦察 - 💥 **DDoS** - 分布式拒绝服务 - 🔓 **Brute Force** - 密码攻击

## 🔒 安全功能 ## 📊 演示模式功能

### 🎭 **模拟能力** - **真实的流量模式**，具有统计变化 - **多攻击场景**，跨越不同协议 - **基于时间的攻击序列**，用于测试 - **可配置的告警频率**（1-3 秒）

### 📈 **分析与监控** - **实时性能指标**及模型准确率 - **攻击分布图**（按类型和严重性） - 威胁模式的**时间序列可视化** - 每次检测的**SHAP 可解释性**

## 🐛 故障排除

🔧 常见问题

### 端口已被占用 ``` # 终止现有进程 pkill -f uvicorn pkill -f streamlit pkill -f node # 或者在 Windows 上： taskkill /f /im python.exe taskkill /f /im node.exe ``` ### Python/模块问题 ``` # 重新安装依赖 source venv/bin/activate # Linux/macOS # 或 venv\Scripts\activate # Windows pip install -r requirements.txt --force-reinstall ``` ### 权限被拒绝 ``` # Linux/macOS: chmod +x start-aegis.sh chmod +x scripts/*.sh # Windows: 以管理员身份运行 ``` ### 虚拟环境问题 ``` # 删除并重建 rm -rf venv # Linux/macOS # 或 rmdir /s venv # Windows python -m venv venv ``` ### WSL/Ubuntu 设置 ``` # 在 PowerShell (Windows) 中 wsl --install -d Ubuntu wsl --list --verbose # 然后在 WSL Ubuntu 中： cd /mnt/c/path/to/aegis ./start-aegis.sh ```

## 🚀 开发

🛠️ 开发设置

### 后端开发 ``` # 安装开发依赖 pip install -r requirements.txt pip install pytest black flake8 # 运行测试 pytest # 格式化代码 black backend/ # 启动并热重载 uvicorn backend.ids.serve.app:app --reload --port 8000 ``` ### 前端开发 ``` # React 开发 cd frontend_react npm install npm run dev # Streamlit 开发 cd frontend_streamlit streamlit run aegis_dashboard.py --server.runOnSave true ``` ### 模型训练 ``` # 训练所有模型 ./scripts/train_ids.sh # 训练特定模型 python backend/ids/models/xgb_baseline.py ```

## 📈 路线图

### ✅ **已完成** - [x] 实时 ML 检测引擎 - [x] 双仪表板系统（React + Streamlit） - [x] WebSocket 流式传输 - [x] SHAP 可解释性 - [x] 多攻击类型支持 - [x] 具有真实数据的演示模式

### 🔄 **进行中** - [ ] 数据库持久化（PostgreSQL） - [ ] 用户身份验证与 RBAC - [ ] 告警关联引擎 - [ ] 自定义规则引擎 - [ ] 移动端响应式设计 - [ ] Docker 容器化

### 🎯 **未来增强** - **🤖 自动化渗透测试** - AI 驱动的安全评估 - **💬 安全聊天机器人** - 自然语言威胁分析 - **📊 高级分析** - 预测性威胁建模 - **🔗 SIEM 集成** - 企业安全平台连接 ## 📄 许可证 ``` MIT License - See LICENSE file for details ``` ## 👥 贡献者 ## 🙏 致谢

标签：AI安全, AMSI绕过, AV绕过, Chat Copilot, CISA项目, DDoS检测, FastAPI, Kubernetes, Python安全工具, React, SHAP可解释性, SQL注入检测, Streamlit, Syscalls, WebSocket, XGBoost, 企业安全, 依赖分析, 免杀技术, 入侵检测系统, 全栈安全, 告警关联, 威胁情报, 威胁检测, 安全数据湖, 安全运营中心, 实时流分析, 密钥泄露防护, 开发者工具, 插件系统, 暴力破解检测, 机器学习安全, 端口扫描检测, 网络安全, 网络映射, 网络资产管理, 访问控制, 逆向工具, 隐私保护