beratkrmn7/Agentic-SOC-Triage-Assistant

# Agentic SOC Triage 助手 一个基于 LangGraph 的 Agentic SOC Triage Assistant PoC，它结合了确定性检测规则、受约束的基于 LLM 的 triage、证据验证和简明的 SOC 报告。 本项目是一个 Agentic SOC Triage PoC 系统，它通过分析安全日志，为 SOC 分析师生成基于证据的 triage 决策和简短的事件报告。 ## 系统概述 本项目不是简单的 LLM 聊天机器人。原始日志首先会被归一化，并由确定性的 Python 检测规则进行分析。在调用 LLM 之前，这些规则会生成检测到的信号和候选证据。然后，Triage Agent 会审查这些信号，可选择调用 `search_logs` 工具获取额外上下文，并提交结构化的 triage 决策。在生成最终报告之前，每个证据项都会与原始日志进行比对验证。 最终输出是一份简明的 SOC triage 报告，重点关注以下四个问题： 1. 发生了什么？ 2. 为什么它可疑或良性？ 3. 有什么证据支持该判定？ 4. 分析师接下来应该做什么？ ## 架构 该工作流被实现为一个受控的 LangGraph 状态机。确定性节点负责提取、检测、验证、MITRE 映射和操作建议。LLM 被限制在 triage 和报告生成阶段，从而降低幻觉风险并确保决策基于证据。  其核心思想是，LLM 不仅仅直接根据原始日志做出决定。它接收确定性信号和候选证据，并且其输出在报告之前会经过验证。 ## 核心功能 - **基于 LangGraph 的 Agentic 工作流：** 系统被构建为一个受控的状态机，而不是自由形式的聊天机器人。 - **确定性预分析：** Python 检测规则在调用 LLM 之前识别可疑或良性的模式。 - **候选证据生成：** 检测规则生成包含 `event_id`、`quote`、`reason` 和 `source` 的结构化证据。 - **受约束的 Triage Agent：** LLM 只能使用有限的工具，如 `search_logs` 和 `submit_triage_result`。 - **证据验证：** 每个提交的证据项都会与原始日志进行核对。 - **needs_review 回退机制：** 无效、缺失或薄弱的证据可防止不安全的自动化决策。 - **MITRE ATT&CK 映射：** 相关的事件类型被映射到 ATT&CK 技术。 - **简明的 SOC 报告：** 报告简短、基于证据，并专注于分析师的决策。 - **FastAPI 支持：** 工作流可以通过 REST 端点使用。 - **Pytest 覆盖：** 确定性检测和验证逻辑由测试覆盖。 ## 为什么这不只是一个 LLM 聊天机器人 一个简单的聊天机器人会将原始日志直接发送给 LLM，并返回自由格式的答案。本项目使用受控的 Agentic 工作流： 1. 日志使用事件 ID 进行归一化。 2. 确定性检测规则生成信号和候选证据。 3. Triage Agent 审查结构化证据，并可能调用工具获取更多上下文。 4. Triage 结果必须遵循严格的 Pydantic schema。 5. 证据会与原始日志进行比对验证。 6. 最终报告仅基于经过验证的证据和确定性建议生成。 这使得该系统成为一个受控的 Agentic SOC Triage PoC，而不是普通的 LLM 聊天机器人。 ## 报告生成 报告生成层特意保持简明并优先考虑证据。其目标不是生成冗长的通用安全报告，而是创建一份可以快速理解的简短 SOC triage 报告。 每份报告回答四个问题： 1. **判定：** 事件是误报、可疑活动、已确认的事件，还是需要人工审查？ 2. **为何重要：** 为什么日志可疑、恶意、良性或无法定论？ 3. **关键证据：** 哪些经过验证的事件 ID 和日志引用支持该决策？ 4. **建议操作：** 分析师接下来应该做什么？ 该报告设计得简短易读。除非日志提供直接证据，否则它会避免提出数据外泄、帐户失陷或数据库失陷等未经证实的声明。 ### 报告格式示例 ## 技术栈 - Python 3.10+ - LangGraph - LangChain / LangChain Groq - 使用 Llama 3.3 70B 的 Groq API - Pydantic - FastAPI - Uvicorn - Pytest - 用于终端输出的 Rich ## 项目结构 ``` SOC-Project/ ├── agent/ │ ├── graph.py # LangGraph workflow definition │ ├── nodes.py # Workflow nodes: extraction, detection, triage, validation, reporting │ ├── tools.py # LLM-accessible tools and deterministic detection functions │ └── models.py # Pydantic schemas and LangGraph state definitions ├── data/ │ └── mock_logs.json # Mock SOC incident dataset ├── tests/ │ ├── test_detection_tools.py │ ├── test_evidence_validation.py │ ├── test_reporter_output.py │ └── test_graph_smoke.py ├── main.py # Terminal-based test runner ├── server.py # FastAPI server ├── requirements.txt └── README.md ``` ## 快速开始 ### 1. 安装依赖 ``` pip install -r requirements.txt ``` ### 2. 配置环境变量 创建 `.env` 文件： ``` GROQ_API_KEY=your_groq_api_key_here ``` 请勿将 `.env` 提交到 GitHub。 ### 3. 运行终端演示 ``` python main.py ``` 运行所有模拟事件： ``` RUN_ALL=true python main.py ``` ### 4. 运行 API 服务器 ``` python server.py ``` 打开 Swagger UI： ``` http://localhost:8000/docs ``` ### 5. 运行测试 ``` pytest ``` ## API 端点 ### 健康检查 ``` GET /health ``` ### 分析事件 ``` POST /analyze ``` 请求示例： ``` { "incident_id": "INC-001", "raw_logs": [ { "timestamp": "2023-10-27T10:15:00Z", "src_ip": "192.168.1.100", "dst_ip": "10.0.0.5", "event_type": "HTTP_GET", "raw_message": "GET /index.html HTTP/1.1 200 OK" } ] } ``` ### 获取报告 ``` GET /incident/{incident_id}/report ``` ## 模拟数据集 本项目包含涵盖可疑活动和误报的模拟 SOC 事件： - 标准的良性 Web 流量 - 失败的 SSH 暴力破解尝试 - SQL 注入尝试 - 正常的管理员登录误报 - 端口扫描活动 - 暴力破解后成功登录 - XSS 负载尝试 - 可疑的 PowerShell 命令 - 恶意软件哈希警报 - DNS 隧道模式 - 通过 SMB/PsExec 进行的横向移动 - 内部备份流量误报 ## 局限性 本项目是一个 PoC，并不旨在替代生产级别的 SIEM、SOAR 或 SOC 平台。 当前局限性： - 使用模拟日志数据，而不是真实的 SIEM 后端。 - 检测规则为了演示进行了简化。 - 尚未包含威胁情报集成。 - LLM 用于 triage 综合，因此其输出受到限制和验证。 - 使用内存中的 API 存储而不是持久化数据库。 ## 未来工作 可能的改进： - Elasticsearch 或 OpenSearch 集成 - VirusTotal / AbuseIPDB 威胁情报查询 - 持久化的事件数据库 - 面向分析师的 Web 仪表板 - 更多 MITRE ATT&CK 映射 - Human-in-the-loop 审批工作流 - Docker 部署 - 更逼真的日志归一化 pipeline ## 安全提示 切勿提交 `.env` 文件或 API 密钥。使用 `.env.example` 进行文档记录，并将真实的凭据保存在本地。

标签：AI智能体, DLL 劫持, LangGraph, 告警分诊, 大语言模型, 安全运营中心, 网络映射, 逆向工具