nassim-saii/netpol-intelligence
GitHub: nassim-saii/netpol-intelligence
面向 OpenShift/Kubernetes 的六层安全可观测性平台，结合网络流量异常检测、NetworkPolicy 自动合规审计与集群内 LLM 智能分析，实现零数据外泄的智能安全治理。
Stars: 0 | Forks: 0
# NetworkPolicy 智能系统 (NPI)
### 面向 OpenShift 的智能网络异常检测与 Kubernetes NetworkPolicy 合规性
[](https://www.openshift.com/)
[](https://github.com/ovn-org/ovn-kubernetes)
[](https://www.python.org/)
[](https://react.dev/)
[](https://hub.docker.com/u/nassimsai)
## 📌 项目概述
**NPI** 是一个面向 **OpenShift / Kubernetes 集群** 的六层安全可观测性平台，它将实时网络流分析、统计与机器学习异常检测、自动化的 NetworkPolicy 合规性审计，以及一个集群内的 LLM 助手结合在一起，构建为一个位于 **OVN-Kubernetes** 之上的单一智能层。
NPI 无需依赖人工手动检查 `NetworkPolicy` YAML 以寻找安全漏洞，也不必肉眼盯着仪表板寻找可疑流量，而是监控集群原生信号 —— OVN ACL 丢弃日志、实时的 `NetworkPolicy` 对象以及时间序列流量统计 —— 并将其转化为结构化的发现结果、排序后的异常情况以及安全工程师可以立即采取行动的纯英文解释。
本项目是作为 **PFE（毕业工程项目）** 在 **NextStep IT**（突尼斯，突尼斯市）与 **TEK-UP 大学** 合作开发的。
[](docs/screenshots/dashboard-overview.png)
## 🎯 目标
- 使用统计和基于机器学习的方法实时检测异常网络流
- 根据安全规则目录自动审计 Kubernetes `NetworkPolicy` 资源
- 将异常和策略违规关联起来，为每个 namespace 生成单一的合规性分数
- 通过集群上的 LLM 提供自然语言解释和修复指导 —— 且数据绝对不会离开集群
- 在运行 OVN-Kubernetes 的真实裸机 OpenShift 集群上演示零信任 NetworkPolicy 设计
## 🏗️ 架构概述
NPI 构建为 **六个协作层**，作为独立的微服务部署在 `netpol-system` 和 `llm-system` 命名空间中：
| 层级 | 组件 | 作用 |
|---|---|---|
| 1. 可观测性 | Fluent Bit → Loki | 在集群范围内收集 OVN-Kubernetes ACL 流量/丢弃日志 |
| 2. 流量处理 | `flow-processor` | 将原始 OVN 丢弃事件转换为结构化流量记录，构建基于命名空间对的基础基线（Welford 在线算法） |
| 3. 异常检测 | `anomaly-detector` | 三级检测：Welford/Z-score 统计峰值、确定性规则匹配，以及用于多变量异常值的 Isolation Forest (scikit-learn) |
| 4. 策略审计 | `audit-engine` | 通过 Kubernetes API 监控实时 `NetworkPolicy` 对象，并根据 8 条安全规则目录 (NP-001–NP-008) 对其进行评估 |
| 5. 智能 | `llm-service` (Ollama / `llama3.2:3b`) | 生成纯英文解释、攻击场景框架和 YAML 修复建议 —— 完全在集群内进行，通过 SSE 流式传输 |
| 6. 展示 | `api-gateway` + `netpol-dashboard` (React 18) | REST + SSE API 和实时仪表板：namespace 地图、异常时间轴、合规性报告，以及由 LLM 驱动的聊天助手 |
所有数据均持久化存储在 **TimescaleDB** hypertables 中，并在 **Grafana** 中实时可视化。
[](docs/diagrams/npi-architecture.png)
## 🧰 使用的技术
| 类别 | 技术栈 |
|---|---|
| 集群 | OpenShift 4.21.8 (裸机 UPI), OVN-Kubernetes CNI |
| 后端 | Python 3.11, FastAPI, Kubernetes Python client v29 |
| 机器学习/统计 | scikit-learn (Isolation Forest), NumPy, Welford 在线算法 |
| LLM | Ollama, `llama3.2:3b` (Q4 量化, 纯 CPU 推理) |
| 数据库 | TimescaleDB (PostgreSQL + hypertables) |
| 前端 | React 18, Vite, Recharts |
| 可观测性 | Fluent Bit, Loki, Prometheus, Grafana 12 |
| 策略自动化 | Kyverno (生成/验证 `ClusterPolicy`) |
| 构建 | OpenShift `BuildConfig` (`--binary --strategy=docker`) / Docker & Podman |
| 容器 | Docker Hub — [`nassimsai`](https://hub.docker.com/u/nassimsai) |
## 🖥️ 集群拓扑
| 节点 | 角色 | IP | 备注 |
|---|---|---|---|
| `ocp-lb` | Bastion / HAProxy | 10.9.22.229 | 真理来源：`~/netpol-intelligence/` |
| `ocp-cp-0` | Control plane | 10.9.22.230 | |
| `ocp-w-0` | Storage worker | 10.9.22.231 | Loki, TimescaleDB, `flow-processor` |
| `ocp-w-1` | Intelligence worker | 10.9.22.232 | `audit-engine`, `anomaly-detector`, `api-gateway` |
| `ocp-w-2` | LLM-dedicated worker | 10.9.22.233 | 12 vCPU, taint `dedicated=llm:NoSchedule`, 运行 Ollama |
域名：`lab.ocp.lan` · 应用：`*.apps.lab.ocp.lan` · 命名空间：`netpol-system`, `llm-system`, `online-boutique` (测试工作负载), `kyverno`
## 🐳 预构建镜像
所有六个服务均作为独立、可移植的镜像发布在 Docker Hub 上 —— 在其他地方重新部署无需 OpenShift `BuildConfig`：
| 服务 | 镜像 | 描述 |
|---|---|---|
| `audit-engine` | [`nassimsai/audit-engine`](https://hub.docker.com/r/nassimsai/audit-engine) | NetworkPolicy 合规性审计引擎 (NP-001–NP-008) |
| `flow-processor` | [`nassimsai/flow-processor`](https://hub.docker.com/r/nassimsai/flow-processor) | OVN ACL 丢弃日志 → 流量记录 + 基线构建器 |
| `anomaly-detector` | [`nassimsai/anomaly-detector`](https://hub.docker.com/r/nassimsai/anomaly-detector) | Z-score、基于规则和 Isolation Forest 的异常检测 |
| `llm-service` | [`nassimsai/llm-service`](https://hub.docker.com/r/nassimsai/llm-service) | 集群内 LLM 编排（Ollama 客户端，SSE 流式传输） |
| `api-gateway` | [`nassimsai/api-gateway`](https://hub.docker.com/r/nassimsai/api-gateway) | 用于仪表板的 FastAPI REST + SSE 网关 |
| `netpol-dashboard` | [`nassimsai/netpol-dashboard`](https://hub.docker.com/r/nassimsai/netpol-dashboard) | React 18 SPA (多阶段构建 → nginx) |
每个镜像均标记为 `latest` 和 `v1.0-pfe2026`（答辩快照）。
```
docker pull docker.io/nassimsai/audit-engine:v1.0-pfe2026
```
## 🚀 快速开始
### 选项 A — 使用预构建的 Docker Hub 镜像在 OpenShift 上部署（推荐）
```
git clone https://github.com/nassim-saii/netpol-intelligence.git
cd netpol-intelligence
# 创建 namespaces
oc apply -f deploy/namespaces.yaml
# 创建 secrets（先填写您自己的 credentials —— 参见 deploy/secrets.example.yaml）
oc apply -f deploy/secrets.yaml
# 部署 TimescaleDB、Kyverno policies 及全部六个服务
oc apply -f deploy/
oc rollout status deployment/audit-engine -n netpol-system
oc rollout status deployment/flow-processor -n netpol-system
oc rollout status deployment/anomaly-detector -n netpol-system
oc rollout status deployment/llm-service -n netpol-system
oc rollout status deployment/api-gateway -n netpol-system
oc rollout status deployment/netpol-dashboard -n netpol-system
```
完整的分步说明（包括 Ollama 模型拉取、Grafana 仪表板导入和 Kyverno 设置）在 [`NPI_Deployment_Runbook.md`](docs/NPI_Deployment_Runbook.md) 中。
### 选项 B — 在 OpenShift 中从源代码构建（原始支持气隙部署的流水线）
```
oc new-build --name=audit-engine --binary --strategy=docker -n netpol-system
oc start-build audit-engine --from-dir=services/audit-engine/ --follow
# 按每个 service 重复执行 —— 参见 docs/NPI_Deployment_Runbook.md，第 3 节
```
## 🔍 NetworkPolicy 审计规则目录
| 规则 ID | 严重性 | 检查内容 |
|---|---|---|
| NP-001 | HIGH | 每个 namespace 是否存在默认拒绝 ingress |
| NP-002 | CRITICAL | 过于宽松的 ingress（`{}` 选择器） |
| NP-003 | HIGH | 缺少 egress 限制 |
| NP-004 | MEDIUM | 缺少 DNS egress 规则（端口 53 **和** 5353） |
| NP-005 | MEDIUM | namespace 标签选择器最佳实践 |
| NP-006 | LOW | 策略命名/文档规范 |
| NP-007 | HIGH | 没有明确允许的跨 namespace 流量 |
| NP-008 | CRITICAL | Router ingress 路径缺少双重 namespace 选择器 |
检查结果将转化为每个 namespace 的**合规性分数**：`100 − (CRITICAL×20 + HIGH×10 + MEDIUM×5 + LOW×2)`，评级为 A–F。
## 🧪 实测性能
| 指标 | 结果 |
|---|---|
| LLM 首字时间 | 3.8 s |
| 完整 LLM 分析（SSE 流完成） | 11.3 s |
| Z-score 峰值检测延迟 | 84 s |
| 端口扫描检测延迟 | 98 s |
| 审计规则评估延迟 | < 10 s |
| 端到端测试场景通过 | 8 / 8 |
| Isolation Forest — 首次实时检测 | 分数 −0.5004，基于 8 个样本训练 |
## 📂 仓库结构
```
netpol-intelligence/
├── services/
│ ├── audit-engine/ ← Policy compliance audit engine
│ ├── flow-processor/ ← OVN flow ingestion + baselining
│ ├── anomaly-detector/ ← Z-score / rules / Isolation Forest
│ └── llm-service/ ← Ollama orchestration (SSE)
├── netpol-p4/
│ ├── api-gateway/ ← FastAPI REST + SSE gateway
│ ├── frontend/ ← React 18 dashboard (Vite + nginx)
│ └── deploy/ ← Phase 4 manifests
├── deploy/ ← Deployment manifests (all phases)
├── kyverno-policies/ ← ClusterPolicy definitions
├── grafana/ ← Dashboard JSON exports
├── docs/ ← Runbooks, diagrams, screenshots
└── README.md
```
## 📊 仪表板功能
| 标签页 | 组件 | 亮点 |
|---|---|---|
| Namespace 地图 | `App.jsx` | 实时的每个 namespace 风险概览：pod、流量、活跃违规 |
| 异常时间轴 | `AnomalyTimeline.jsx` | 带有严重性颜色显示的实时异常信息流 |
| 合规性 | `ComplianceReport.jsx` | 分数圆圈 (0–100 %)、评级 (A–F)、严重性分布 (Recharts) |
| 助手 | `Chat.jsx` | 由 `llama3.2:3b` 驱动的流式 SSE 聊天机器人，具备实时集群上下文感知 |
## 📸 截图
| 合规性报告 | AI 助手 |
|---|---|
|  |  |
| Grafana — 策略违规 | 异常时间轴 |
|---|---|
|  |  |
## ⚠️ 已知操作行为
- `oc start-build` **不会**自动循环运行的 pod —— 必须始终随后执行 `oc rollout restart`
- Ollama 部署策略必须为 `Recreate`（两个需要 10+ vCPU 的 pod 无法在一个节点上共存）
- OVN-Kubernetes 会在 post-DNAT 阶段评估 DNS —— 需在 egress 规则中同时允许端口 53 和 5353
- OCP Router ingress NetworkPolicy 需要**两**个独立的 `from:` 条目（namespace-name 选择器*和* `policy-group=ingress`）
完整列表见 [`docs/NPI_Deployment_Runbook.md`](docs/NPI_Deployment_Runbook.md)。
## 👨🎓 作者与指导
- **Nassim Saii** — TEK-UP 大学网络与系统安全工程专业大四学生
**企业指导教师：** Mouna Belghith — NextStep IT 云与基础设施工程师\
**学术指导教师：** Khaoula Ammar — TEK-UP 大学
班级：网络与系统安全工程 · 学年：2025–2026
## 📜 许可证
本项目作为 PFE（毕业工程项目）的一部分，出于学术目的而开发。除非另有说明，保留所有权利。
标签：AI风险缓解, DLL 劫持, 大语言模型, 安全可观测性, 异常检测, 版本控制, 网络流量分析, 逆向工具, 防御绕过