ShamsKibonge/soc-triage-automation-opensearch

# S.H.A.M.S. - SOC Hunting and Mitigation System **AI 辅助的 SOC 分诊平台，用于 OpenSearch 遥测、分析师案例分组、调查追踪以及 MantisBT 工单工作流。** S.H.A.M.S. 将海量的安全遥测数据转化为分组且具可解释性的调查案例。该项目最初作为网络安全专业的高年级毕业设计开发，在此作为 SOC 自动化、告警分诊和安全工程工作流设计的作品集案例研究进行展示。 ## 执行摘要 安全团队往往拥有足够的日志，却没有足够的时间将这些日志转化为清晰、有证据支持的决策。S.H.A.M.S. 通过收集由 OpenSearch 支持的 Suricata 和 Zeek 遥测数据，将相关事件分组为候选案例，利用 AI 辅助分诊推理，执行后续追踪，并准备带有结构化证据的 MantisBT 工单，从而弥补了这一差距。 该项目展示了一个实用的 SOC 工作流： - 从 OpenSearch 收集并规范化遥测数据。 - 将活动分类为不同的调查类别，例如 C2、恶意软件、暴力破解、DNS 隧道、扫描、漏洞利用尝试以及 Web 漏洞利用。 - 将相关日志分组为带有稳定指纹的候选案例。 - 使用 AI 总结证据、推荐追踪路径，并生成分析师可读的判定结果。 - 保留工单和案例历史记录，以便先前的决策能为未来的分诊提供参考。 - 确保分析师始终掌控最终的工单审核与提交。 ## 安全问题 原始的告警仪表盘可能会让初级分析师不知所措。单一安全事件可能会在 Suricata 告警、Zeek DNS 记录、HTTP 记录、SSL 元数据、通知和连接事件中生成大量日志。分析师必须反复回答同样的问题： - 哪些告警值得调查？ - 多个事件是否属于同一个案例？ - 有哪些证据支持升级、持续监控或关闭？ - 下一步应该检查哪个追踪方向？ - 该源 IP、目标 IP、主机、特征码或 URL 是否曾出现在之前的工单中？ - 能否创建一个带有足够上下文信息的工单，以便其他分析师采取行动？ S.H.A.M.S. 正是围绕这一工作流设计的。它并不声称能检测一切。它的重点在于减少重复的分诊工作，并使证据链更易于审查。 ## 架构 ``` flowchart LR A[Network Security Telemetry] --> B[Suricata and Zeek Events] B --> C[Ingestion Pipeline] C --> D[(OpenSearch Indexes)] D --> E[Node/Express Backend] E --> F[Collector and Classifier] E --> G[Case Grouping and Fingerprinting] E --> H[Pivot Executor] E --> I[AI Investigation Service] E --> J[MantisBT Integration] G --> K[(Local Case and Ticket JSON Stores)] I --> K J --> K E --> L[React Frontend] L --> M[Dashboard v1] L --> N[Case Manager v1] L --> O[Ticket Registry] ``` ## SOC 工作流 ``` flowchart TD A[Refresh OpenSearch telemetry] --> B[Categorize events by SOC use case] B --> C[Group related logs into case candidates] C --> D[Analyst reviews case evidence] D --> E{Run AI analysis?} E -->|Yes| F[AI returns assessment, confidence, verdict, and pivots] F --> G{Pivot needed?} G -->|Yes| H[Execute OpenSearch pivot] H --> I[Reassess with pivot results] I --> J{Ticket recommended?} G -->|No| J E -->|No| J J -->|Yes| K[Check MantisBT duplicates] K --> L[Preview and edit ticket] L --> M[Submit to MantisBT] J -->|No| N[Monitor or close as likely false positive] M --> O[Save local ticket history] N --> O ``` ## 遥测工作流 ``` sequenceDiagram participant OS as OpenSearch participant API as S.H.A.M.S. Backend participant AI as OpenAI API participant UI as React Frontend participant MBT as MantisBT UI->>API: Refresh triage summary API->>OS: Query alert, dns, http, notice, conn, ssl datasets OS-->>API: Matching events API->>API: Normalize fields, filter noise, group cases API-->>UI: Case candidates and evidence samples UI->>API: Analyze selected case API->>AI: Structured case evidence AI-->>API: JSON assessment and recommended pivots UI->>API: Execute pivot API->>OS: Lucene query over OpenSearch time range OS-->>API: Pivot hits and summary UI->>API: Create ticket API->>MBT: MantisBT REST issue create API->>API: Save local ticket history ``` ## 技术栈 | 领域 | 技术 | | --- | --- | | 前端 | React, Create React App, CSS | | 后端 | Node.js, Express, JavaScript ES modules | | 遥测 | OpenSearch, OpenSearch Dashboards 链接, Suricata 风格告警, Zeek DNS/HTTP/SSL/notice/conn 记录 | | AI 工作流 | OpenAI chat completions（结构化 JSON 响应） | | 工单系统 | MantisBT REST API | | 存储 | 本地 JSON 文件，用于生成的分诊摘要、案例管理器状态、案例注册表和工单历史 | | 工具 | npm, PowerShell 辅助脚本 | ## 核心功能 - **OpenSearch 遥测收集**：查询 `alert`, `dns`, `http`, `notice`, `conn` 和 `ssl` 数据集，并存储汇总的分诊输出。 - **安全类别分类**：涵盖 C2/信标、恶意软件、漏洞利用尝试、DNS 隧道、横向移动、暴力破解、侦察、Web 漏洞利用、HTTP 协议异常、双用途基础设施以及外部 IP 发现。 - **案例分组**：将事件分组为确定性的案例记录，包含时间戳、日志计数、源/目标指标、端口、主机、URL、DNS 查询、特征码和样本证据。 - **仪表盘 v1**：提供类别摘要、案例证据、AI 分析、追踪执行、重复检查和工单预览/提交。 - **案例管理器 v1**：运行过去一小时的 OpenSearch 自动分组任务，在本地对案例进行排名，使用 AI 调查重点案例，执行有限的追踪，并显示实时进度。 - **追踪执行**：执行 AI 建议的 OpenSearch 追踪，涵盖源 IP、目标 IP、特征码、CVE、目标端口、HTTP URL、主机、DNS 名称、TLS SNI 以及延长时间窗口。 - **MantisBT 工作流**：检查可能的重复项、创建有证据支撑的工单、同步用户工单历史并存储本地分析师记忆。 - **证据链接**：在环境配置支持的情况下，生成用于案例审查的 OpenSearch Dashboards Discover URL。 ## AI 辅助分诊工作流 AI 层的作用是经过刻意限制的。它接收结构化的案例证据，并返回包含以下内容的 JSON： - 初步威胁评估和分析师推理。 - 判定候选：`ESCALATE`, `LIKELY_FALSE_POSITIVE`, 或 `SUSPICIOUS_MONITOR`。 - 置信度得分和攻击分类。 - 工单建议。 - 最多两个用于后续调查的推荐追踪方向。 随后，应用程序通过 OpenSearch 执行已批准的追踪，并可以利用追踪结果重新评估案例。在提交之前，分析师仍需对工单预览进行审核。 ## MantisBT 工单工作流 S.H.A.M.S. 通过 REST API 与 MantisBT 集成： 1. 从选定的遥测数据中构建案例指纹。 2. 使用 IP、特征码、目标、主机和类别在最近的 MantisBT 工单中搜索可能的重复项。 3. 生成包含评估、证据、追踪、OpenSearch 查询/链接、严重程度、优先级和附加上下文的工单预览。 4. 允许分析师编辑工单字段。 5. 将问题提交至 MantisBT。 6. 保存本地工单历史记录，为未来的分诊提供上下文。 ## 截图 ### 仪表盘概览  Dashboard v1 汇总了基于 OpenSearch 的告警类别和分组的调查案例。 ### 案例证据  分组后的遥测数据在一个可由分析师审查的案例中保留了源、目标、特征码、时间和样本证据。 ### AI 分析与追踪结果  AI 辅助分诊提供有边界的推理、置信度、判定指导和后续的 OpenSearch 追踪。 ### 工单注册表  工单注册表将已创建、已同步和手动添加的 MantisBT 工单保存为本地分析师记忆。 在最终公开发布之前，其他一些有用的截图将包括 MantisBT 工单预览模态框和案例管理器 v1 的实时运行画面。 ## 仓库布局 ``` . |-- backend/ | |-- server.js | |-- triage_collector.js | |-- opensearch.client.js | |-- mantis.client.js | |-- ai.service.js | |-- pivot_executor.js | |-- .env.example | `-- services/ | |-- caseManagerV1.service.js | |-- caseCandidateSync.service.js | |-- caseFingerprint.service.js | |-- caseStore.service.js | |-- ticketContext.service.js | |-- ticketHistoryStore.service.js | |-- ticketRegistry.service.js | `-- mantis.service.js | |-- frontend/ | |-- src/App.js | |-- src/CaseManagerV1Page.js | |-- src/TicketsPage.js | |-- src/App.css | `-- .env.example | |-- docs/ | |-- PORTFOLIO_NOTES.md | `-- INTERVIEW_PREP.md | `-- README.md ``` ## 安装说明 前置条件： - Node.js 和 npm - 可访问 OpenSearch 或 OpenSearch Dashboards 环境 - 如果使用工单功能，需提供 MantisBT API token - 如果使用 AI 辅助分析，需提供 OpenAI API key 后端： ``` cd backend Copy-Item .env.example .env npm install npm start ``` 前端： ``` cd frontend Copy-Item .env.example .env npm install npm start ``` 默认本地 URL： ``` Backend: http://localhost:5000 Frontend: http://localhost:3000 Health: http://localhost:5000/api/health ``` ## 环境变量 使用包含的示例文件： - `backend/.env.example` - `frontend/.env.example` 重要的后端配置项： - `OPENSEARCH_NODE` - `OPENSEARCH_USERNAME` - `OPENSEARCH_PASSWORD` - `OPENSEARCH_MODE` - `OPENSEARCH_INDEX` - `OPENSEARCH_INDEX_PATTERN_ID` - `MANTIS_URL` - `MANTIS_API_TOKEN` - `MANTIS_USERNAME` - `OPENAI_API_KEY` - `OPENAI_CASE_MANAGER_MODEL` - `CASE_MANAGER_V1_MAX_AI_CASES` - `CASE_MANAGER_V1_MAX_PIVOTS` 运行时数据将写入本地 `backend/data/` 目录下，生成的分诊 JSON 文件可能会写入 `backend/` 目录下。这些文件会被 Git 忽略，如果其中包含真实的遥测数据或客户/学生实验室标识符，则不应公开发布。 ## API 区域 - `GET /api/health` - 后端健康检查。 - `GET /api/triage-summary-v1` - 加载分组的 OpenSearch 汇总数据。 - `GET /api/triage-raw-v1` - 加载收集的原始分诊数据。 - `POST /api/refresh-triage-v1` - 刷新 OpenSearch 遥测收集。 - `POST /api/analyze-case` - 对选定案例运行 AI 分析。 - `POST /api/pivot-query` - 执行 OpenSearch 追踪。 - `POST /api/reassess-case` - 在获取追踪证据后重新评估案例。 - `POST /api/check-duplicates` - 在 MantisBT 中搜索可能的重复工单。 - `POST /api/tickets/create` - 创建 MantisBT 工单。 - `GET /api/tickets/history` - 加载本地工单注册表。 - `POST /api/tickets/sync` - 将 MantisBT 工单同步到本地历史记录。 - `GET /api/cases-v1/status` - 加载案例管理器 v1 状态。 - `POST /api/cases-v1/start` - 启动过去一小时的自动调查运行。 - `POST /api/cases-v1/stop` - 请求安全停止。 ## 安全免责声明 本项目是用于防御性安全工作流自动化的作品集原型。未经适当的审查、身份验证、授权、密钥管理、日志控制和数据保留控制，请勿将其连接到生产系统。 ## 经验教训 - 一个实用的 SOC 工具应从清晰的工作流出发，而不仅仅是提供更多的告警。 - 字段映射至关重要。最终的 OpenSearch 实现必须使用可用字段，例如 `rule.name`, `rule.category`, `dns.host`, `zeek.dns.query`, `http.host`, `http.uri`, `url.full`, `zeek.notice.note`, `zeek.notice.msg` 和 `zeek.ssl.server_name`。 - 当案例分组能够保留证据和可解释性时，其价值才更大。 - 当 AI 辅助受到结构化提示词、追踪限制、JSON 输出和分析师审核的约束时，才最为实用。 - 工单系统集成是检测工程的一部分，因为交接过程必须保留上下文、证据和决策历史。

标签：AI辅助分析, GNU通用公共许可证, Go语言工具, IP 地址批量处理, Metaprompt, MITM代理, Node.js, React, Syscalls, 告警分诊, 安全编排与自动化, 安全运营中心, 插件系统, 数据可视化, 网络映射, 自定义脚本