husseinammr/sentrynet-ai

https://husseinammr.github.io/sentrynet-ai/ ## 📋 目录 - [概述](#-overview) - [核心功能](#-key-features) - [架构](#-architecture) - [快速演示](#-quick-demo) - [全栈配置](#-full-stack-setup) - [机器学习模型](#-machine-learning-model) - [自动响应引擎](#-auto-response-engine) - [AI Agent](#-ai-agent) - [REST API](#-rest-api-reference) - [仪表盘](#-dashboard) - [项目结构](#-project-structure) - [技术栈](#-tech-stack) - [路线图](#-roadmap) ## 🎯 概述 **SentryNet AI** 是一个全栈网络安全平台，它集成了以下功能： - **实时 Zeek 日志接入** — 读取实时的 `conn.log` 流，或在不可用时回退到内置模拟器 - **基于机器学习的异常检测** — 在正常流量上训练的 Isolation Forest，能够标记任何异常情况 - **自动化威胁响应** — 通过 iptables 封禁 IP，隔离受感染的局域网主机，并在超时后自动解封 - **自主 AI Agent** — 将事件批次发送给 Claude AI 进行深度分析，生成结构化的取证报告，并协调响应操作 - **实时 WebSocket 仪表盘** — 包含实时图表、GeoIP 地图、威胁日志和事件报告的 4 面板 UI **它解决的问题：** 网络每秒承载着数千个连接 — 依靠人工监控是不可能的。攻击者正是利用了这一盲点。SentryNet AI 进行 7x24 小时全天候监控，在几秒钟内检测到威胁，并自主做出响应。 ## ✨ 核心功能 | 功能 | 描述 | |---|---| | 🔍 **异常检测** | Isolation Forest ML 模型 — 学习正常流量，标记偏差 | | ⚡ **实时流处理** | 每 1.5 秒向所有已连接的仪表盘进行 WebSocket 广播 | | 🚫 **自动封禁** | 通过 iptables 规则自动封禁恶意 IP | | 🔒 **主机隔离** | 将受感染的局域网主机从网络中隔离 | | 🤖 **AI Agent** | 基于 Claude 的事件分析，提供完整的取证报告 | | 📡 **Zeek 集成** | 实时追踪 `conn.log`；自动检测 Zeek 安装情况 | | 🌍 **GeoIP 映射** | 根据经纬度在世界地图上显示动态来源点 | | 📊 **攻击分类** | DDoS · 端口扫描 · 暴力破解 · 数据泄露 | | 🗄️ **双数据库** | 使用 MongoDB + PostgreSQL 存储日志、告警和 IP 统计信息 | | 🐳 **Docker 就绪** | 完整的 `docker-compose.yml` — 一条命令即可运行所有服务 | | 🔐 **JWT 认证** | 基于 token 的身份验证，支持基于角色的访问控制 | ## 🏗️ 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ SentryNet AI v3.0 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Network Traffic │ │ │ │ │ ┌────▼────────┐ ┌───────────────────┐ │ │ │ Zeek Reader │ │ Traffic Simulator │ (fallback) │ │ │ conn.log │ │ synthetic data │ │ │ └────┬────────┘ └─────────┬──────────┘ │ │ └──────────┬────────────┘ │ │ │ │ │ ┌────────▼─────────┐ │ │ │ Anomaly Detector │ ← Isolation Forest (sklearn) │ │ │ Feature Extract │ 9 features per entry │ │ └────────┬─────────┘ │ │ │ enriched entries │ │ ┌────────▼─────────┐ │ │ │ Alert Manager │ ← stats, top IPs, time-series │ │ └────┬─────────────┘ │ │ │ │ │ ┌──────────┼───────────────┐ │ │ │ │ │ │ │ ┌──▼─────┐ ┌──▼────────┐ ┌───▼──────┐ │ │ │ Auto │ │ AI Agent │ │WebSocket │ │ │ │Response│ │ (Claude) │ │Broadcast │ │ │ │ Engine │ │ │ │ │ │ │ └──┬─────┘ └─────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ iptables Incident Dashboard │ │ rules Reports (browser) │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` ## ⚡ 快速演示 **无需后端** — 直接在浏览器中打开即可： ``` git clone https://github.com/yourusername/sentrynet-ai.git cd sentrynet-ai # 打开 dashboard open frontend/dashboard.html # 或：python3 -m http.server 3000 && open http://localhost:3000/dashboard.html ``` **登录信息：** `admin` / `sentrynet2025` 仪表盘在完全模拟的模式下运行 — 攻击是随机注入的，AI Agent 会生成事件报告，自动响应引擎会自动封锁和解封 IP。无需任何后端、数据库或 API 密钥即可进行试用。 ## 🚀 全栈配置 ### 前置条件 - Python 3.11+ - pip - (可选) Docker & Docker Compose - (可选) Zeek 6.x（用于实时流量监控） - (可选) Anthropic API 密钥（用于 AI Agent） ### 1. 安装依赖 ``` cd backend python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` ### 2. 启动后端 ``` # 标准模式（模拟流量） uvicorn main:app --host 0.0.0.0 --port 8000 --reload # 使用实时 Zeek 日志（如果安装了 Zeek 则自动检测） uvicorn main:app --host 0.0.0.0 --port 8000 ``` ### 3. 将仪表盘连接到后端 打开 `frontend/dashboard.html`，找到 `connectWS()` 函数，并取消注释真实的 WebSocket 代码块： ``` ws = new WebSocket('ws://localhost:8000/ws'); ws.onopen = () => { document.getElementById('hstatus').textContent = 'LIVE'; }; ws.onmessage = e => { handleMessage(JSON.parse(e.data)); }; ws.onclose = () => { setTimeout(connectWS, 3000); }; ``` ### 4. Docker (全栈) ``` docker-compose up --build # 服务： # Dashboard → http://localhost:3000 # Backend → http://localhost:8000 # API Docs → http://localhost:8000/docs # MongoDB → localhost:27017 # PostgreSQL → localhost:5432 ``` ## 🤖 机器学习模型 ### 算法：Isolation Forest Isolation Forest 非常适合用于网络异常检测，因为： - 无需标注的攻击数据即可工作（无监督学习） - 推理速度快 — 能够处理每秒数千条记录 - 在稳定、正常的流量模式下误报率低 ### 提取的特征 | # | 特征 | 描述 | |---|---|---| | 1 | `bytes` | 传输的总字节数 | | 2 | `packets` | 数据包数量 | | 3 | `duration` | 连接持续时间（秒） | | 4 | `dst_port` | 目标端口 | | 5 | `src_port` | 源端口 | | 6 | `protocol` | TCP=0, UDP=1, ICMP=2 | | 7 | `conn_state` | SF=0, S0=1, REJ=2, RSTO=3, OTH=4 | | 8 | `bytes/sec` | 吞吐率 | | 9 | `packets/sec` | 数据包速率 | ### 攻击分类规则 | 攻击类型 | 检测特征 | |---|---| | **DDoS** | packets > 200, duration < 0.5s, protocol = UDP | | **端口扫描** | state = REJ/S0, bytes < 300, duration < 50ms | | **暴力破解** | port ∈ {22, 3389, 21, 5900}, state = REJ/RSTO | | **数据泄露** | bytes > 50KB, packets < 50 | ### 训练模型 ``` cd models python train_model.py # ───────────────────────────────────────────────────────────── # 评估报告 # ───────────────────────────────────────────────────────────── # Accuracy : 94.2% # Precision: 91.8% # Recall : 88.5% # F1 Score : 90.1% # ───────────────────────────────────────────────────────────── ``` ### 生成合成数据集 ``` cd data python generate_dataset.py --rows 10000 --out zeek_conn.csv # 分布： # Normal : ~8,600 行 (86%) # DDoS : ~500 行 (5%) # Port Scan : ~500 行 (5%) # Brute Force : ~400 行 (4%) ``` ## 🚫 自动响应引擎 `backend/services/auto_response.py` **实时**响应已确认的威胁，无需人工干预。 ### 响应动作 | 触发条件 | 阈值 | 动作 | |---|---|---| | DDoS 洪水攻击 | 单个 IP ≥ 1,000 pps | 通过 `iptables -A INPUT -s -j DROP` 封禁 IP | | 暴力破解 | ≥ 5 次失败尝试 | 封禁 IP，记录目标端口 | | 端口扫描 | 探测 ≥ 20 个不同端口 | 封禁 IP | | 数据泄露 (内部) | 任何内部主机 | 通过 iptables FORWARD 规则隔离主机 | | — | 300 秒后 | 自动解封，自动移除规则 | ### 模式 ``` # Dry-run 模式（默认）—— 记录操作但不修改 iptables auto_response = AutoResponseEngine(dry_run=True) # Active 模式 —— 应用真实的 iptables 规则（需要 root） auto_response = AutoResponseEngine(dry_run=False) ``` ### 通过 API 进行手动控制 ``` # 解封特定 IP curl -X POST http://localhost:8000/api/v1/response/unblock/185.220.101.45 # 检查当前被封禁的 IP 和隔离的主机 curl http://localhost:8000/api/v1/response/status ``` ## 🧠 AI Agent `backend/services/ai_agent.py` 是位于原始检测之上的自主智能层。 ### Pipeline ``` 1. Ingest high/critical alerts from the Alert Manager 2. Batch up to 5 alerts per analysis cycle 3. Send structured context to the Claude API 4. Parse the JSON response into an Incident Report 5. Execute recommended auto-response actions 6. Broadcast the forensic report to the dashboard 7. Store report history (last 50 incidents) ``` 如果 Claude API 不可用，该 Agent 将回退到基于规则的事件分析，以确保系统响应永不中断。 ### 事件报告结构 ``` { "incident_id": "INC-1042", "title": "DDoS Attack Detected", "severity": "critical", "attack_type": "DDoS", "confidence": 0.94, "summary": "Sustained UDP flood from 185.220.101.45...", "attacker_profile": "Botnet operator using UDP amplification", "impact_assessment": "Service unavailability, bandwidth saturation", "recommended_actions": ["Block source IP", "Enable rate limiting", "..."], "auto_actions_taken": ["Blocked IP: 185.220.101.45"], "ioc": { "ips": ["185.220.101.45"], "ports": [80, 443], "protocols": ["udp"] }, "report": "Incident INC-1042: A CRITICAL severity DDoS attack..." } ``` ### Agent API 接口 ``` # 获取 agent 状态和队列深度 curl http://localhost:8000/api/v1/agent/status # 获取所有事件报告 curl http://localhost:8000/api/v1/agent/reports ``` ## 📡 REST API 参考 | 方法 | 端点 | 描述 | |---|---|---| | `POST` | `/auth/login` | 身份验证 → 返回 JWT | | `GET` | `/health` | 系统健康状态 + 组件状态 | | `WS` | `/ws` | 实时 WebSocket 流 | | `GET` | `/api/v1/traffic` | 最近的流量日志 (`?limit=100`) | | `GET` | `/api/v1/alerts` | 最近的告警 (`?severity=high&attack_type=DDoS`) | | `GET` | `/api/v1/stats` | 汇总统计数据 + 热门 IP | | `GET` | `/api/v1/top-ips` | 按流量大小排列的热门 IP | | `GET` | `/api/v1/attack-summary` | 攻击类型分布情况 | | `GET` | `/api/v1/response/status` | 已封禁的 IP + 已隔离的主机 | | `POST` | `/api/v1/response/unblock/{ip}` | 手动解封 IP | | `GET` | `/api/v1/agent/status` | AI Agent 队列 + 统计信息 | | `GET` | `/api/v1/agent/reports` | 所有事件报告 | **交互式 API 文档：** `http://localhost:8000/docs` ### 示例请求 ``` # Login curl -X POST http://localhost:8000/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"sentrynet2025"}' # 最近的关键警报 curl "http://localhost:8000/api/v1/alerts?severity=critical&limit=10" # 系统健康状态 curl http://localhost:8000/health ``` ## 📊 仪表盘 `frontend/dashboard.html` 是一个独立的单文件应用程序，包含 4 个标签页。 ### 标签页 1 — 监控 | 面板 | 内容 | |---|---| | 实时流量 | 实时折线图 — packets/s + 异常覆盖图 | | 威胁分布 | 攻击类型环形图 + 协议环形图 | | 热门源 IP | 按流量大小排序的柱状图，威胁 IP 以红色高亮显示 | | 数据包流 | 最近 6 条 Zeek 日志记录及其状态徽章 | | 威胁日志 | 滚动告警信息流，按严重程度进行颜色编码 | | GeoIP 地图 | 根据地理坐标显示动态来源点 | | 攻击摘要 | DDoS、端口扫描、暴力破解、数据泄露的计数器 | ### 标签页 2 — 自动响应 - **已封禁的 IP** — 包含原因、时间戳的实时列表，以及手动解封按钮 - **动作流** — 实时记录的每一个自动化操作 - **已隔离的主机** — 被引擎隔离的局域网主机 - **配置** — 阈值和当前模式 (DRY-RUN / ACTIVE) ### 标签页 3 — AI Agent - **事件报告** — 每个事件对应一个可展开的卡片 - **分析详情** — 摘要、攻击者画像、影响评估 - **IOC 列表** — 每个事件涉及的 IP、端口、协议 - **取证报告** — 完整的叙述性段落 - **Agent 状态** — 实时的 pipeline 统计数据 | ### 标签页 4 — Zeek / 数据 - Zeek 日志检测状态和搜索路径 - 数据集生成命令 - ML 特征列表 - 系统架构概览 ## 📁 项目结构 ``` sentrynet-ai/ │ ├── backend/ │ ├── main.py # FastAPI app — all services wired together │ ├── requirements.txt # Python dependencies │ ├── Dockerfile # Container image │ │ │ ├── api/ │ │ └── routes.py # REST API endpoints (v1) │ │ │ ├── services/ │ │ ├── traffic_simulator.py # Zeek-style synthetic traffic generator │ │ ├── zeek_reader.py # Live Zeek conn.log reader │ │ ├── anomaly_detector.py # Isolation Forest ML model │ │ ├── alert_manager.py # Alert tracking, stats, history │ │ ├── auto_response.py # Automated IP blocking / isolation │ │ └── ai_agent.py # Autonomous Claude-powered agent │ │ │ └── utils/ │ ├── auth.py # HMAC-SHA256 JWT implementation │ ├── logger.py # Structured logging │ └── schema.sql # PostgreSQL schema │ ├── frontend/ │ ├── dashboard.html # Full dashboard (self-contained) │ └── nginx.conf # Nginx reverse proxy config │ ├── models/ │ └── train_model.py # Model training + evaluation script │ ├── data/ │ └── generate_dataset.py # Zeek CSV dataset generator │ ├── docs/ │ └── estimate.html # Project estimate │ ├── docker-compose.yml # Full stack: backend + frontend + DBs └── README.md ``` ## 🔧 环境变量 在 `backend/` 目录下创建一个 `.env` 文件： ``` # Database MONGO_URI=mongodb://localhost:27017/sentrynet POSTGRES_URI=postgresql://postgres:sentrynet@localhost:5432/sentrynet # Auth SECRET_KEY=your-secret-key-change-in-production # 自动响应 DRY_RUN=true # Set to false for real iptables rules # Zeek ZEEK_LOG_PATH= # Leave empty for auto-detection # AI Agent ANTHROPIC_API_KEY= # Required for live Claude analysis (optional — falls back to rules) ``` ## 🛠️ 技术栈 | 层级 | 技术 | |---|---| | **Backend** | Python 3.11, FastAPI, Uvicorn | | **ML** | scikit-learn (Isolation Forest), NumPy, pandas | | **WebSocket** | FastAPI WebSocket, websockets | | **Database** | MongoDB 7 + PostgreSQL 16 | | **Frontend** | Vanilla JS, Chart.js 4, CSS Grid | | **AI Agent** | Anthropic Claude API | | **IDS/Traffic** | Zeek 6.x (或内置模拟器) | | **Auth** | HMAC-SHA256 JWT | | **Deploy** | Docker, Docker Compose, Nginx | ## 🗺️ 路线图 - [x] 实时监控仪表盘 - [x] ML 异常检测 - [x] 自动化 IP 封禁和主机隔离 - [x] 实时 Zeek 日志集成 - [x] 自主 AI Agent - [ ] 用于序列攻击的 LSTM 时间序列模型 - [ ] 移动推送通知 - [ ] 多租户 / 企业模式 - [ ] SIEM 集成 (Splunk, IBM QRadar) - [ ] 合规性报告 (ISO 27001, NCA) ## 🤝 贡献指南 1. Fork 该仓库 2. 创建一个功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交您的更改 (`git commit -m 'Add AmazingFeature'`) 4. 推送到该分支 (`git push origin feature/AmazingFeature`) 5. 发起一个 Pull Request ## 📄 许可证 MIT License — 详情请参阅 [LICENSE](LICENSE)。

为网络防御者而生。 如果 SentryNet AI 对您有帮助请 ⭐ **点亮此仓库**！

标签：AV绕过, FastAPI, IP 地址批量处理, scikit-learn, 后端开发, 异常检测, 测试用例, 网络安全, 网络流量分析, 自动化威胁响应, 请求拦截, 逆向工具, 隐私保护