Divyesh-Kamalanaban/zeeksight

# ZeekSight 自主的一级 SOC 分诊 — 从原始数据包到基于 RFC 的诊断。        ## 概述 ZeekSight 是一个自主的一级 SOC 分诊 Agent，能够自动化安全运营中心分析师的首次响应工作流。 它接收原始数据包捕获，通过 Zeek 处理它们以生成结构化的网络日志，使用基于特征的检测来发现异常，通过 pgvector RAG pipeline 检索权威的 RFC 文档，并生成基于协议标准的结构化分诊报告 — 所有这些均无需人工干预。 **旨在替代一级分析师盯着原始 Zeek 日志所花费的 30-60 分钟手动分诊周期**，改用一个能够在几秒钟内完成诊断、分类和升级的自主 Agent。 ## 架构

### 混合路由 ZeekSight 实现了两条 Agent 路径： | 路径 | 触发条件 | 检索方式 | |---|---|---| | 已知攻击 | 特征匹配 | 从 pgvector 进行确定性预检索 | | 未知模式 | 无特征匹配 | 通过 agentic loop 进行 LLM 驱动的工具调用 | ## 评估结果 使用 DeepEval 4.0.7 进行评估，并通过 LM Studio 使用 Gemma 4 12B 作为 LLM 评委。 | 指标 | 分数 | 阈值 | 状态 | |---|---|---|---| | 上下文精确度 (RAG) | **1.0** | 0.7 | ✓ 通过 | | 上下文召回率 (RAG) | **1.0** | 0.7 | ✓ 通过 | | 忠实度 (Agent) | **1.0** | 0.7 | ✓ 通过 | | 答案相关性 (Agent) | **1.0** | 0.7 | ✓ 通过 | | SYN Flood 检测置信度 | **0.99** | — | — | ## RAG Pipeline | 组件 | 选择 | 理由 | |---|---|---| | 向量存储 | pgvector (PostgreSQL) | 生产级、可更新、无供应商锁定 | | 索引 | HNSW | 高准确性，随语料库增长而扩展，对于中小型语料库优于 IVF | | 分块 | 基于 TOC 的语义分块 | RFC 章节边界是自然的语义单元 | | 重叠 | 200 字符重叠 | 保留章节边界的上下文 | | Embeddings | nomic-embed-text (LM Studio) | 本地、免费、768 维 | ### RFC 语料库 | RFC | 标题 | 作用 | |---|---|---| | RFC 9293 | 传输控制协议 | TCP 规范，状态机 | | RFC 4987 | TCP SYN Flooding 攻击 | 主要的 SYN flood 参考 | | RFC 3552 | 安全注意事项指南 | 用于跨 RFC 语义基础的元文档 | ## Agent 输出 ``` { "attack_type": "SYN Flood", "confidence": 0.99, "severity": "CRITICAL", "explanation": "The connection metrics show a massive volume of half-open connections (S0) originating from 37,621 unique source IPs targeting a single destination port (25565). This aligns with RFC 4987, which describes a SYN flooding attack as a denial-of-service method that exploits TCP state retention to exhaust the backlog of half-open connections.", "rfc_citation": "RFC 4987, Section 1 and Section 2", "recommendation": "ESCALATE", "timestamp": "2021-04-28T10:30:44Z" } ``` ## 检测逻辑 ZeekSight 使用带有数学推导置信度分数的基于特征的检测系统。 ### 攻击特征 ``` ATTACK_SIGNATURES = { "SYN Flood": { "conditions": { "s0_rate": (">", 0.8), # half-open connection rate "unique_src_ips": (">", 50), # spoofed source diversity }, "proto": "tcp", }, "Port Scan": { "conditions": { "unique_dst_ports": (">", 100), "unique_src_ips": ("==", 1), }, "proto": "tcp", }, } ``` ### 置信度分数 置信度来源于观察到的指标超出特征阈值的程度： ``` score per condition = min(observed / threshold, 1.0) confidence = mean(condition scores), capped at 0.99 ``` 这是**特征匹配置信度**，而不是概率估计。添加新的攻击类型只需要一个字典条目 — 无需更改代码。 ## 监控 ZeekSight 使用时间窗口聚合策略实时监控 `conn.log`： ``` Watchdog thread → detects file changes → appends to buffer (thread-safe) Analysis thread → wakes every 10s → drains buffer → computes metrics → threshold check → invokes agent if suspicious → cooldown (30s) prevents duplicate alerts ``` 这确保了 S0 速率是在有意义的采样窗口上计算的，而不是按行计算，从而避免了由于对同一攻击事件重复触发而产生的告警疲劳。 ## 项目结构 ``` zeeksight/ ├── agent/ │ ├── agent.py # LangGraph graph, nodes, routing │ ├── tools.py # Deterministic tool definitions │ └── rag.py # pgvector ingestion and retrieval ├── rag_corpus/ │ ├── rfc9293.txt │ ├── rfc4987.txt │ └── rfc3552.txt ├── pcaps/ │ └── synflood.pcap ├── logs/ # Zeek output directory ├── dataframes/ # Parsed CSVs ├── evals/ │ ├── test_unit.py # Unit tests (no external deps) │ ├── test_rag.py # RAG retrieval evals │ └── test_agent.py # Agent triage evals ├── docs/ │ └── assets/ │ └── zeeksight-architecture.png ├── monitor.py # Live monitoring loop ├── requirements.txt ├── .env.example └── README.md ``` ## 技术栈 | 层级 | 技术 | |---|---| | 数据包分析 | Zeek 8.2.0 | | 日志解析 | ZAT 0.4.9 + Pandas | | Agent 框架 | LangGraph 1.2.6 | | LLM | Gemma 4 12B QAT | | Embeddings | 通过 LM Studio 的 nomic-embed-text | | 向量存储 | pgvector 0.4.2 + HNSW | | 时间序列数据库 | InfluxDB 2.7 | | 仪表板 | Grafana | | 评估 | DeepEval 4.0.7 + Gemma 4 12B 评委 | | 语言 | Python 3.14 | ## 快速开始 ### 前置条件 - Docker - Python 3.11+ - Zeek 8.x - 加载了 `nomic-embed-text` 的 LM Studio ### 1. 克隆并安装 ``` git clone https://github.com/Divyesh-Kamalanaban/zeeksight.git cd zeeksight python -m venv venv && source venv/bin/activate pip install -r requirements.txt ``` ### 2. 启动基础设施 ``` # pgvector sudo docker run -d \ --name pgvector \ --network bridge \ --restart unless-stopped \ -e POSTGRES_PASSWORD=zeeksight \ -e POSTGRES_DB=zeeksight \ -p 127.0.0.1:5432:5432 \ pgvector/pgvector:pg16 # InfluxDB docker run -d --name influxdb \ -p 8086:8086 \ -e DOCKER_INFLUXDB_INIT_MODE=setup \ -e DOCKER_INFLUXDB_INIT_USERNAME=admin \ -e DOCKER_INFLUXDB_INIT_PASSWORD=zeeksight123 \ -e DOCKER_INFLUXDB_INIT_ORG=zeeksight \ -e DOCKER_INFLUXDB_INIT_BUCKET=zeeksight \ -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=your-token-here \ influxdb:2.7 # Grafana docker run -d --name grafana \ -p 3000:3000 \ grafana/grafana:latest ``` ### 3. 配置环境 ``` cp .env.example .env # 使用你的凭据编辑 .env ``` ### 4. 导入 RFC 语料库 ``` wget https://www.rfc-editor.org/rfc/rfc9293.txt -P rag_corpus/ wget https://www.rfc-editor.org/rfc/rfc4987.txt -P rag_corpus/ wget https://www.rfc-editor.org/rfc/rfc3552.txt -P rag_corpus/ python agent/rag.py ``` ### 5. 对 pcap 运行分诊 ``` mkdir -p logs zeek -r pcaps/synflood.pcap Log::default_logdir=$(pwd)/logs python agent/agent.py ``` ### 6. 运行实时监控 ``` # Terminal 1 python monitor.py # Terminal 2 zeek -r pcaps/synflood.pcap Log::default_logdir=$(pwd)/logs ``` ## 运行测试 ``` # 单元测试 — 不需要外部 deps pytest evals/test_unit.py -q # RAG eval — 需要 pgvector + LM Studio deepeval test run evals/test_rag.py # Agent eval — 需要全栈 deepeval test run evals/test_agent.py ``` ## 环境变量 ``` # .env.example INFLUX_URL=http://localhost:8086 INFLUX_TOKEN=your_token_here INFLUX_ORG=zeeksight INFLUX_BUCKET=zeeksight LOCAL_MODEL_API_KEY=lm-studio LM_STUDIO_MODEL="google/gemma-4-12b-qat [Model of your choice]" DEEPEVAL_RESULTS_FOLDER="./my_results" CONN_LOG_PATH=logs/conn.log ``` ## 路线图 - [ ] 带有预构建面板的 Grafana 仪表板 - [ ] 用于一键设置的 Docker Compose - [ ] UDP flood 和 ICMP flood 攻击特征 - [ ] 额外的 RFC 语料库（RFC 4732 — DoS 考量） - [ ] 在正常流量 pcap 上的误报率基准测试 - [ ] 多攻击场景的评估覆盖范围 ## 为什么选择 ZeekSight | 问题 | ZeekSight | |---|---| | 一级分析师在每个告警上花费 30-60 分钟 | Agent 在几秒钟内完成分诊 | | 原始 Zeek 日志需要专家解读 | 基于 RFC 的通俗英文解释 | | 基于规则的 IDS 不提供上下文 | RAG 检索引用权威标准 | | 重复通知导致告警疲劳 | 时间窗口聚合 + 30秒冷却时间 | | 静态检测规则无法扩展 | 特征字典 — 新攻击 = 8 行配置 | ## 参考 - [RFC 9293 — 传输控制协议](https://www.rfc-editor.org/rfc/rfc9293) - [RFC 4987 — TCP SYN Flooding 攻击及常见缓解措施](https://www.rfc-editor.org/rfc/rfc4987) - [RFC 3552 — 编写 RFC 安全考量文本指南](https://www.rfc-editor.org/rfc/rfc3552) - [Zeek 网络安全监控器](https://zeek.org) - [SYN Flood 数据包捕获](https://github.com/StopDDoS/packet-captures/tree/main) - [Corelight — 生产环境 Zeek](https://corelight.com) ## 许可证 MIT © [Divyesh Kamalanaban](https://github.com/Divyesh-Kamalanaban)

标签：LLM代理, Python, RAG, SOC自动化, WSL, 安全运营, 扫描框架, 无后门, 测试用例, 网络流量分析, 请求拦截, 逆向工具