evangeline905/Splunk-SOAR-Playbook-Lab

# Splunk MCP Playbook 验证实验室 **将真实的 BOTS v3 证据转化为经过验证、受批准门控的 SOAR 工作流。** Splunk MCP Playbook 验证实验室是一个为 Splunk Agentic Ops Hackathon 打造的安全工程工作台。它通过 Splunk MCP 查询历史攻击证据，生成人类可读的 SOAR playbook，将其编译为 机器可读的工作流，验证这两种表示形式，使用 VirusTotal 丰富公共 IOC，并在人工批准门控之后对响应进行模拟运行。 ## 问题所在 生成一个看似合理的 playbook 很容易。但证明其部署是安全的则更加困难。 AI 生成或分析师编写的工作流仍然可能： - 需要 Splunk 告警中缺失的字段； - 让可选的丰富化步骤阻碍主要调查； - 编译成与经过审查的 YAML 不同的机器逻辑； - 引用损坏的依赖项或未映射的输入； - 在没有人工批准的情况下自动化执行破坏性操作。 该实验室在 **playbook 生成** 和 **SOAR 部署** 之间增加了一个工程验证层。它会在工作流被提升到生产使用之前，验证 playbook 的结构、依赖项、编译逻辑和批准要求。 ## 演示所证明的内容 竞赛 UI 展示了一个专注的端到端工作流： 1. **调查** - 描述调查目标并通过 Splunk MCP 查询 BOTS v3。 2. **生成 Playbook** - 创建可审查的 YAML SOAR 定义。 3. **验证工作流** - 将 YAML 编译为 JSON 并验证结构、语义、一致性和安全性。 4. **模拟响应** - 丰富公共 IOC，计算风险，并在人工批准门控处停止遏制操作。 5. **导出证据** - 将搜索、schema、playbook、编译的工作流、验证报告和执行结果打包。 输出不仅仅是一个生成的 playbook。它是一个可追溯的证据包， 展示了工作流为何通过、警告、失败、跳过或被阻止的原因。 ## 独特之处 | 能力 | 生成的证据 | | --- | --- | | Splunk MCP 调查 | 真实的 BOTS v3 搜索结果和提取的字段 schema | | 确定性 playbook 生成 | 人类可读的 `validated_playbook.yaml` | | 工作流编译 | 机器可读的 `compiled_playbook.json` | | 就绪性验证 | 每项检查的通过、警告或失败结果以及就绪度评分 | | 安全丰富化 | 针对符合条件的公共 IOC 的实时 VirusTotal 查询证据 | | 批准门控模拟 | 包含被阻止的高风险操作的 `execution_result.json` | | 可移植审查 | 包含完整工程证据的 ZIP 导出 | ### 实时模拟运行证据 下面的截图展示了在批准门控模拟运行中，一个真实的仅查询 VirusTotal 的结果。内部和私有指标已在本地过滤。 ## 竞赛场景 默认 UI 包含基于官方 Splunk Boss of the SOC v3 数据集的四个调查。 | BOTS v3 调查 | 训练假设 | 批准门控操作 | | --- | --- | --- | | 可疑身份验证 | 账户被盗 / 可疑身份验证 | `revoke_sessions` | | Web / 钓鱼调查 | 可疑的 Web、DNS、URL 或域名活动 | `block_domain` | | 端点恶意软件调查 | 恶意软件 / 端点被盗 | `isolate_endpoint` | | 网络可疑通信 / 疑似 C2 | 重复或大容量出站通信 | `block_ip` | MITRE ATT&CK 映射作为训练假设展示，而非自动 事件确认。分类器置信度代表字段证据的匹配度。 ## 架构 [完整架构图](architecture_diagram.md) ``` BOTS v3 -> Splunk Enterprise -> Splunk MCP Server -> FastAPI | +-> field schema + incident context +-> SOAR YAML generation +-> YAML validation +-> compiled workflow JSON +-> compiled JSON validation +-> VirusTotal lookup-only enrichment +-> approval-gated dry run +-> evidence export ``` MCP 模式是主要架构。REST 模式是实用的后备方案。Demo 模式用于保证 Hackathon 的可靠性并进行本地开发。 ## 验证流水线 ``` YAML Playbook -> YAML Validation -> Compiled Playbook JSON -> Compiled JSON Validation -> Visual SOAR Flow -> Dry-run Execution Result ``` 验证器检查： - 有效的 YAML 结构和必填的顶级字段； - 根据 Splunk 返回的 schema 检查必填字段； - 工作流依赖项和引用的步骤 ID； - 可能阻碍必需工作流步骤的可选丰富化分支； - YAML 步骤与编译后的 JSON 节点之间的一对一一致性； - 保留的条件、输入映射、依赖项和批准标志； - 需要高 dictated `approval_required: true` 的高风险操作； - 模拟运行完成情况和部署就绪性。 就绪度初始值为 100，并根据确定性发现进行扣减。UI 独立 显示每项检查，因此高得分无法掩盖安全故障。 ## 安全模型 - 未实现真实的遏制 connector。 - 中等和高风险操作在人工批准之前将保持阻止状态。 - VirusTotal 集成仅使用 API v3 的 `GET` 查询。 - 该实验室从不上传文件、提交 URL 进行扫描或请求重新扫描。 - 私有/保留 IP 和内部域名在访问提供者之前会被过滤。 - URL 查询字符串、片段和嵌入的凭据将被移除或拒绝。 - API 密钥和 Splunk 凭据仅保留在本地 `.env` 的后端中。 - 提供者错误是明确的警告，绝不会伪装成模拟成功。 - 威胁情报证据不会自动触发遏制。 ## 技术栈 - **安全平台:** Splunk Enterprise, Splunk MCP Server, SPL, BOTS v3 - **后端:** Python, FastAPI, Pydantic, PyYAML, HTTPX - **前端:** React, TypeScript, Vite, Lucide - **威胁上下文:** 本地 MITRE ATT&CK 注册表, VirusTotal API v3 - **测试:** pytest, FastAPI TestClient, Vitest ## 快速开始 ### 前置条件 - Python 3.11+ - Node.js 20+ - Windows 上的 PowerShell 7（用于 Splunk 辅助脚本） - 可选：带有 Splunk MCP Server 和 BOTS v3 的本地 Splunk Enterprise ### 1. 配置环境 ``` Copy-Item .env.example .env ``` Demo 模式无需 Splunk 凭据即可运行。切勿提交真实的 `.env` 文件。 ### 2. 启动后端 ``` cd backend python -m pip install -r requirements.txt python -m uvicorn main:app --host 127.0.0.1 --port 8012 ``` ### 3. 启动前端 ``` cd frontend npm install $env:VITE_API_BASE_URL="http://127.0.0.1:8012" npm run dev -- --port 5173 ``` 打开 [http://127.0.0.1:5173](http://127.0.0.1:5173)。 ### Docker 替代方案 ``` Copy-Item .env.example .env docker compose up --build ``` ## Splunk MCP 和 BOTS v3 设置 使用由 Splunk MCP Server 应用生成的 endpoint 和加密 token，在 `.env` 中设置这些值： ``` SPLUNK_MODE=mcp SPLUNK_MCP_URL=https://localhost:8089/ SPLUNK_MCP_TOKEN= SPLUNK_MCP_VERIFY_SSL=false SPLUNK_MCP_TIMEOUT_SECONDS=30 SPLUNK_MCP_PROTOCOL_VERSION=2025-03-26 ``` connector 调用 Splunk MCP 工具 `splunk_run_query`。如果 MCP 不可用， 后端可以回退到 REST，然后再回退到 Demo 模式，这样无需更改主要架构即可保持演示的可恢复性。 ### 安装 BOTS v3 数据集 官方的预索引数据集可从 [splunk/botsv3](https://github.com/splunk/botsv3) 获取。使用以下命令将其安装到本地 Splunk 实验室中： ``` pwsh -ExecutionPolicy Bypass -File .\scripts\install-botsv3-dataset.ps1 -SplunkHome "D:\Splunk" ``` 使用以下命令验证历史事件： ``` index=botsv3 earliest=0 | head 20 | table _time sourcetype host source user src_ip dest_ip url file_hash ``` 必须使用 `earliest=0`，因为 BOTS v3 包含历史事件。 ### 可选的 REST 后备方案 创建一个短期的本地 Splunk REST token 并更新 `.env`，且不要打印 该 token： ``` pwsh -ExecutionPolicy Bypass -File .\scripts\configure_splunk_rest.ps1 ` -SplunkHost "https://127.0.0.1:8089" ` -UserName admin ` -BackendPort 8012 ``` ## 实时 VirusTotal 丰富化 对于个人的非商业培训，将 VirusTotal Community API key 添加到 本地 `.env`： ``` ENRICHMENT_MODE=live VIRUSTOTAL_API_KEY= VIRUSTOTAL_CACHE_TTL_SECONDS=21600 VIRUSTOTAL_MAX_REQUESTS_PER_MINUTE=4 VIRUSTOTAL_DAILY_SOFT_LIMIT=450 ``` 重启后端，然后使用 **Advanced / Fallback Settings -> Test VirusTotal**。连接测试会对 `example.com` 执行一次查询。 在模拟运行期间，引擎会扫描返回的 Splunk 行以查找第一个符合条件的 公共 IOC，而不是盲目地发送第一行。如果不存在符合条件的 IOC， 该步骤将报告警告或跳过，并且必需的工作流将继续执行。 VirusTotal 报告描述了当前的信誉。它们无法证明在历史 BOTS v3 事件发生时的情况是否属实。 ## 生成的产物 导出包包含： - `validated_playbook.yaml` - 分析师可读的 SOAR 定义 - `compiled_playbook.json` - 机器可读的工作流图 - `validation_report.md` - 发现结果和就绪性证据 - `readiness_summary.md` - 简明的部署建议 - `field_schema.json` - 提取的 Splunk 字段覆盖范围 - `spl_query.spl` - 调查查询 - `execution_result.json` - 一次模拟运行执行的结果 - `dry_run_report.json` - 完整的模拟时间线 ## API 概览 | Endpoint | 用途 | | --- | --- | | `GET /health` | 后端健康状态 | | `GET /api/use-cases` | 可用的调查场景 | | `GET /api/training-context` | MITRE 和威胁情报状态 | | `POST /api/search` | 通过 MCP、REST 或 Demo connector 执行 SPL | | `POST /api/generate-playbook` | 生成 YAML 和编译的工作流数据 | | `POST /api/validate-playbook` | 验证 YAML 和编译后的一致性 | | `POST /api/apply-fixes` | 应用确定性的安全修复 | | `POST /api/dry-run` | 模拟批准门控的响应 | | `POST /api/export` | 下载证据包 | ## 测试 后端： ``` cd backend $env:ENRICHMENT_MODE="mock" python -m pytest tests -q ``` 前端： ``` cd frontend npm test -- --run npm run build ``` 当前提交验证：**63 个后端测试和 11 个前端测试通过**。 ## 项目结构 ``` backend/ connectors/ Splunk MCP, REST, and Demo adapters services/ SPL, schema, classification, generation, enrichment validators/ YAML, workflow, safety, and compiled JSON checks simulator/ Approval-gated dry-run engine tests/ Backend regression and integration tests frontend/ React competition workflow scripts/ Splunk REST, demo data, and BOTS v3 helpers docs/ Design records and screenshots architecture_diagram.md ``` ## 范围和后续步骤 当前项目刻意在生产遏制操作前停止。合乎逻辑的 后续步骤是：原生 Splunk SOAR 导出、经过身份验证的分析师批准历史记录、 额外的情报提供者、实时 MITRE 知识同步，以及 受确定性验证器约束的 LLM 起草层。 ## 许可证 [MIT](LICENSE)

标签：Cloudflare, MITRE ATT&CK, SOAR, 安全编排与自动化, 安全规则引擎, 安全运营, 工作流验证, 恶意代码分类, 扫描框架, 请求拦截, 逆向工具