JustinwkWan/NetSentinel

# NetSentinel 一款用于网络安全的 AI agent，能够获取 PCAP 文件（或实时流量），检测异常网络流，并使用由 CVE 和 MITRE ATT&CK 威胁情报支持的 ReAct 风格 agent 循环自主调查每个标记的流。输出结果为结构化的威胁报告，可在 Web 仪表板或 CLI 中查看。 ## 架构 ``` PCAP file / live capture | v [ Ingestion ] ---> FlowRecords (aggregated network flows) | v [ Detection ] ---> FlaggedFlows (anomalous flows with scores) | v [ Agent (LangGraph ReAct loop) ] |--- cve_lookup tool ---------> [ RAG Store (ChromaDB) ] |--- attack_technique_lookup -> [ RAG Store (ChromaDB) ] | v [ Structured Threat Reports ] | +--> CLI output +--> FastAPI backend ---> React dashboard ``` **4 个核心层：** 1. **Ingestion** - 通过与源无关的 `PacketSource` 接口读取 PCAP/pcapng 文件，将数据包聚合为带有派生特征（数据包速率、平均数据包大小）的 `FlowRecord` 对象。 2. **Detection** - 使用 `Detector` 协议标记异常流。可通过 `--detector` 标志选择 `StubDetector`（基于规则）和 `LstmDetector`（在正常流量上训练的 LSTM autoencoder）。 3. **Agent** - LangGraph ReAct 循环，用于调查每个标记的流。Agent 会决定调用哪些工具，对结果做出反应，并决定何时生成报告。设置硬迭代上限作为护栏。 4. **RAG** - 包含 CVE 条目和 MITRE ATT&CK 技术的 ChromaDB 向量存储，在自然边界上进行切分（一个 CVE = 一个 chunk，一个技术 = 一个 chunk）。 另外还有建立在基础之上的两个同级层： - **Evaluation** (`eval/`) - LLM-as-judge 评估工具，使用偏见缓解措施（rubric 评分、反冗长、可替换的 judge 模型），根据带标签的数据集对 agent 报告进行评分。 - **Web app** (`api/` + `web/`) - FastAPI 后端和 React 仪表板，用于运行 pipeline、浏览本地 pcap 以及从浏览器驱动实时捕获。 ## 技术栈 - **编程语言：** Python（核心）+ TypeScript（前端） - **数据包处理：** scapy - **异常检测：** PyTorch（LSTM autoencoder） - **向量存储：** ChromaDB - **Agent 编排：** LangGraph（ReAct 循环） - **LLM：** Anthropic Claude API（通过兼容 Anthropic 的 endpoint 支持 DeepSeek） - **后端 API：** FastAPI + Uvicorn - **前端：** React + Vite + Tailwind CSS - **实时捕获：** dumpcap (Wireshark) ring buffer - **CLI 入口点：** `netsentinel/cli.py` ## 设置 ### 前置条件 - Python 3.10+ - [Anthropic API key](https://console.anthropic.com/)（或 DeepSeek key —— 参见配置） - Node.js 18+ 和 npm —— 仅用于 Web 仪表板 - Wireshark / `dumpcap` —— 仅用于实时捕获 ### 安装 ``` # 克隆 repository git clone https://github.com/JustinwkWan/NetSentinel.git cd NetSentinel # 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt ``` ### 配置 在项目根目录下创建一个包含您的 API key 的 `.env` 文件： ``` cp .env.example .env # 编辑 .env 并添加你的 API key ``` ``` ANTHROPIC_API_KEY=your-api-key-here ``` **使用 DeepSeek（或其他兼容 Anthropic 的提供商）：** 改为设置 model， base URL 和 key。NetSentinel 通过 `langchain-anthropic` 与任何兼容 Anthropic 的 endpoint 通信。 ``` LLM_MODEL=deepseek-v4-pro LLM_BASE_URL=https://api.deepseek.com/anthropic DEEPSEEK_API_KEY=your-deepseek-key ``` 所有可调设置（模型名称、检索 `k` 值、agent 迭代上限， 检测器阈值、路径）都位于 `config.py` 中 —— 代码中没有散落的魔法数字。 ### 构建 RAG Store 在运行 pipeline 之前，使用威胁情报数据构建 ChromaDB 向量存储： ``` python scripts/build_rag_store.py ``` 这将在 `data/chroma/` 处创建一个 ChromaDB collection，其中包含 CVE 条目（以及第二阶段的 ATT&CK 技术）。 ## 用法 ### 在 PCAP 文件上运行 pipeline ``` python -m netsentinel.cli # 使用 LSTM detector 替代默认 stub python -m netsentinel.cli --detector lstm ``` 使用内置示例： ``` python -m netsentinel.cli data/pcaps/sample_suspicious.pcap python -m netsentinel.cli data/pcaps/sample_suspicious.pcap --detector lstm ``` 该 pipeline 将： 1. 解析 PCAP 并组装网络流 2. 标记可疑流（stub：基于规则，lstm：重建误差） 3. 使用 AI agent 调查每个标记的流 4. 打印结构化的威胁报告 ### 训练 LSTM 检测器 ``` # 生成用于训练的正常流量 python scripts/generate_training_pcap.py # 训练模型 python scripts/train_lstm.py ``` ### 运行演示 ``` python scripts/run_demo.py ``` ### Web app（仪表板） Web app 提供了一个浏览器 UI，用于运行 pipeline 和查看报告， 无需解析终端输出。它由两部分组成：FastAPI 后端和 React/Vite 前端。 ``` # Terminal 1 — backend (http://127.0.0.1:8765) source venv/bin/activate uvicorn api.main:app --host 127.0.0.1 --port 8765 --reload # Terminal 2 — frontend (http://localhost:5173) cd web npm install # first time only npm run dev ``` 打开 http://localhost:5173。在仪表板中，您可以： - **从 `data/pcaps/` 运行** — 从下拉菜单中选择一个内置的 pcap，或上传一个。 - **浏览本地文件夹** — 将后端指向您机器上的任意文件夹并就地运行 pcap（无需复制）。 - **实时捕获** — 启动/停止滚动捕获；每个完成的窗口都会被自动分析。 - **查看报告** — 每个被标记流的严重程度、威胁类型、摘要、CVE、ATT&CK 技术和修复建议，以及运行历史记录。 前端将 `/api/*` 代理到后端（参见 `web/vite.config.ts`）。 ### 实时捕获 将实时流量捕获到滚动的 pcapng ring buffer 中，并在每个窗口完成时进行分析。 有两种驱动方式： **从仪表板** — 使用“实时捕获”面板（开始/停止，接口， 检测器）。后端管理 `dumpcap` 并在每次关闭轮转时自动运行 pipeline，在停止时清理捕获文件。 **从 CLI** — 两个独立脚本： ``` # Terminal A — 捕获 60秒窗口，10文件滚动缓冲区（约10分钟） sudo ./scripts/live_capture.sh # Terminal B — 在每个已完成窗口上运行 pipeline DETECTOR=lstm ./scripts/watch_and_run.sh ``` ### 评估测试工具 使用带有偏见缓解措施的 LLM-as-judge 对带标签数据集中的 agent 报告进行评分 （基于 rubric 的评分、反冗长指令、可通过 `EVAL_JUDGE_MODEL` 更换的 judge 模型）。 ``` # 运行完整 eval set python -m eval.harness --save # 运行特定用例 python -m eval.harness --cases reverse_shell_4444 ssh_brute_force ``` 结果会打印出每个 case 的明细以及总分，`--save` 会将 原始结果写入 `data/eval/eval_results.json`。 ### 运行测试 ``` pytest tests/ ``` ## 项目结构 ``` NetSentinel/ ├── config.py # Central config (model, k values, thresholds) ├── data/ │ ├── pcaps/ # Sample + live-capture PCAP files │ ├── threat_intel/ # Raw CVE/ATT&CK data │ ├── chroma/ # ChromaDB store (gitignored, built by script) │ └── eval/ # Eval results (gitignored) ├── netsentinel/ │ ├── cli.py # CLI entry point │ ├── ingestion/ │ │ ├── sources.py # PacketSource interface, PcapFileSource │ │ └── flows.py # FlowRecord dataclass │ ├── detection/ │ │ ├── base.py # Detector Protocol, FlaggedFlow │ │ ├── stub.py # StubDetector (rule-based) │ │ └── lstm.py # LstmDetector (LSTM autoencoder) │ ├── rag/ │ │ ├── store.py # ChromaDB query interface │ │ ├── chunking.py # Natural-boundary chunkers │ │ └── build_store.py # Download + chunk + embed CVE/ATT&CK │ └── agent/ │ ├── graph.py # LangGraph ReAct graph │ ├── state.py # Agent state definition │ ├── tools.py # cve_lookup, attack_technique_lookup │ ├── prompts.py # System and investigation prompts │ └── report.py # ThreatReport dataclass ├── eval/ # Evaluation harness (LLM-as-judge) │ ├── dataset.py # Labeled eval cases │ ├── judge.py # Rubric-based judge with bias mitigations │ ├── harness.py # Runs agent + judge over the dataset │ └── report.py # Aggregate scoring + summary ├── api/ # FastAPI backend │ ├── main.py # Routes: pcaps, runs, capture, local browse │ ├── jobs.py # Background job store + pipeline orchestrator │ ├── capture.py # Live-capture manager (dumpcap ring buffer) │ └── models.py # Pydantic schemas ├── web/ # React + Vite + Tailwind dashboard │ └── src/ │ ├── api.ts # Typed API client │ └── components/ # PcapSelector, RunControls, LiveCapturePanel, … ├── scripts/ │ ├── build_rag_store.py # Build the RAG store │ ├── generate_training_pcap.py # Generate normal traffic for LSTM training │ ├── train_lstm.py # Train the LSTM detector │ ├── run_demo.py # Run the demo │ ├── live_capture.sh # dumpcap rolling-window capture │ └── watch_and_run.sh # Auto-run pipeline on each captured window └── tests/ ``` ## 构建阶段 - [x] **Phase 1** - 骨架端到端 agent（PCAP -> StubDetector -> 最小化 RAG -> LangGraph 循环 -> 报告） - [x] **Phase 2** - 完整 RAG 层（真实 CVE/ATT&CK 数据，自然切分，第二个工具） - [x] **Phase 3** - LSTM autoencoder 检测器（在正常流量上训练，通过重建误差标记异常流） - [x] **Phase 4** - 使用 LLM-as-judge 的评估工具（rubric 评分 + 偏见缓解措施） - [x] **Phase 5** - Web 仪表板（FastAPI + React），实时捕获和本地文件夹浏览 ## 设计决策 - **检索：** top-k 为 3-5，绝不使用 20。Chunk 遵循自然边界（一个 CVE = 一个 chunk）。 - **Agent 循环：** 硬迭代上限作为护栏。终止动作是一个明确的“生成报告”步骤。 - **工具返回结构化、简洁的结果** - 绝不直接倾倒原始文档。 - **工具优雅地失败** - 返回“无相关结果”消息，绝不抛出异常。 - **与源无关的 Ingestion** - `PacketSource` 协议允许在不触及下游代码的情况下切换至实时捕获。 - **Detector 协议** - LSTM 可通过一行配置更改进行替换。 - **Eval judge 偏见缓解措施** - 基于 rubric 的评分（而非整体偏好），明确的反冗长指令，以及可以使用与 agent 模型不同的 judge 模型。 - **通过 ring buffer 进行实时捕获** - `dumpcap` 负责轮转和保留（固定大小窗口的滚动窗口）；监视器仅对已关闭的文件触发分析。文件在停止时会被清理。 - **本地优先的 Web app** - 后端绑定到 localhost，可以从任何本地文件夹就地运行 pcap，无需上传/复制。 完整的技术设计文档请参见 [Design.md](Design.md)。

标签：AV绕过, DLL 劫持, FastAPI, React, Syscalls, 凭据扫描, 大语言模型, 威胁情报, 开发者工具, 网络安全, 网络流量分析, 逆向工具, 隐私保护