hicran-cansever/xai-nids-cyber-radar

# NIDS Cyber Radar 具备可解释 AI 的网络入侵检测系统。实时分类原始网络流量数据包，并通过 SHAP 值向 SOC 分析师呈现每次决策背后的推理过程。 本项目为 CENG 3544（计算机与网络安全）课程项目，涵盖机器学习、可解释 AI 和 MLOps。 ## 核心特性 | 功能 | 详情 | |---|---| | 34 种网络威胁类别 | DDoS、SQL Injection、XSS、Port Scan 等 | | XAI 决策依据 | 基于每次预测生成 SHAP 局部解释 | | 一键部署 | `docker-compose up --build` | | SHA-256 模型签名 | 针对文件篡改进行完整性校验 | | 98.41% ROC-AUC | 34 类宏平均 One-vs-Rest 评估 | ## 工作原理 ### 智能提取（数据流水线） **模块：** [`src/data_loader.py`](src/data_loader.py) CIC-IoT-2023 包含 63 个以上的 CSV 文件。直接加载会导致 OOM 崩溃，且占据主导地位的 `BENIGN` 类会导致模型忽略罕见攻击。该流水线通过四个阶段处理此问题： 1. **防泄漏保护**：删除类似索引的列（`Number`、`Unnamed:0`） 2. **目标检测**：自动查找标签列 3. **分层二次抽样**：每类最多抽取 2000 个样本，保留罕见攻击的代表性 4. **RAM 压缩**：将 `int64` 向下转换为 `int8/16/32`，将 `float64` 向下转换为 `float32`，内存占用减少 40-60% 固定的 `random_state=42` 确保完全可复现性。 ### Optuna 超参数优化 **模块：** [`src/train_model.py`](src/train_model.py) 使用 Optuna 的 TPE 采样器对树的数量、深度、分裂/叶子节点阈值以及特征选择策略进行搜索。优化器通过 3 折交叉验证以 Macro F1 为目标。 选定配置：250 棵树，平衡的类别权重。LabelEncoder 仅在训练数据上执行 `fit()` 以防止泄漏。 | 指标 | 分数 | |---|---| | Macro ROC-AUC (OvR) | 98.41% | | 总类别数 | 34 | | 数据集划分 | 分层 80/20 | ### Schema 对齐 **模块：** [`src/poc_ui.py`](src/poc_ui.py), [`src/xai_explainer.py`](src/xai_explainer.py) 实时流量到达时的列数或顺序可能与训练期间使用的 38 特征模板不同。Schema 锁定会用零填充缺失的列，并重新排序以完全匹配训练布局。如果没有此步骤，模型会悄无声息地产生错误的预测。 ### SHAP 可解释性 **模块：** [`src/xai_explainer.py`](src/xai_explainer.py), [`src/poc_ui.py`](src/poc_ui.py) 两种模式： - **全局**：在 300 个样本的子集上运行 TreeExplainer，生成整体特征重要性图表 - **局部**：逐数据包的 SHAP 向量显示哪些特征驱动了特定的分类（红色 = 增强，蓝色 = 减弱） ### SHA-256 模型签名 **模块：** [`src/utils.py`](src/utils.py) 未签名的 `.pkl` 文件是已知的攻击媒介（OWASP A08:2021）。保存时，SHA-256 摘要会写入 sidecar 文件中。每次加载时都会重新计算并比较哈希值。如果不匹配，将引发 `SecurityError` 并阻止加载。 ## 项目结构 ``` ├── Dockerfile ├── docker-compose.yml ├── config.yaml ├── requirements.txt │ ├── src/ │ ├── data_loader.py # Stratified sub-sampling + RAM compression │ ├── train_model.py # Optuna TPE + Random Forest + SHA-256 serialization │ ├── xai_explainer.py # Global SHAP summary (300 DPI) │ ├── poc_ui.py # Streamlit SOC terminal │ └── utils.py # Path/config/logging/SHA-256 security layer │ ├── models/ │ ├── nids_champion_model.pkl # ~305 MB trained model (250 trees) │ ├── nids_champion_model.pkl.sha256 │ ├── label_encoder.pkl │ └── label_encoder.pkl.sha256 │ └── data/ ├── confusion_matrix.png ├── shap_summary_plot.png └── merged/ # CIC-IoT-2023 CSV files ``` ## 设置 ### Docker（推荐） ``` git clone https://github.com/hicran-cansever/xai-nids-cyber-radar.git cd xai-nids-cyber-radar # 从 GitHub Releases (v1.0.0) 下载训练好的模型到 models/ docker-compose up --build ``` 当容器就绪时打开 http://localhost:8501。 | 参数 | 值 | |---|---| | 端口 | `8501:8501` | | 数据卷 | `./data`, `./models`, `./logs` | | 重启策略 | `unless-stopped` | | 健康检查 | `curl http://localhost:8501/_stcore/health` | ### 手动（不使用 Docker） ``` python -m venv venv .\venv\Scripts\activate # Windows # source venv/bin/activate # Linux/macOS pip install -r requirements.txt # (可选) 重新训练 python src/train_model.py # (可选) 生成全局 SHAP 图 python src/xai_explainer.py # 启动 streamlit run src/poc_ui.py ``` ## 配置 所有参数均位于 [`config.yaml`](config.yaml)： ``` data: max_files_train: 63 max_files_xai: 2 test_size: 0.2 random_state: 42 model: n_estimators: 100 # fallback if Optuna is disabled max_depth: null class_weight: "balanced" optuna_trials: 5 # 0 = disabled, 20+ = full optimization xai: sample_size: 300 max_display_features: 10 top_n_local_features: 12 labels: benign_keyword: "BENIGN" ``` ## 训练好的模型 模型文件（约 305 MB）不在仓库中。请从 [Releases (v1.0.0)](../../releases/tag/v1.0.0) 下载并放在 `models/` 目录下。必须包含 SHA-256 sidecar 文件；如果哈希不匹配，系统将拒绝加载。 ## 技术栈 Python 3.10、Streamlit 1.32、scikit-learn 1.4、Optuna 3.5、SHAP 0.45、Pandas、NumPy、Docker ## 许可证 MIT

标签：Apex, Kubernetes, MLOps, 可解释AI, 安全运营中心, 机器学习, 网络入侵检测系统, 网络映射, 网络流量分析, 请求拦截, 逆向工具