omerfarooq223/shap-agentic-ids

# 🛡️ 基于SHAP解释的 Agentic IDS ### *通过可解释 AI 与 Agentic 推理变革网络安全*        ## 📖 概述 本项目实现了一个专为现代安全运营中心 (SOC) 设计的**混合入侵检测系统 (IDS)**。它弥合了高性能“黑盒”机器学习与具有可操作性的人类可读安全分析之间的差距。 该系统利用 **Random Forest** 分类进行高速检测，利用 **SHAP** (SHapley Additive exPlanations) 实现透明度，并利用基于 **LangGraph** 的 Agent 进行智能验证和情境化。与仅标记威胁的传统系统不同，该平台解释了*为什么*某个流量被标记，并根据实时威胁情报提供修复步骤。 **v2.5 新特性：** 集成了**自动化红队评估框架**，其中 AI Agent（Attacker 和 Critic）持续对 Defender 进行压力测试，以发现并修复“隐蔽的”绕过漏洞。 ## 🏗️ 系统架构 核心逻辑遵循使用 **LangGraph** 实现的非线性推理流水线： ``` flowchart LR Capture[Live Packet Capture] --> Stream[Streaming API] RedTeam[Adversarial Attacker] --> Stream Stream --> Detect[ML Detection Engine] Detect --> Explain[SHAP Explainer] Explain --> Reason[LangGraph Reasoning] Reason --> Alert[Actionable SOC Alert] Reason <--> Intel[(AbuseIPDB / MITRE ATTACK)] Alert --> Dashboard[SOC Dashboard] Dashboard --> Chat[RAG Forensic Chat] Alert --> Voice[Voice Assistant] Alert --> Lab[Snort / Suricata Lab] Chat <--> KB[(data/knowledge/)] Critic[Critic Agent] -->|Feedback| RedTeam Alert --> Critic style Capture fill:#d9ecff,stroke:#0f4c81,stroke-width:2px,color:#102a43 style Stream fill:#d9ecff,stroke:#0f4c81,stroke-width:2px,color:#102a43 style Detect fill:#dff3e4,stroke:#1f6b3a,stroke-width:2px,color:#102a43 style Explain fill:#dff3e4,stroke:#1f6b3a,stroke-width:2px,color:#102a43 style Reason fill:#fff2cc,stroke:#8a5b00,stroke-width:2px,color:#102a43 style Alert fill:#ffe0e0,stroke:#b42318,stroke-width:2px,color:#102a43 style Dashboard fill:#d9ecff,stroke:#0f4c81,stroke-width:2px,color:#102a43 style Voice fill:#d9ecff,stroke:#0f4c81,stroke-width:2px,color:#102a43 style Lab fill:#d9ecff,stroke:#0f4c81,stroke-width:2px,color:#102a43 style Critic fill:#ffe0e0,stroke:#b42318,stroke-width:2px,color:#102a43 style Intel fill:#fff2cc,stroke:#8a5b00,stroke-width:2px,color:#102a43 ``` 有关更详细的、以文本为主的架构剖析，请参见 [docs/SYSTEM_ARCHITECTURE.md](docs/SYSTEM_ARCHITECTURE.md)。 ## 🚀 核心特性 * **可解释 ML (XAI)：** 集成的 SHAP 层为每个警报提供数学证明，将原始网络特征（熵、端口、持续时间）映射到贡献得分。 * **Agentic 自我修正：** LangGraph 推理引擎使用 **Llama 3.3（通过 Groq）** 根据实时声誉数据验证 ML 输出，并解决模型预测与网络逻辑之间的冲突。 * **自动化红队评估：** 一个多 Agent 对抗框架，其中 **Attacker** 生成 payload，**Critic** 分析防御日志以教导攻击者如何绕过 IDS，从而创建一个持续加固的循环。 * **实时威胁情报：** 通过 **AbuseIPDB** 进行自动化的 IP 声誉检查，并自动映射到 **MITRE ATT&CK** 战术和技术。 * **真实的数据包捕获与流式 API：** 基于原生 Scapy 的嗅探器 (`packet_capture.py`) 用于实时接口捕获，结合高度并发的 REST Streaming API (`streaming_api.py`) 用于连续的线速数据包分析。 * **真实的 Snort/Suricata 对比：** 集成了并排的行为取证实验室 (`snort_comparison.py`)，以针对传统的基于签名的规则对 LLM Agent 进行基准测试（满足 Tier S 要求）。 * **基线分类器与效率基准测试：** `scripts/run_evaluation.py` 使用 Accuracy、Precision、Recall、F1、ROC-AUC、训练时间、推理延迟、峰值训练内存、序列化模型大小以及各攻击类别的指标来比较 Logistic Regression、GaussianNB、MultinomialNB、ComplementNB、Decision Tree、Random Forest 和可选的 XGBoost。 * **取证实验室报告：** React 取证实验室显示 Snort/Suricata 对比、模型基线排行榜、效率权衡以及来自生成的基准测试报告的各攻击类别 Random Forest 诊断。 * **实时 SOC 仪表板：** 一个高级的基于 React 的界面，具有 3D 威胁地球仪、RAG 驱动的取证聊天和高密度遥测功能。 * **语音驱动的安全助手：** 集成的语音警报系统使用后端（macOS `say`）和前端（Web Speech API）语音合成，为 SOC 分析师提供免手动操作的威胁报告。 * **跨数据集的实证验证：** 系统性能在异构数据集（CICIDS2017 和 UNSW-NB15）中进行了严格测试，以确保模型的泛化能力以及对新型攻击模式的鲁棒性。 ## 🛠️ 安装与设置 ### 1. 环境要求 - **Python 3.11+** - **Node.js 18+**（用于前端） - **API Keys：** Groq（用于 LLM）和 AbuseIPDB（用于威胁情报） ### 2. 后端设置 ``` # 创建并激活虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 配置环境 cp .env.example .env # 使用您的 GROQ_API_KEY 和 ABUSEIPDB_API_KEY 编辑 .env # 开发默认值：INTERNAL_API_KEY 和 FRONTEND_ORIGIN 已在 .env.example 中预填 ``` ### 前端环境 ``` cd frontend cp .env.example .env.local # 仅 VITE_API_URL —— API key 在 dashboard 解锁界面输入（不存储在前端 bundle 中） ``` ### 3. 前端设置 ``` cd frontend npm install ``` ## 🚦 使用指南 ### 1. 数据准备与训练 在运行系统之前，初始化 ML 流水线： ``` # 合并原始数据集 (CICIDS2017) python src/merge_data.py # 训练 Random Forest + SHAP Explainer python src/train.py ``` ### 2. 启动系统 ``` # 为本地开发启动 Flask Backend（默认端口 5005） python run_flask.py # 生产环境 (Gunicorn + WSGI) # gunicorn -c gunicorn.conf.py # 启动 React Dashboard（在单独的终端中） cd frontend npm run dev ``` ### 3. 运行基准测试 为取证实验室生成实证数据： ``` python scripts/run_evaluation.py ``` 这会将基线/效率对比写入 `docs/BASELINE_EFFICIENCY_COMPARISON.md` 和 `docs/baseline_efficiency_results.json`。 有关生成更新的幻灯片，请参见 `docs/NOTEBOOKLM_SLIDE_SOURCES.md`。 ### 4. 自动化红队评估（对抗战斗） 运行多 Agent 战斗（Attacker 对抗 Defender）： ``` # 运行 3 轮战斗以对 IDS 进行压力测试 python scripts/red_team_battle.py 3 ``` ## 🌐 部署 该系统**可在免费云平台上实现 95% 的部署**，仅受限于 API 的速率限制。 ### 快速部署（5 分钟） 1. **后端：** 部署到 [Render.com](https://render.com)（免费层，项目数量不限） 2. **前端：** 部署到 [Vercel](https://vercel.com)（免费层） 3. **API：** 使用 GROQ（100K token/天）+ AbuseIPDB（1000 次请求/天）的免费额度 4. **成本：** 对于小流量，每月 $0 有关详细的部署说明，请参见 [**DEPLOYMENT.md**](DEPLOYMENT.md)。它包含将后端部署到 Render 并将前端部署到 Vercel 的重点且最新的步骤，以及环境变量和模型指南。 ## 📂 项目结构 ``` IS Project/ ├── src/ # Core Backend Logic │ ├── agent.py # LangGraph Reasoning Engine for Threat Verification │ ├── attacker.py # Adversarial Agent for Red Teaming (New) │ ├── critic.py # Analysis Agent for Adversarial Feedback (New) │ ├── app.py # Flask API Application & REST Endpoints │ ├── config.py # Central System Settings & Environment Variables │ ├── data_loader.py # Feature Translation & Dataset Parsing │ ├── evaluation_metrics.py# Model Accuracy and Testing Metrics Helper │ ├── merge_data.py # Utility for Merging CICIDS CSV Distributions │ ├── packet_capture.py # Live Scapy-based Network Sniffer & PCAP Extractor │ ├── schemas.py # Pydantic Schemas for Strict Data Validation │ ├── snort_comparison.py # Real Snort/Suricata Rule Benchmarking Engine │ ├── streaming_api.py # Async Streaming API for Continuous Network Detection │ ├── train.py # Random Forest ML Training & SMOTE Pipeline │ └── services/ # Decoupled Business Logic / Abstraction Layer │ ├── geo_service.py # Map IPs to Geolocation via APIs │ ├── inference.py # SHAP TreeExplainer & RF ML Prediction Engine │ ├── persistence.py # JSON Alert Logging & Data Persistence │ ├── rag_service.py # TF-IDF RAG retrieval for forensic chat │ ├── red_team_service.py # Red team battle orchestration │ └── voice_service.py # Audible Security Alert System ├── frontend/ # React + Vite SOC Dashboard Website │ ├── src/ # Frontend Application Code │ │ ├── components/ # Reusable React UI (Dashboard, ChatWidget w/ RAG sources, …) │ │ ├── utils/ # API Communication Handlers │ │ ├── ThreatGlobe.jsx # 3D Three.js Live Attack Geolocation Map │ │ ├── Analytics.jsx # Reporting, Visualizations & Metrics Dashboard │ │ └── App.jsx # Main React App Core & Routing │ └── package.json # Frontend deps (`npm run test` — Vitest + Testing Library) ├── scripts/ # Research, Utilities & Report Scripts │ ├── run_evaluation.py # Cross-Dataset Baseline + Efficiency Benchmarking │ └── red_team_battle.py # Autonomous Adversarial Loop Engine (New) ├── tests/ # Pytest Unit & Integration Testing Suite │ ├── test_flask_api.py # System API Endpoint Checks │ ├── test_agent_steps.py # Tests for LangGraph Node Functionalities │ └── test_integration_e2e.py # End-to-End full system logic tests │ └── test_rag_service.py # TF-IDF knowledge retrieval unit tests ├── data/ # Datasets (CICIDS2017 & UNSW-NB15) │ └── knowledge/ # RAG markdown playbooks (MITRE, benchmarks, threat patterns) ├── models/ # Serialized models (`rf_model.pkl`, `scaler.pkl`, `model_metadata.json`) ├── wsgi.py # Production WSGI entry (`gunicorn -c gunicorn.conf.py`) ├── gunicorn.conf.py # Gunicorn bind/workers configuration ├── docs/ # Full Technical Reporting & Academic Documentation │ ├── API.md # REST API Interface Spec Details │ ├── SYSTEM_ARCHITECTURE.md # Architecture Blueprints │ └── FINAL_COMPREHENSIVE_REPORT.md # Academic Grading Project Report ├── logs/ # System Threat & Error Runtime Logging Outputs ├── QUICK_START.md # Easy Step-by-Step Setup Guide ├── run_flask.py # Core Entry Point script to boot backend application └── requirements.txt # Python Backend Dependencies File ``` ## 🛡️ 安全与加固 - **API 安全：** 特权路由接受有效的 `X-API-KEY` 请求头（`INTERNAL_API_KEY`，在生产环境中长度需 32+ 字符）、经过身份验证的 Flask 会话，或由 `POST /api/v1/auth/login` 返回的已签名浏览器会话 token。React 仪表板无需在前端 bundle 中发送 API 密钥即可解锁。 - **运行时验证：** `ENVIRONMENT=production` 在启动时强制执行 `INTERNAL_API_KEY`、`FRONTEND_ORIGIN` 及相关检查 (`validate_runtime_config()`)。 - **速率限制：** 通过 `Flask-Limiter` 强制执行，以防止针对 LLM 推理引擎的 DoS 攻击。 - **优雅降级：** 自适应的动态队列深度负载削减（例如 `>2000` 时降至 Layer 1 快速路径）可安全维持吞吐量，并在系统遭受大规模容量型 DDoS 攻击时充当防泛滥保障。 - **防御解释操纵：** 跨信号验证 (CSV) 将 SHAP 值与外部不可变的网络逻辑进行交叉核对，提供了一种对抗对抗性机器学习可解释性漏洞利用的固有机制。 - **输入验证：** 严格的 Pydantic schema 强制执行类型安全和特征范围验证。 - **CORS 保护：** 锁定 Origin 配置以防止未经授权的跨站请求。 ## 🛑 局限性与未来工作 - **范围外的攻击（无深度包检测）：** 由于流水线严格使用 12 项特征的流统计数据，深度嵌入的 payload 级漏洞利用（例如，零日远程代码执行、加密的应用层恶意软件、SQLi payload）不在范围内。**未来集成：** 深度包检测 (DPI) 结合多模态 LLM 功能将直接分析基于文本的 payload，以捕获混淆的应用层攻击。 **开发者：** Muhammad Umar Farooq **许可证：** MIT

标签：Apex, Beacon Object File, IP 地址批量处理, Python, React, Syscalls, 入侵检测系统, 可解释性AI, 多智能体, 安全数据湖, 无后门, 机器学习, 网络安全, 逆向工具, 隐私保护