Kanwardeep-Singh/GridGuard-AI

# GridGuard AI **一个多智能体智能电网安全 copilot：面向 IEC 61850/MMS 工业控制系统的 ML 异常检测 + LLM agent 调查。** 本项目是我在 Friedrich-Alexander-Universität Erlangen-Nürnberg 的硕士学位论文的工程扩展，论文题目为*"基于 AI 的异常检测与 ICS 协议集成的智能电网"*。该论文在一个模拟的智能电网测试平台中构建了一个用于 MMS 流量的机器学习异常检测器。本仓库在该检测器之上封装了一个多智能体 LLM 层，负责调查每一个被标记的异常、检索相关的 ICS 安全上下文、评估风险并推荐响应措施——从而将原始的异常评分转化为 SOC 分析师可据以采取行动的事件报告。 ## 架构 ``` ┌─────────────────────┐ MMS Traffic ──▶ │ Feature Engineering │ (real or └──────────┬───────────┘ synthetic) ▼ ┌─────────────────────┐ │ Anomaly Detection │ Isolation Forest + Local Outlier │ (ensemble) │ Factor, ensemble union/threshold └──────────┬───────────┘ ▼ (flagged event) ┌─────────────────────────────────────────────┐ │ Agent Orchestrator (LangGraph) │ │ │ │ Detection ─▶ ICS Knowledge (RAG) ─▶ │ │ Root Cause ─▶ Risk Assessment ─▶ Response │ └──────────────────────┬────────────────────────┘ ▼ Incident Report (JSON) ▼ Power Automate webhook ─▶ Teams / Email ``` ## 已实现与概念性功能 | 组件 | 状态 | 备注 | |---|---|---| | 特征工程（时间 + 网络特征） | ✅ 已实现 | `detection/feature_engineering.py` | | Isolation Forest + LOF 集成检测器 | ✅ 已实现并测试 | `detection/` | | 合成 MMS 流量生成器（DoS/MITM/FDI/重放） | ✅ 已实现 | `data/generate_synthetic_data.py` — MATLAB/Simulink 路径的 Python 替代方案，详见下文 | | 多智能体 pipeline（5 个 agent + orchestrator） | ✅ 已实现并测试 | `agents/`，基于 LangGraph 构建 | | 与提供商无关的 LLM 客户端（Anthropic / OpenAI / mock） | ✅ 已实现 | `agents/llm_client.py` — mock 提供商无需 API 密钥 | | RAG 知识检索（NIST + MITRE ATT&CK for ICS） | ✅ 已实现 | TF-IDF + FAISS，请参阅下方的注意事项 | | FastAPI 服务（`/detect`，`/incidents/investigate`） | ✅ 已实现并测试 | `api/` | | Power Automate → Teams/邮件 webhook | ✅ 代码已实现，**未经实时测试** | 需要您自己的 Power Automate 租户和流 URL | | Docker / docker-compose | ✅ 已编写，**未在此环境中进行构建测试**（此处无 Docker daemon 可用） | 标准的精简版 Python 镜像；在本地应该能顺利构建 | | CI（GitHub Actions） | ✅ 已实现 | 在推送/PR 时运行 pytest + Docker 构建 | | MATLAB/Simulink 数据生成 | 📝 来自原论文，此处未复现 | 请参阅下方的注意事项 | | Azure 云部署 | 📝 未实现 | 作为下一步说明，未包含在此仓库中 | | 数字孪生、自主修复、Sentinel 集成 | 📝 未来工作 | 特意将其排除在此原型的范围之外 | ### 值得注意的注意事项 - **MATLAB/Simulink → Python 合成数据。** 论文使用了基于 Simulink 建模的变电站测试平台来生成带标签的训练数据。这需要 MATLAB 许可证和经过验证的电网模型，将其打包到开源仓库中并不现实。`data/generate_synthetic_data.py` 是一个从头编写的 Python 生成器，能为正常流量和四种攻击类别（DoS、MITM、FDI、重放）产生具有统计学差异的特征分布，因此任何人只需克隆此仓库，就可以运行并测试 pipeline 的其余部分。它**不是**真实电网模拟数据的经验证替代品——请将其视为开发和演示的辅助工具，并在拥有真实数据捕获后，通过同一文件中的 `load_real_traffic()` 将其替换。 - **RAG 知识库。** ICS 知识 agent 从公开的 NIST SP 800-82 和 MITRE ATT&CK for ICS *摘要笔记*（为该仓库编写的原始文本——并非源文件的复制）中进行检索。实际的 IEC 61850 标准是 IEC 的付费出版物，因此未在此处进行索引。如果您拥有许可访问权限，请将您自己的 `.txt` 笔记放入 `rag/knowledge_base/` 并重建索引（`python -m rag.vectorstore`）。 - **检索使用 TF-IDF，而不是托管的 embedding 模型。** 这是一个经过深思熟虑的选择，这样整个 pipeline——包括 RAG——就可以在零 API 密钥和零外部调用的情况下运行。如果您在使用实时 LLM 提供商时希望获得更高质量的检索结果，请将 `rag/vectorstore.py` 替换为真实的 embedding 模型。 - **Mock LLM 提供商。** 默认情况下（`LLM_PROVIDER=mock`），agent 会使用基于确定规则替代方案，而不是真实的 LLM 调用，因此整个系统（包括 CI）无需任何 API 密钥即可运行和测试。它对输入特征执行简单的关键词/阈值启发式处理（例如，高 `request_rate` → DoS），以生成连贯的演示报告；它并没有进行真正的推理。请在 `.env` 中设置 `LLM_PROVIDER=anthropic` 或 `openai` 并填入真实密钥，以实现实际的 LLM 驱动的调查。 - **Power Automate 交付**如果没有您自己的 Microsoft 365 租户和配置好的流，则无法进行演练。webhook 代码是真实的，会将事件报告 JSON POST 到您配置的任何 URL；而 Power Automate 端的 Teams/邮件扇出连接则需要您自行配置。 ## 仓库结构 ``` GridGuard-AI/ ├── agents/ # Detection, Root Cause, ICS Knowledge, Risk, Response agents + orchestrator ├── api/ # FastAPI app and routes ├── automation/ # Power Automate webhook integration ├── config/ # config.yaml + settings loader ├── data/ # synthetic MMS traffic generator ├── detection/ # feature engineering + Isolation Forest / LOF ensemble ├── rag/ # knowledge base ingestion, TF-IDF/FAISS vector store, retriever ├── scripts/ # end-to-end demo script ├── tests/ # pytest suite (14 tests, all passing) ├── Dockerfile / docker-compose.yml └── .github/workflows/ci.yml ``` ## 快速开始 ``` git clone https://github.com/Kanwardeep-Singh/GridGuard-AI.git cd GridGuard-AI python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # defaults to LLM_PROVIDER=mock, no key needed ``` 运行端到端演示（合成数据 → 检测 → agent 调查）： ``` python scripts/run_pipeline.py ``` 运行测试套件： ``` pytest tests/ -v ``` 运行 API： ``` uvicorn api.app:app --reload --port 8000 # 交互式文档位于 http://localhost:8000/docs ``` 或者使用 Docker： ``` docker compose up --build ``` 要使用真实的 LLM 而不是 mock 提供商，请在 `.env` 中设置： ``` LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-... ``` ## 事件报告示例 这是 `scripts/run_pipeline.py` 针对合成流量（mock LLM 提供商）的演示输出——并非基准测试的生产结果： ``` { "attack_type": "Denial of Service", "protocol": "MMS", "target": "NAN-Gateway", "severity": "High", "confidence": 0.8, "impact": "Communication disruption / potential loss of protective function", "recommended_actions": [ "Isolate affected asset from the control network segment", "Enable enhanced monitoring on related IEDs", "Notify on-call ICS security engineer" ], "root_cause": "Traffic pattern consistent with a Denial of Service attempt: elevated request rate with reduced packet size.", "knowledge_references": ["..."] } ``` ## 论文渊源 本仓库扩展了我论文工作中的异常检测核心部分： - 针对 MMS 协议通信数据进行特征工程，以提取时间维度和网络层面的异常信号。 - 基于 ML 对 DoS、MITM、False Data Injection 和重放攻击进行检测。 - 通过 precision/recall/F1/detection-latency 等指标进行评估（有关此处使用的合理性边界检查，请参阅 `tests/`；完整的基准测试数据属于论文文档本身，而非本仓库）。 此扩展的新增部分是顶部的 agent 层：GridGuard AI 不会停留在异常评分上，而是调查*为什么*某些内容被标记，引入 ICS 安全上下文，对风险进行评分，并提出响应建议——这更贴近 SOC 分析师工作流程的实际需求。 ## 许可证 MIT — 请参阅 `LICENSE`。

标签：DLL 劫持, 大语言模型, 安全运营中心, 工业控制系统安全, 异常检测, 智能电网, 网络映射, 自动化响应, 请求拦截, 逆向工具