Lockelamoree/BreachLens-Splunk-MCP-SOC-Copilot

# BreachLens 我为Splunk Agentic Ops Hackathon安全赛道构建了BreachLens。想法很简单：我不想让一个AI聊天机器人猜测其通过事件响应的方式。我想要一个SOC工作流程，其中每个声明都有一个Splunk支持的证据ID作为其后盾。 BreachLens接收一个可疑警报，通过Splunk数据进行转换，构建事件时间线，将活动映射到MITRE ATT&CK，建议响应操作，并导出证据账本和Markdown事件报告。AI部分很有用，但它被故意限制在框内：它可以总结证据，而后端只接受引用真实证据ID和具体字段的笔记。  ## 我构建的内容 - 一个带有`breachlens`索引、JSON源类型、样本违规遥测、保存的搜索、宏和仪表板的Splunk应用程序。 - 一个FastAPI后端，具有三种数据模式： - `rest`：本地Splunk Enterprise实时数据模式。 - `mcp`：Splunk MCP Server模式，用于最终的Hackathon证明。 - `sample`：离线开发模式。 - 一个React/Vite SOC控制台，具有警报队列、证据条、时间线、证据抽屉、SPL转写、MITRE映射、响应计划、导出和检测草稿。 - 一个可以借助Ollama使用NiNa的证据门控分析师笔记。 - 对后端调查流程和前端演示路径的测试。 ## 为什么我认为它很重要 大多数SOC副驾驶演示看起来很棒，直到你问，“那个声明是从哪里来的？”BreachLens就是围绕这个问题构建的。 工作流程故意以证据为起点： 1. Splunk返回警报和相关遥测数据。 2. 代理记录工具调用和SPL转换。 3. 证据项获得稳定的ID，如`EV-001`。 4. 时间线事件、MITRE映射、响应操作、报告和AI笔记引用那些ID。 5. 如果AI响应没有引用真实的证据ID和具体证据字段，则后端将回退而不是信任它。 这就是全部要点：有用的AI，但带有分析师可以审计的护栏。 ## Hackathon Fit - **赛道**：安全 - **奖励目标**：最佳使用Splunk MCP Server - **演示视频**：[BreachLens - Splunk MCP SOC副驾驶与证据门控AI](https://youtu.be/FM6DZyjPXbs) - **我在演示中使用的AI模型**：通过本地Ollama的NiNa，模型链接在UI中显示：[LockeLamora2077/NiNa](https://huggingface.co/LockeLamora2077/NiNa) - **评委应寻找的内容**：第一个视口的证据条、SPL转写、证据抽屉、Splunk源链接、账本/报告导出和生成的检测。 有关我使用的Devpost说明，请参阅[docs/devpost_submission.md](docs/devpost_submission.md）。 有关我的当前实时环境状态，请参阅[docs/live_validation.md](docs/live_validation.md）。 ## 实时证明模式 我保留这些模式是明确的，因为这是一种安全工具，假装样本数据是实时数据是演示变得奇怪的原因。 | 模式 | 客户端标签 | 它意味着什么 | | --- | --- | --- | | `rest` | `splunk_rest` | 使用本地Splunk Enterprise容器和真实的`breachlens`索引数据。这是正常的本地验证路径。 | | `mcp` | `splunk_mcp` | 使用Splunk MCP Server。这是最终的Hackathon/奖金证明模式。 | | `sample` | `sample_data` | 仅使用本地JSONL文件。适用于开发，但不适用于最终的录制。 | 在演示录制中，证据条应显示： ``` Splunk MCP live mcp splunk_mcp NiNa 4/4 observed ``` 应可见的四个MCP调用是： ``` splunk_get_indexes splunk_get_metadata splunk_get_knowledge_objects splunk_run_query ``` 仅工具名称不足以进行MCP证明。SPL转写还记录了`transport`，并且当本地服务器公开新的名称时，UI只计算这四个调用作为MCP证明，例如`get_indexes`和`run_query`。 一个小命名注意事项：BreachLens显示这四个逻辑标签，因为这是我想要在演示中可见的证明点。MCP客户端将它们映射到本地Splunk MCP Server工具名称，当本地服务器公开新的名称时，例如`get_indexes`和`run_query`。 ## 如何将Splunk和AI结合起来 1. `apps/breachlens_splunk/`定义了Splunk应用程序、索引、源类型、输入、保存的搜索、宏和仪表板。 2. Splunk索引来自`sample_data/`的合成身份验证、云、端点、代理和警报事件。 3. 后端根据`BREACHLENS_MODE`通过REST或MCP运行调查。 4. 在MCP模式下，代理使用Splunk MCP Server工具进行索引发现、元数据、知识对象和SPL搜索。 5. NiNa/Ollama可以生成分析师笔记，但后端只接受具有支持状态、有效证据ID和声明级字段引用（如`EV-001.user`）的结构的JSON。 6. UI将结果显示为SOC工作流程，而不是聊天记录。 ``` flowchart LR Analyst["SOC analyst"] --> UI["BreachLens React console"] UI --> API["FastAPI investigation API"] API --> Agent["Evidence-gated SOC agent"] Agent --> Mode{"Runtime mode"} Mode --> MCP["Splunk MCP Server"] Mode --> REST["Splunk REST"] Mode --> Sample["Sample JSONL"] MCP --> Splunk["Local Splunk Enterprise"] REST --> Splunk Sample --> Data["Synthetic breach telemetry"] Splunk --> Data Agent --> NiNa["NiNa via Ollama"] NiNa --> Gate["Evidence ID + field-reference gate"] Agent --> Gate Gate --> Findings["Timeline, MITRE, response, detections"] Findings --> UI UI --> Exports["Evidence ledger + incident report"] ``` ## 仓库布局 ``` apps/breachlens_splunk/ Splunk app with index, sourcetypes, saved searches, dashboard backend/ FastAPI API, Splunk MCP/REST clients, agent, tests frontend/ React/Vite SOC console and Playwright smoke test sample_data/ Synthetic multi-stage breach JSONL logs docs/ Devpost notes, demo script, checklist architecture_diagram.md Root-level architecture diagram for Devpost ``` ## 快速入门 1. 复制环境模板。 Copy-Item .env.example .env 在`.env`中设置本地`SPLUNK_PASSWORD`，在启动Splunk之前。模板默认为`BREACHLENS_MODE=rest`，因此应用程序使用来自本地Splunk容器的实时数据。 2. 启动本地Splunk Enterprise。 docker compose up -d splunk 3. 在`http://127.0.0.1:18000`打开Splunk并以`.env`中的密码登录`admin`。 4. 创建后端环境并安装依赖项。 cd backend python -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -r requirements.txt 5. 验证Splunk已索引演示数据。 @' from app.config import load_settings from app.splunk_client import make_splunk_client client = make_splunk_client(load_settings()) print(client.name) print(client.run_query("search index=breachlens | stats count by sourcetype", earliest="0")) '@ | .\.venv\Scripts\python.exe - 预期的客户端在正常实时数据模式下： splunk_rest 6. 运行后端。 .\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8080 7. 运行前端。 cd ..\frontend npm install --ignore-scripts npm run dev 8. 在`http://localhost:5173`打开。 ## MCP演示设置 本地REST路径证明了应用程序正在使用实时Splunk数据。对于Splunk MCP奖金证明，在本地Splunk实例中安装Splunk MCP Server，为演示角色启用所需的工具执行功能，生成加密的MCP令牌，并设置： ``` BREACHLENS_MODE=mcp SPLUNK_MCP_URL= SPLUNK_MCP_TOKEN= SPLUNK_MCP_VERIFY_TLS=false ``` 然后重新启动后端。 我将在[docs/mcp_live_setup.md](docs/mcp_live_setup.md）中保留详细的实时设置步骤。 ## NiNa / Ollama 对于我的演示，我使用通过Ollama的NiNa： ``` OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL=hf.co/LockeLamora2077/NiNa:latest ``` 如果没有配置模型，BreachLens将使用确定性回退推理，并在UI中明确标记。 ## MCP演示验证 在Splunk、Splunk MCP Server应用程序、后端和前端在MCP模式下运行后： ``` .\backend\.venv\Scripts\python.exe backend\scripts\validate_mcp.py --out docs\mcp_validation.md ``` ``` cd frontend $env:EXPECTED_BREACHLENS_MODE = "mcp" $env:EXPECTED_SPLUNK_CLIENT = "splunk_mcp" $env:EXPECTED_AI_MODEL_LABEL = "NiNa" npm run test:live ``` 这捕获了`docs/breachlens-ui-real-splunk.png`，下载了证据账本和事件报告，并检查证据条和SPL转写是否显示了所需的MCP信号。 ## AI评估 我添加了一个小型评估器，以便AI行为可重复，而不是从一张截图进行判断： ``` cd backend .\.venv\Scripts\python.exe scripts\evaluate_ai.py --alerts 3 ``` 当前的本地运行已保存在[docs/ai_evaluation.md](docs/ai_evaluation.md）。在该次运行中，NiNa为所有三个警报返回了接受的JSON，具有有效的证据ID和基于证据的字段声明，而确定性路径保持明确标记为回退。 ## API - `GET /api/alerts` - `POST /api/investigations` - `GET /api/investigations/{id}` - `POST /api/detections` - `GET /api/investigations/{id}/ledger` - `GET /api/investigations/{id}/report.md` 示例调查请求： ``` { "alert_id": "BLS-2026-001", "objective": "Determine account takeover and blast radius" } ``` ## 演示流程 1. 显示证据条，以便可见运行时模式、Splunk客户端、模型、工具调用和证据计数。 2. 运行关键的不可能旅行警报调查。 3. 沿着事件时间线导航并单击证据ID。 4. 在证据抽屉中显示原始Splunk字段和源事件链接。 5. 显示SPL转写。 6. 导出证据账本和事件报告。 7. 生成检测草稿。 ## 测试 后端： ``` cd backend .\.venv\Scripts\python.exe -m unittest discover tests ``` 前端： ``` cd frontend npm run test:e2e ``` ## 安全注意事项 - 没有秘密被提交。`.env`被忽略。 - MCP令牌必须在Splunk MCP Server应用程序中本地生成。 - AI笔记是证据门控的，并限制为已知证据ID加上具体证据字段引用。 - 后端拒绝明显的提示注入目标，例如请求忽略指令或泄露系统提示。 - 包含的`rest`设置适用于本地演示使用。它可以使用基本身份验证和`SPLUNK_VERIFY_TLS=false`，因为Splunk管理端口绑定到localhost在Docker中。 - 对于生产，我将使用令牌身份验证、TLS验证、最小权限Splunk角色、锁定CORS、网络允许列表和`.env`之外的秘密存储。 - MCP令牌、Splunk令牌和任何模型API密钥永远不应提交或显示在演示录制中。

标签：请求拦截