joanne-j-m/SentinelOps

# 🛡️ Sentinel-Ops **自主多 Agent 威胁狩猎 Pipeline** Sentinel-Ops 是一个有状态的多 Agent 网络安全 pipeline，能够自主调查安全警报。只需提交一段威胁描述，即可目睹四个专业 AI Agent 实时协作，完成对威胁的分类、调查、富化与报告——全面涵盖 MITRE ATT&CK 映射、威胁情报查询、Discord 通知以及实时网站监控。 ## 演示     ## 架构 ``` ┌─────────────────────────────────┐ │ FastAPI Backend │ │ POST /jobs · GET /jobs/{id} │ │ X-API-Key auth on mutations │ └────────────┬────────────────────┘ │ ┌────────────▼────────────────────┐ │ LangGraph State Machine │ │ │ │ ┌────────────┐ │ │ │ Supervisor │ classify alert │ │ └─────┬──────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ Scout │ extract IOCs │ │ └─────┬──────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ Analyst │ enrich + score │ │ └─────┬──────┘ │ │ │ confidence < 0.6? │ │ ├──────────────► Scout │ │ │ (autonomy loop) │ │ ┌─────▼──────┐ │ │ │ Reporter │ compile + notify│ │ └────────────┘ │ └─────────────────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ┌──────▼──────┐ ┌────────▼───────┐ ┌────────▼───────┐ │ Discord │ │ Omium Tracing │ │ React Dashboard│ │ Webhook │ │ (spans) │ │ localhost:8000 │ └─────────────┘ └────────────────┘ └────────────────┘ ▲ ┌────────┴───────┐ │ monitor.py │ │ (proxy/detect) │ └────────────────┘ ``` ## Agent | Agent | 职责 | 技术 | |---|---|---| | **Supervisor** | 分类警报类型和严重程度，分解任务 | 通过 Groq 运行的 Llama 3 | | **Scout** | 提取 IOC（IP、哈希、CVE），重构日志 | Regex + Llama 3 | | **Analyst** | 使用威胁情报富化证据，评估置信度评分 | Tavily Search + Llama 3 | | **Reporter** | 汇编威胁情况说明书，发送通知 | Llama 3 + Discord/Slack | ## 功能特性 - **自主循环** — 若置信度 < 60%，Analyst 会回退至 Scout 重新调查 - **真实 IOC 提取** — IP、MD5/SHA1/SHA256 哈希、CVE、域名 - **IP 分类** — 将攻击者 IP 与受害主机区分开来 - **威胁情报** — 通过 Tavily 网络搜索获取实时 IP/CVE 信誉 - **MITRE ATT&CK 映射** — 根据威胁类型自动推断战术 - **Discord/Slack 通知** — 任务完成后发送富嵌入内容 - **Omium 追踪查看器** — 具备自动 LangGraph 追踪和 checkpoint 的全流程 pipeline 可观测性 - **实时网站监控** — `monitor.py` 代理可实时检测 SQLi、XSS、路径遍历和暴力破解 - **自动提交警报** — 监控器将检测到的威胁直接推送到仪表板 - **API 密钥认证** — 所有修改性 endpoint 均需提供 `X-API-Key` header - **输入清理** — 在输入 LLM 前剥离控制字符并限制最大长度为 5000 字符 - **线程安全的任务存储** — 深拷贝隔离防止了轮询线程与 graph 线程之间的竞态条件 - **延迟图初始化** — pipeline 在首次使用时编译，而非在导入时 - **指数退避** — 遇到 Groq 速率限制时自动重试 - **健壮的 JSON 解析** — 括号平衡提取器 + 针对格式错误 LLM 响应的重试逻辑 - **SentinelAdapter** — 兼容 P&E bench 的适配器模式 ## 技术栈 | 层级 | 技术 | |---|---| | 后端 | FastAPI + Python 3.14 | | Agent 框架 | LangGraph 1.2+ | | LLM | 通过 Groq 运行的 Llama 3.3 70B | | 威胁情报 | Tavily Search API | | 前端 | React 18（无需构建步骤） | | 通知 | Discord + Slack Webhooks | | 追踪 | Omium（自动 LangGraph 埋点 + checkpoint） | | 实时监控 | monitor.py（Flask 反向代理 + 攻击检测器） | | 测试 | pytest（104 个测试） | ## 项目结构 ``` sentinel-ops/ ├── main.py # Entry point ├── monitor.py # Live website monitor + attack simulator ├── requirements.txt ├── .env.example # Environment variable template ├── frontend/ │ └── index.html # React dashboard (no npm needed) ├── backend/ │ ├── core/ │ │ ├── state.py # Shared LangGraph state schema │ │ ├── job_store.py # Thread-safe in-memory job registry │ │ ├── llm.py # Groq client with retry + backoff │ │ ├── ioc_parser.py # Regex IOC extractor │ │ ├── ip_classifier.py # Attacker vs victim IP classifier │ │ ├── search.py # Tavily threat intel search │ │ ├── notify.py # Discord + Slack dispatcher │ │ ├── omium.py # Omium trace + checkpoint integration │ │ └── tracing.py # Trace span context manager │ ├── agents/ │ │ ├── supervisor.py # Alert classification agent │ │ ├── scout.py # IOC extraction agent │ │ ├── analyst.py # Threat enrichment agent │ │ └── reporter.py # Fact sheet + notification agent │ ├── graph/ │ │ └── pipeline.py # LangGraph StateGraph definition (lazy init) │ ├── adapters/ │ │ └── sentinel.py # SentinelAdapter (P&E bench) │ └── api/ │ ├── app.py # FastAPI factory + CORS config │ └── routes.py # API endpoints + auth middleware └── tests/ ├── test_phase1.py # Graph wiring + adapter tests ├── test_phase2.py # IOC parser + search tests ├── test_phase3.py # Notification + tracing tests ├── test_phase5.py # JSON retry + IP classifier tests └── test_phase7_fixes.py # Security, correctness, and type-safety tests ``` ## 快速开始 ### 1. 克隆并设置 ``` git clone https://github.com/vpadival/sentinel-ops.git cd sentinel-ops python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # Mac/Linux pip install -r requirements.txt pip install pytest ``` ### 2. 配置环境 ``` cp .env.example .env ``` 编辑 `.env` 并填入： ``` GROQ_API_KEY=gsk_... # https://console.groq.com TAVILY_API_KEY=tvly-... # https://app.tavily.com DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... # Optional OMIUM_API_KEY=... # https://omium.ai ``` ### 3. 运行测试 ``` python -m pytest tests/ -v # 104 passed ``` ### 4. 启动服务器 ``` python main.py ``` ### 5. 打开仪表板 ``` http://localhost:8000 ``` ## 实时网站监控 `monitor.py` 可作为任何网站前的反向代理，自动检测攻击——包括 SQL 注入、XSS、路径遍历、命令注入、暴力破解以及扫描器机器人。检测到的威胁将被直接推送到 Sentinel-Ops 仪表板。 ### 作为代理运行（监控真实流量） ``` # Terminal 1 — 在你的网站前启动代理 python monitor.py --target http://localhost:3000 --port 9000 # 通过 monitor 访问你的网站： # http://localhost:9000 ``` ### 运行攻击模拟器（演示模式） ``` # Terminal 1 — 启动代理 python monitor.py --target http://localhost:8000 --port 9000 # Terminal 2 — 模拟攻击 python monitor.py --simulate ``` 在 `http://localhost:8000` 查看 Sentinel-Ops 仪表板——警报会自动出现，Agent 将实时展开调查。 ### 检测到的攻击类型 | 攻击 | 检测方法 | |---|---| | SQL 注入 | 对 URL + body 进行正则匹配（UNION SELECT, DROP TABLE 等） | | XSS | Script 标签、javascript: URI、事件处理器 | | 路径遍历 | `../` 序列、`/etc/passwd`、`/windows/system32` | | 命令注入 | Shell 元字符、反引号、`$(...)` | | 暴力破解 | 速率限制 — 阈值为 60 秒内 30 次请求 | | 扫描器/机器人 | User-agent 匹配（nikto、sqlmap、nmap 等） | | 敏感路径 | `/.env`、`/.git`、`/admin`、`/wp-admin` 等 | ## API 参考 ### 提交任务 ``` POST /api/v1/jobs Content-Type: application/json X-API-Key: your-key-here # required if SENTINEL_API_KEY is set { "problem_statement": "SSH brute-force from 203.0.113.42, 10 failed attempts. CVE-2023-38408 detected." } ``` 响应： ``` { "job_id": "7bb1f521-...", "status": "pending", "message": "Job accepted. Poll GET /jobs/{job_id} for status." } ``` ### 轮询任务状态 ``` GET /api/v1/jobs/{job_id} ``` ### 从监控器推送警报 ``` POST /api/v1/queue Content-Type: application/json X-API-Key: your-key-here { "problem_statement": "SQL injection detected from 1.2.3.4..." } ``` ### 轮询队列（前端自动提交） ``` GET /api/v1/queue ``` ### 摄取 Webhook 警报 ``` POST /api/v1/webhook/alert Content-Type: application/json X-API-Key: your-key-here { "source": "falco", "severity": "WARNING", "rule": "Terminal shell in container", "output": "A shell was spawned in a container..." } ``` ### 健康检查 ``` GET /api/v1/health ``` 响应： ``` { "status": "ok", "version": "0.7.0", "models": { "primary": "llama-3.3-70b-versatile", "fallback": "llama-3.1-8b-instant" }, "keys": { "groq": true, "tavily": true, "discord": true, "omium": true }, "jobs": { "total": 12, "complete": 10, "pending": 2 } } ``` ## 适配器模式（P&E Bench） ``` from backend.adapters.sentinel import SentinelAdapter adapter = SentinelAdapter() result = adapter.execute_task( "SSH brute-force from 203.0.113.42, CVE-2023-38408 detected." ) print(result["fact_sheet"]["severity"]) # HIGH print(result["fact_sheet"]["recommendations"]) # ["Block 203.0.113.42...", ...] print(result["fact_sheet"]["mitre_tactics"]) # ["T1110", "T1190"] ``` ## 用于测试的示例警报 ``` # Brute Force SSH brute-force from 203.0.113.42, 10 failed login attempts on root account. CVE-2023-38408 detected. # Ransomware + C2 Ransomware detected on host 10.0.0.5. Outbound C2 connection to 185.220.101.47 on port 443. 2GB data exfiltrated. # Privilege Escalation Unusual sudo activity on prod-server-01. User jenkins executed chmod 777 /etc/passwd. CVE-2021-4034 polkit exploit detected. # Phishing User clicked suspicious link from ceo@comp4ny.com. Credential harvesting page at 45.33.32.156/login detected. # Malware Hash File hash 3c4b2a1d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b quarantined on WIN-DC-04. Outbound to 91.108.4.1:1337. ``` ## 实施阶段 | 阶段 | 构建内容 | |---|---| | 1 | LangGraph 骨架、状态 schema、桩 Agent、FastAPI、SentinelAdapter | | 2 | 真实的 Groq/Llama 3 LLM 调用、IOC 解析器、Tavily 搜索 | | 3 | Discord/Slack 通知、Omium 追踪 + checkpoint、Analyst 消息修复 | | 4 | 带有实时 Agent pipeline 可视化的 React 任务控制仪表板 | | 5 | JSON 重试逻辑、IP 分类器、指数退避、健康检查 endpoint | | 6 | Omium SDK 集成、实时网站监控（monitor.py）、自动警报队列 | | 7 | API 密钥认证、CORS 加固、线程安全的任务存储、输入清理、延迟图初始化、完整的类型注解、30 个新测试 | ## 安全性 | 控制措施 | 实现方式 | |---|---| | API 认证 | `X-API-Key` header — 在 `.env` 中设置 `SENTINEL_API_KEY` 以启用 | | CORS | 锁定为 `localhost:8000` 和 `localhost:9000` — 无通配符 | | 输入清理 | 剥离控制字符，在输入 LLM 前设置 5000 字符硬性上限 | | 线程安全 | `JobStore.get()` 和 `create()` 返回深拷贝 — graph 线程不会破坏轮询线程的读取 | | 依赖安全 | `monitor.py` 不再通过 subprocess 自动安装包 | ## 依赖项 所有依赖项均在 `requirements.txt` 中列出。核心依赖包括： fastapi>=0.111.0 uvicorn[standard]>=0.29.0 langgraph>=0.2.0 langchain-core>=0.2.19 groq>=0.8.0 python-dotenv>=1.0.1 httpx>=0.27.0 pydantic>=2.7.1 tavily-python>=0.3.0 aiofiles>=23.0.0 omium flask>=3.0.0 flask-cors>=4.0.0

标签：AI安全运营, AV绕过, FastAPI, LangGraph, SOC平台, 告警分诊, 多智能体, 安全规则引擎, 自动化威胁分析, 逆向工具