harisx404/intrushield-nids
GitHub: harisx404/intrushield-nids
企业级网络入侵检测与安全运营中心平台，基于 Suricata 深度包检测，通过 FastAPI 异步后端与 Next.js 实时仪表板实现从流量监控到告警管理的全链路威胁可视化。
Stars: 1 | Forks: 0
# IntruShield NIDS — 自主网络入侵检测与威胁情报平台
**IntruShield NIDS** 是一个**企业级安全运营中心 (SOC) 平台和威胁遥测引擎**，由 **[Muhammad Haris](https://github.com/harisx404)** 设计并构建。 它将 **Suricata**（深度包检测引擎）与高性能、实时异步的 **FastAPI** 后端以及响应式的 **Next.js 14** 分析仪表板无缝结合——从原始网络线路流量到分析师屏幕，提供即时的威胁可视化。 ## 🔑 快速登录 | 字段 | 值 | |----------|-----------------| | 用户名 | `admin` | | 密码 | `admin` | | API 文档 | `/docs` | ## 🎯 本项目展示的内容 | 领域 | 技能 | |------|-------| | **异步 Python** | FastAPI + SQLAlchemy 异步会话，`aiofiles` 文件追踪 | | **实时系统** | WebSocket 广播管理器，自动重连客户端 | | **安全工程** | Suricata IDS 集成，JWT 认证，速率限制，审计日志 | | **数据工程** | EVE JSON 解析流水线，GeoIP 富化，TTL 去重 | | **前端** | Next.js 14，Zustand 状态管理，交互式 SOC 仪表板 | | **DevOps** | 多阶段 Docker 构建，Vercel Serverless，GitHub Actions CI/CD | | **架构** | 领域驱动设计，仓储模式，事件总线，响应引擎 | ## 🏗️ 系统架构 ``` ┌─────────────────────────────────────────────┐ Raw Network ──▶│ Suricata 7 (privileged, host network mode) │ Packets │ · Deep packet inspection │ │ · Custom + ET ruleset │ │ · Writes alerts to eve.json │ └─────────────────┬───────────────────────────┘ │ eve.json (shared volume) ┌─────────────────▼───────────────────────────┐ │ FastAPI Backend (Python 3.12 async) │ │ · aiofiles tail loop → EVE parser │ │ · GeoIP enrichment → deduplication │ │ · PostgreSQL/SQLite persistence │ │ · WebSocket broadcast manager │ │ · REST API /api/v1/* │ └─────────────────┬───────────────────────────┘ │ REST + WebSocket ┌─────────────────▼───────────────────────────┐ │ Next.js 14 Frontend (React, Zustand) │ │ · Real-time alert feed via WebSocket │ │ · Dashboard KPIs, charts, Top Attackers │ │ · Alert management (ack, resolve, filter) │ │ · Suricata rule CRUD │ └─────────────────┬───────────────────────────┘ │ ┌─────────────────▼───────────────────────────┐ │ NGINX / Vercel Edge │ │ · Reverse proxies /api/ → backend │ │ · Proxies /ws/ → backend WebSocket │ │ · Serves frontend on / │ └─────────────────────────────────────────────┘ ``` ## 🚀 本地运行（5 分钟） ### 选项 A — Docker Compose（推荐） **前置条件：** Docker Desktop ≥ 4.x（包含 Compose v2），Git ``` git clone https://github.com/harisx404/intrushield-nids.git cd intrushield-nids # 构建并启动所有 containers（首次运行会自动 seed 数据库） docker compose up --build -d # 查看启动日志 docker compose logs -f backend ``` SOC 仪表板将在约 30 秒后在 **http://localhost** 上线。 #### 常用命令 ``` docker compose ps # Check all container health docker compose logs -f backend # View live backend logs docker compose up --build backend -d # Rebuild a single service docker compose down # Stop everything docker compose down -v # Full reset (removes database volume) ``` ### 选项 B — 手动本地开发 **前置条件：** Python 3.12+，Node.js 20+ ``` # 1. Clone git clone https://github.com/harisx404/intrushield-nids.git cd intrushield-nids # 2. Backend — 创建 virtual environment 并安装依赖 python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate pip install -r backend/requirements.txt # 3. 配置 backend 环境 cp backend/.env.example backend/.env # 编辑 backend/.env — 设置强 JWT_SECRET_KEY 和你的 DATABASE_URL # 4. Seed 数据库（创建 admin 用户 + 示例数据） python -m backend.database.seed # 5. 启动 FastAPI backend uvicorn backend.main:app --reload --port 8000 # 6. 在第二个 terminal 中 — 启动 Next.js frontend npm install npm run dev ``` 仪表板将可以通过 **http://localhost:3000** 访问，API 文档位于 **http://localhost:8000/docs**。 ## 🌐 生产环境部署 该应用程序以 **混合 Vercel Serverless** 应用程序的形式部署： - **前端：** Next.js → Vercel Edge CDN - **后端：** FastAPI → Vercel Python Serverless Function (`api/index.py`) - **数据库：** Neon PostgreSQL（兼容 serverless 的 asyncpg） ### 必需的环境变量（Vercel 控制台） | 变量 | 描述 | |----------|-------------| | `DATABASE_URL` | `postgresql+asyncpg://user:pass@host/db` | | `JWT_SECRET_KEY` | 至少 64 个字符的随机字符串 | | `APP_ENV` | `production` | | `VERCEL` | `1`（由 Vercel 自动设置） | | `CORS_ORIGINS` | 你的 Vercel 域名（例如 `https://nids-pro.vercel.app`） | 设置环境变量后，触发新的 Vercel 部署，然后访问： ``` https://your-domain.vercel.app/api/v1/system/seed ``` 此幂等端点会在首次运行时创建默认管理员用户和示例数据。 ## 📐 API 参考 应用程序运行时，可以在 **/docs** 查看交互式的 Swagger 文档。 ### 核心 Endpoint | 方法 | Endpoint | 认证 | 描述 | |--------|----------|------|-------------| | `POST` | `/api/v1/auth/login` | ❌ | 认证 → 接收 JWT | | `GET` | `/api/v1/auth/me` | ✅ | 获取当前用户配置 | | `GET` | `/api/v1/alerts` | ✅ | 列出警报（过滤器：severity, status, src_ip, page） | | `GET` | `/api/v1/alerts/{id}` | ✅ | 获取单个警报的完整详情 | | `POST` | `/api/v1/alerts/{id}/acknowledge` | ✅ | 确认警报 | | `POST` | `/api/v1/alerts/{id}/resolve` | ✅ | 解决警报 | | `GET` | `/api/v1/rules` | ✅ | 列出检测规则 | | `POST` | `/api/v1/rules` | ✅ | 创建新规则 | | `PUT` | `/api/v1/rules/{id}` | ✅ | 更新 / 切换规则 | | `DELETE` | `/api/v1/rules/{id}` | ✅ | 删除规则 | | `GET` | `/api/v1/statistics/dashboard` | ✅ | 仪表板 KPI 统计数据 | | `GET` | `/api/v1/statistics/current` | ✅ | 最新流量统计快照 | | `GET` | `/api/v1/system/health` | ❌ | 存活探针 | | `GET` | `/api/v1/system/seed` | ❌ | 幂等数据库种子填充（仅首次运行） | | `WS` | `/ws/events?token={jwt}` | ✅ | 实时警报 WebSocket 推送 | ## 🛡️ 检测规则 平台内置了 **10 条生产级 Suricata 规则**，涵盖： | # | 规则 | 技术 | |---|------|-----------| | 1 | SSH 暴力破解检测 | 按源 IP 进行阈值追踪 | | 2 | SQL 注入 (OR 1=1) | HTTP URI 内容匹配 | | 3 | SQL 注入 (UNION SELECT) | HTTP 多内容匹配 | | 4 | Nmap OS 检测探针 | TCP 标志组合 | | 5 | Log4Shell (CVE-2021-44228) | JNDI 字符串检测 | | 6 | XSS 探针 | HTTP URI 中的 `
**IntruShield NIDS** 是一个**企业级安全运营中心 (SOC) 平台和威胁遥测引擎**，由 **[Muhammad Haris](https://github.com/harisx404)** 设计并构建。 它将 **Suricata**（深度包检测引擎）与高性能、实时异步的 **FastAPI** 后端以及响应式的 **Next.js 14** 分析仪表板无缝结合——从原始网络线路流量到分析师屏幕，提供即时的威胁可视化。 ## 🔑 快速登录 | 字段 | 值 | |----------|-----------------| | 用户名 | `admin` | | 密码 | `admin` | | API 文档 | `/docs` | ## 🎯 本项目展示的内容 | 领域 | 技能 | |------|-------| | **异步 Python** | FastAPI + SQLAlchemy 异步会话，`aiofiles` 文件追踪 | | **实时系统** | WebSocket 广播管理器，自动重连客户端 | | **安全工程** | Suricata IDS 集成，JWT 认证，速率限制，审计日志 | | **数据工程** | EVE JSON 解析流水线，GeoIP 富化，TTL 去重 | | **前端** | Next.js 14，Zustand 状态管理，交互式 SOC 仪表板 | | **DevOps** | 多阶段 Docker 构建，Vercel Serverless，GitHub Actions CI/CD | | **架构** | 领域驱动设计，仓储模式，事件总线，响应引擎 | ## 🏗️ 系统架构 ``` ┌─────────────────────────────────────────────┐ Raw Network ──▶│ Suricata 7 (privileged, host network mode) │ Packets │ · Deep packet inspection │ │ · Custom + ET ruleset │ │ · Writes alerts to eve.json │ └─────────────────┬───────────────────────────┘ │ eve.json (shared volume) ┌─────────────────▼───────────────────────────┐ │ FastAPI Backend (Python 3.12 async) │ │ · aiofiles tail loop → EVE parser │ │ · GeoIP enrichment → deduplication │ │ · PostgreSQL/SQLite persistence │ │ · WebSocket broadcast manager │ │ · REST API /api/v1/* │ └─────────────────┬───────────────────────────┘ │ REST + WebSocket ┌─────────────────▼───────────────────────────┐ │ Next.js 14 Frontend (React, Zustand) │ │ · Real-time alert feed via WebSocket │ │ · Dashboard KPIs, charts, Top Attackers │ │ · Alert management (ack, resolve, filter) │ │ · Suricata rule CRUD │ └─────────────────┬───────────────────────────┘ │ ┌─────────────────▼───────────────────────────┐ │ NGINX / Vercel Edge │ │ · Reverse proxies /api/ → backend │ │ · Proxies /ws/ → backend WebSocket │ │ · Serves frontend on / │ └─────────────────────────────────────────────┘ ``` ## 🚀 本地运行（5 分钟） ### 选项 A — Docker Compose（推荐） **前置条件：** Docker Desktop ≥ 4.x（包含 Compose v2），Git ``` git clone https://github.com/harisx404/intrushield-nids.git cd intrushield-nids # 构建并启动所有 containers（首次运行会自动 seed 数据库） docker compose up --build -d # 查看启动日志 docker compose logs -f backend ``` SOC 仪表板将在约 30 秒后在 **http://localhost** 上线。 #### 常用命令 ``` docker compose ps # Check all container health docker compose logs -f backend # View live backend logs docker compose up --build backend -d # Rebuild a single service docker compose down # Stop everything docker compose down -v # Full reset (removes database volume) ``` ### 选项 B — 手动本地开发 **前置条件：** Python 3.12+，Node.js 20+ ``` # 1. Clone git clone https://github.com/harisx404/intrushield-nids.git cd intrushield-nids # 2. Backend — 创建 virtual environment 并安装依赖 python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate pip install -r backend/requirements.txt # 3. 配置 backend 环境 cp backend/.env.example backend/.env # 编辑 backend/.env — 设置强 JWT_SECRET_KEY 和你的 DATABASE_URL # 4. Seed 数据库（创建 admin 用户 + 示例数据） python -m backend.database.seed # 5. 启动 FastAPI backend uvicorn backend.main:app --reload --port 8000 # 6. 在第二个 terminal 中 — 启动 Next.js frontend npm install npm run dev ``` 仪表板将可以通过 **http://localhost:3000** 访问，API 文档位于 **http://localhost:8000/docs**。 ## 🌐 生产环境部署 该应用程序以 **混合 Vercel Serverless** 应用程序的形式部署： - **前端：** Next.js → Vercel Edge CDN - **后端：** FastAPI → Vercel Python Serverless Function (`api/index.py`) - **数据库：** Neon PostgreSQL（兼容 serverless 的 asyncpg） ### 必需的环境变量（Vercel 控制台） | 变量 | 描述 | |----------|-------------| | `DATABASE_URL` | `postgresql+asyncpg://user:pass@host/db` | | `JWT_SECRET_KEY` | 至少 64 个字符的随机字符串 | | `APP_ENV` | `production` | | `VERCEL` | `1`（由 Vercel 自动设置） | | `CORS_ORIGINS` | 你的 Vercel 域名（例如 `https://nids-pro.vercel.app`） | 设置环境变量后，触发新的 Vercel 部署，然后访问： ``` https://your-domain.vercel.app/api/v1/system/seed ``` 此幂等端点会在首次运行时创建默认管理员用户和示例数据。 ## 📐 API 参考 应用程序运行时，可以在 **/docs** 查看交互式的 Swagger 文档。 ### 核心 Endpoint | 方法 | Endpoint | 认证 | 描述 | |--------|----------|------|-------------| | `POST` | `/api/v1/auth/login` | ❌ | 认证 → 接收 JWT | | `GET` | `/api/v1/auth/me` | ✅ | 获取当前用户配置 | | `GET` | `/api/v1/alerts` | ✅ | 列出警报（过滤器：severity, status, src_ip, page） | | `GET` | `/api/v1/alerts/{id}` | ✅ | 获取单个警报的完整详情 | | `POST` | `/api/v1/alerts/{id}/acknowledge` | ✅ | 确认警报 | | `POST` | `/api/v1/alerts/{id}/resolve` | ✅ | 解决警报 | | `GET` | `/api/v1/rules` | ✅ | 列出检测规则 | | `POST` | `/api/v1/rules` | ✅ | 创建新规则 | | `PUT` | `/api/v1/rules/{id}` | ✅ | 更新 / 切换规则 | | `DELETE` | `/api/v1/rules/{id}` | ✅ | 删除规则 | | `GET` | `/api/v1/statistics/dashboard` | ✅ | 仪表板 KPI 统计数据 | | `GET` | `/api/v1/statistics/current` | ✅ | 最新流量统计快照 | | `GET` | `/api/v1/system/health` | ❌ | 存活探针 | | `GET` | `/api/v1/system/seed` | ❌ | 幂等数据库种子填充（仅首次运行） | | `WS` | `/ws/events?token={jwt}` | ✅ | 实时警报 WebSocket 推送 | ## 🛡️ 检测规则 平台内置了 **10 条生产级 Suricata 规则**，涵盖： | # | 规则 | 技术 | |---|------|-----------| | 1 | SSH 暴力破解检测 | 按源 IP 进行阈值追踪 | | 2 | SQL 注入 (OR 1=1) | HTTP URI 内容匹配 | | 3 | SQL 注入 (UNION SELECT) | HTTP 多内容匹配 | | 4 | Nmap OS 检测探针 | TCP 标志组合 | | 5 | Log4Shell (CVE-2021-44228) | JNDI 字符串检测 | | 6 | XSS 探针 | HTTP URI 中的 `