s-shahzad/Universal-NIDS

# 通用 NIDS **混合网络入侵检测，附带经证据支持的实验室验证。** Universal NIDS 是一个以研究为先的入侵检测工作区，它将实时数据包捕获、离线 PCAP 重放、可选的 Suricata/Zeek 适配器摄取、静态工件分析、多引擎检测、留存证据以及面向分析师的报告统一在一个代码库中。它的构建旨在展示的不仅是它能检测到什么，还包括它在实际条件下的行为表现以及其当前的边界在哪里。 ## 架构 ``` +--------------------+ +--------------------+ +---------------------------+ | INPUT SOURCES | ---> | INGEST LAYER | ---> | PARSE / NORMALIZE | |--------------------| |--------------------| |---------------------------| | Live NIC capture | | Live capture | | Packet parsing | | Offline PCAP replay| | Offline replay | | Flow normalization | | Suricata JSON | | Adapter ingest | | Event shaping | | Zeek JSON | | Artifact intake | | Common schema output | | Artifact / file | +--------------------+ +-------------+-------------+ +--------------------+ | v +---------------------------+ | FEATURE EXTRACTION | +-------------+-------------+ | v +-------------------------------------------+ | DETECTION ENGINES | |-------------------------------------------| | Signature rules (YAML) | | Statistical anomaly (EWMA / z-score) | | Supervised ensemble (RF + ET + HGB + XGB)| | Unsupervised (IsolationForest + AE) | | Fusion engine (combined risk score) | +-------------------+-----------------------+ | v +-----------------------------------------------+ | SUPPRESSION + RETENTION | |-----------------------------------------------| | Alert suppression with audit log | | SQLite (nids.db) + JSONL (alerts / flows) | +-------------------+---------------------------+ | v +---------------------------------------------------+ | ANALYTICS + REPORTING | |---------------------------------------------------| | Live dashboard (WebSocket + HTTP fallback) | | Offline graphs and visual analytics | | Incident / SLA / threshold tuning reports | | AI-assisted triage (local LLM, no data egress) | +---------------------------------------------------+ ``` ## 功能 | 领域 | 支持内容 | |------|-------------------| | **摄取** | 实时网卡捕获，离线 PCAP 重放，Suricata/Zeek JSON 适配器 | | **工件分析** | 无需文件执行的静态分诊 — PE, PDF, Office, 脚本 | | **检测** | 签名规则，统计异常 (EWMA/z-score/DNS 突发)，监督式集成 (RF + ET + HGB + XGB)，可选的无监督 (IsolationForest + 自编码器)，融合评分 | | **留存** | SQLite，每次运行的 JSONL (警报、流、指标)，训练好的模型 pickle | | **仪表盘** | 实时 WebSocket 仪表盘，支持事件确认/抑制操作，传感器比较，异常趋势带，漂移警报，URL 持久化过滤器 | | **报告** | 事件报告，每周 SLA 摘要，阈值调优指南，可视化分析 | | **AI 分诊** | 针对现有运行文件夹的本地 LLM 分诊 — 数据不会离开本机 | | **实验室** | 通过 `adversary_lab` 进行对抗重放场景（可选，GPL 许可 — 参见 [许可协议](#licensing)） | ## 快速开始 ### 前置条件 - Python 3.10+ - Linux 或 Windows（实时捕获需要适当的权限） ### 安装 ``` git clone https://github.com//nids.git cd nids python -m venv .venv # Linux/macOS source .venv/bin/activate # Windows .venv\Scripts\activate pip install -r requirements.txt ``` ### 针对 PCAP 目录运行离线检测 ``` python -m nids run --pcap-dir pcaps --rules rules/rules.yml ``` ### 运行实时捕获 ``` # Linux（需要提升权限以进行 packet capture） sudo python -m nids run --interface eth0 --rules rules/rules.yml ``` ### 运行完整的混合堆栈（签名 + 异常 + 监督式 + 无监督） ``` python -m nids run --pcap-dir pcaps --labels pcaps/labels.csv --unsupervised ``` ### 打开实时仪表盘 ``` python -m nids dashboard --from-db output/nids.db --host 127.0.0.1 --port 8000 ``` 然后在浏览器中打开 `http://127.0.0.1:8000/dashboard`。 ### 生成事件报告 ``` python -m nids report --from-db output/nids.db --out reports/summary.md ``` ### 在现有的运行文件夹上运行 AI 辅助分诊（本地 LLM，无网络流出） ``` # Windows .\nids-triage.cmd "output\" # 输出：同一文件夹中的 triage_.json + triage__report.md ``` ### 训练并评估监督式集成模型 ``` python -m nids train --from-db output/nids.db --out models/model.pkl python -m nids evaluate --from-db output/nids.db --model models/model.pkl --out reports/ml_evaluation.json ``` ## 验证概览 本项目将验证视为一等输出。当前的基线： | 指标 | 结果 | |---------|-------:| | 收集的测试套件 | 152 | | 默认套件结果 | 144 个通过，8 个取消选择 | | 活跃的 pytest 警告 | 0 | | 代码覆盖率 | 79.16% | | 覆盖率底线（强制执行） | 72% | | 最新离线实验室场景通过数 | 5 | | 最新预备环境通过数 | 17 个清单中的 10 个 | | 良性压力测试（已调优） | 1,416 个流 — 0 警报 | | 试运行压力测试 | 4,742 个流 — 0 警报，900 秒试运行中重启延迟为 13.3 秒 | **精选预备环境亮点：** - `PREP-ENV-003` — 留存的队列深度和丢包证据（压力下 99.7% 丢包率，已正确计算） - `PREP-ENV-005` — 误报判定：应用了有针对性的无监督调优更改，重新运行 1,416 个良性流，达到 0 警报 - `LAB-SCN-005` — 结合网络与工件证据：7 个流，1 个网络警报，4 个工件行，2 个被隔离的高风险工件 ## 本代码库不包含什么 这是一个研究和作品集项目，而不是生产级安全产品。具体来说： - 未经验证是否可用于零停机的生产环境运行 - 尚未在生产级流量下进行全时长的良性压力测试验证 - 没有企业级支持或商业维护 - 实时仪表盘和 API 设计为**仅供本地使用** (127.0.0.1) — 在未添加身份验证中间件的情况下，请勿将其暴露给外部 ## 文档 | 文档 | 描述 | |----------|-------------| | [项目单页简介](docs/project_one_pager.md) | 摘要、架构和指标 | | [展示故事](docs/showcase_story.md) | 是什么让它有别于典型的 IDS 演示 | | [验证主记录](docs/testing_validation_master.md) | 完整的测试和场景证据 | | [误报分析](docs/false_positive_analysis.md) | 调优决策和判定日志 | | [部署就绪检查清单](docs/deployment_readiness_checklist.md) | 当前的就绪门状态 | | [证据清单](docs/evidence_inventory.md) | 存在哪些证据及其位置 | | [论文大纲](docs/paper_outline.md) | 研究论文规划 | ## 路线图 - [ ] 全时长良性压力测试验证 - [ ] 更广泛的良性流量判定语料库 - [ ] 针对抑制功能的实时证据运行 - [ ] 维护工作流决策（热重载 vs 重启） - [ ] 公开演示资产（精选截图、示例运行输出） ## 许可协议 核心 NIDS 检测引擎和 API（`src/NIDS/`，但不包含 `adversary_lab/`）采用 **MIT License** 授权 — 参见 [LICENSE](LICENSE)。 `src/NIDS/adversary_lab/` 组件依赖于 [Scapy](https://scapy.net) (仅限 GPL-2.0)，因此采用 **GPL-2.0-or-later** 授权 — 参见 [src/NIDS/adversary_lab/LICENSE](src/NIDS/adversary_lab/LICENSE)。此组件是可选的，运行核心检测 pipeline 并不需要它。 ## 安全 要报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。

标签：Apex, CatBoost, Metaprompt, Rootkit, Suricata, Zeek, 入侵检测系统, 安全数据湖, 机器学习, 现代安全运营, 网络安全, 网络流量分析, 逆向工具, 防御绕过, 隐私保护