tejcodes-rex/veritrace

# Veritrace **一款为 Splunk 打造的自主 Tier-1 SOC 分析师，能够证明其每一步操作。** Veritrace 像优秀的分析师一样调查 Splunk 告警。它通过 MCP Server 从 Splunk 提取证据，使用 Foundation-Sec 网络安全模型进行推理，将其完整的证据链、推理过程、置信度和操作以可验证、可重放的账本形式写回 Splunk，并发布经过调优的检测即代码（detection-as-code）规则以填补其发现的漏洞。它提出供人工审批的遏制措施，绝不擅自执行破坏性操作。它不知疲倦，展示其工作过程，并使 SOC 变得比之前更强大。 赛道：**安全**。基于 Splunk MCP Server、Splunk 托管的 Foundation-Sec 模型以及 Splunk 开发者工具（Python SDK、`splunklib.ai` 模式和 App Inspect）构建。  ## 问题所在 安全团队希望将 AI 代理引入 SOC，因为 Tier-1 分诊工作重复性高，海量的告警让人喘不过气，分析师极易产生职业倦怠。然而，阻碍这一切的是信任。在安全领域，一个采取无法审计操作的代理是绝对行不通的。如果一个代理说“这是一次数据泄露，我已禁用了该账户”，分析师必须能够确切地看到原因，检查证据，并为该决策提供支持。 Veritrace 正是围绕这一信任问题而构建的。它做出的每一个声明都带有指向支持该声明的 Splunk 事件的指针。它执行的每一步都会以结构化数据的形式写回 Splunk，供您搜索、审计和重放。该代理是一个白盒，而不是黑盒。 ## 它的功能 1. **分诊。** Splunk 中触发告警（或者您从控制台手动触发一个）。Veritrace 会读取该告警并提出假设。 2. **通过 MCP 进行调查，从数据中发现攻击。** 它通过 Veritrace MCP Server 运行一系列只读检测，根据行为和关联性而非主观假定来发现恶意实体：通过失败与成功的比率锁定暴力破解源，通过该账户执行的可疑命令识别被入侵的主机，通过仅保留同样向攻击者进行数据外泄的 SMB 对等端的子搜索确定横向移动目标，以及通过解析到攻击者的 DNS 应答找到 C2 域名。它发现的每一个实体都会为下一次检测提供输入，因此它调查的是数据实际反映的事件，而不是预先硬编码的事件。 3. **使用 Foundation-Sec 进行推理。** 模型会解释每一个真实结果，对其自身的置信度进行评分，端到端地重构杀伤链，然后给出判定。每次检测的 ATT&CK 技术都是确定性的，因此映射始终是正确的。 4. **写入防篡改账本。** 它执行的每一步、所运行的 SPL、证据数量、推理过程、置信度以及 token 消耗，都会在发生时实时写回 `index=veritrace_ledger`。每一步都通过哈希链与前一步相连，使得该账本成为一条可验证的保管链：控制台可以直接从 Splunk 重新读取这些步骤，证明链条完好无损；而对任何单个条目的篡改、丢弃或重新排序都会在该步骤导致链条断裂。控制台实时渲染调查过程；内置仪表盘可在之后重放该过程。 5. **交付检测即代码。** 它会编写一个更高保真度的关联检测规则（原本能作为单一信号捕获此事件），针对历史数据进行回测，并交付一段随时可部署的 `savedsearches.conf` 配置节。模型以通俗语言设计检测规则；平台则根据调查实际证明的各个阶段编译生成 SPL，因此查询始终有效且立足于证据，而非模型随意输出的结果。 6. **提出遏制措施。** 它会推荐可逆的遏制措施供人工审批。绝不会自动执行任何破坏性操作。  该判定附带一条您可以验证的**保管链**。“验证账本完整性”会重新从 Splunk 读取已封存的步骤并重新计算哈希链，因此审计追踪是可被证明的，而不仅仅是摆设：  ## AI 的使用方式 - 推理引擎是 **Foundation-Sec-1.1-8B-Instruct**，即由 Splunk 托管的 Cisco Foundation AI 网络安全模型。在 Splunk Cloud 上，可通过 AI Toolkit 的 `ai` 命令在 SPL 中访问。在 Splunk Enterprise 上，Veritrace 通过 Ollama 或 vLLM 在本地提供相同的开放权重服务。模型提供程序是可插拔的，因此您可以将其指向您所拥有的任何访问路径。 - 代理**仅通过 MCP 工具**访问 Splunk，且每个工具都会经过 SPL 安全防护检查。代理无法对该平台执行写入、执行或导出命令。 - 对于 8B 模型，我们严格限制了其工作契约。每个决策点都要求输出单一的 JSON 对象，并使用 **JSON 约束解码**（在 Ollama 中为 `format=json`，在 vLLM 中为 `response_format`），从而确保推理结果能被可靠地解析。任何不应交由模型生成的内容（尤其是检测 SPL），都**由代码根据已证实的攻击链组装而成**，因此输出始终是有效的。 - 该模型仅用于小型安全模型所擅长的领域：**解释每个真实结果、评估置信度并对最终判定进行权衡**。编写正确的多阶段关联 SPL 并不属于这些擅长领域，因此在使用 `VERITRACE_GUIDED_PIVOTS=true`（对于本地模型推荐开启）时，代理会运行一条**从数据中发现每个恶意实体的检测链**（`veritrace/soc.py`），然后由模型解释每次检测返回的实时证据。由于判别条件是基于行为的，因此同一个引擎可以调查具有不同地址、主机和域名的另一种账户接管事件；它不会被绑定在单一场景上。整个过程中的搜索和结果都是真实的 Splunk 操作。 - 确定性的**重放**提供程序可以在无需 GPU 和网络的情况下重现完整的调查过程，这正是测试套件和离线演示所使用的方案，因此录制的运行过程每次都完全一致，且不依赖于实际的模型路径。 ## 快速开始 如果您想使用一键命令路径，则需要 [Docker](https://www.docker.com/)。默认情况下，所有操作都使用确定性的推理提供程序运行，因此不需要 GPU。 ``` git clone https://github.com/tejcodes-rex/veritrace.git cd veritrace cp .env.example .env docker compose up --build ``` 这将启动 Splunk Enterprise，配置索引和 HEC，将真实的数据泄露事件加载到 `index=security` 中，启动 Veritrace MCP Server 和代理后端，并提供控制台服务。 - 控制台：http://localhost:8400 - Splunk Web：http://localhost:8000（用户名为 `admin`，密码为 `Veritrace!2026`） 打开控制台并点击 **Run investigation**。观察代理如何在 Splunk 中进行追溯，构建 MITRE 杀伤链，得出判定，并提出新的检测建议。 ### 使用真实的 Foundation-Sec 模型 如果您希望使用实际的 Foundation-Sec 模型而非重放提供程序来运行调查，请安装 [Ollama](https://ollama.com/)，拉取模型，并设置提供程序： ``` # Q4_K_M (~5 GB) fits an 8 GB GPU. The official fdtn-ai Q8_0 build is higher # fidelity if you have more memory. ollama pull hf.co/mradermacher/Foundation-Sec-8B-Instruct-GGUF:Q4_K_M # in .env: # VERITRACE_MODEL_PROVIDER=ollama # OLLAMA_MODEL=hf.co/mradermacher/Foundation-Sec-8B-Instruct-GGUF:Q4_K_M # VERITRACE_GUIDED_PIVOTS=true docker compose up --build ``` 使用本地 8B 模型时，请保持 `VERITRACE_GUIDED_PIVOTS=true`：随后，代理将通过真实的 Splunk 运行经过验证的调查追踪，并由模型来解释每个实时结果——这是小型模型能够可靠完成的任务；而不是让它自行编写多阶段的 SPL——这超出了它的能力范围。 Foundation-Sec-8B-Instruct 是 Splunk 所托管的同一 Cisco Foundation AI 模型家族的开源权重版本（Splunk Cloud 托管的是 1.1 版本）。在 Splunk Cloud 上，您也可以设置 `VERITRACE_MODEL_PROVIDER=splunk_hosted`，这将通过 AI Toolkit 的 `ai` SPL 命令路由推理过程，并使用云端托管的副本，从而无需本地 GPU。 ### 在不使用 Docker 的情况下运行（原生） 如果您已经在本地运行 Splunk Enterprise（例如 60 天试用版），您可以在其上原生运行 Veritrace： ``` python -m venv .venv .venv\Scripts\pip install -e . # or .venv/bin/pip on macOS / Linux copy .env.example .env # set SPLUNK_HOST / SPLUNK_PASSWORD .venv\Scripts\veritrace init # create indexes + HEC, load sample data .venv\Scripts\veritrace mcp-server # in one terminal .venv\Scripts\veritrace serve # in another terminal ``` 打开 http://localhost:8400。如果您希望由后端提供控制台服务，请使用 `cd console && npm install && npm run build` 单独构建控制台；或者运行 `npm run dev` 以使用开发服务器。 ### 离线，无需 Splunk 且无需 GPU ``` .venv\Scripts\veritrace investigate --provider replay --backend direct ``` 这将在终端打印出完整的调查过程。测试套件运行的也是同一路径： ``` .venv\Scripts\pytest -q ``` ## 演示场景 内置的数据包含两周的正常基线，以及隐藏在其中的一次入侵。外部攻击者 `45.137.21.53` 对账户 `j.tanaka` 进行暴力破解，从新位置登录，在 `fin-app-07` 上执行发现操作，通过 SMB 横向移动到 `db-prod-02`，与 `cdn-telemetry-sync.net` 进行信标通信，并向攻击者外泄了约 4.8 GB 的数据。Veritrace 剥丝抽茧地揭开了全部六个阶段，并将它们映射到 MITRE ATT&CK（T1110.001、T1078、T1059.001、T1021.002、T1071.004、T1041）。 ## 证明具备泛化能力，而非硬编码 Veritrace 并非仅针对单一的脚本化事件。内置数据包含两起完全不同实体参与的截然不同的入侵事件，而同一个检测引擎能够通过从数据中发现攻击行为来解决每一起事件： | | 事件 1 | 事件 2 | |---|---|---| | 攻击者 IP | `45.137.21.53` | `203.0.113.66` | | 账户 | `j.tanaka` | `r.dasilva` | | 入口主机 | `fin-app-07` | `fin-app-05` | | 横向移动目标 | `db-prod-02` | `db-prod-01` | | C2 域名 | `cdn-telemetry-sync.net` | `edge-metrics-sync.net` | 代理仅接收告警（账户和来源）。它每次都能从数据中发现被入侵的主机、横向移动目标和 C2 域名。运行其中任何一个并观察： ``` .venv\Scripts\veritrace investigate --incident 1 .venv\Scripts\veritrace investigate --incident 2 ``` ## Splunk 应用 `splunk_app/veritrace_app` 是一个正规的 Splunk 应用，能够通过 App Inspect 检查且零失败。它提供了触发告警、将触发告警转交给 Veritrace 的自定义告警操作、提议的关联检测以及推理账本仪表盘。您可以自行验证： ``` .venv\Scripts\pip install splunk-appinspect .venv\Scripts\splunk-appinspect inspect splunk_app/veritrace_app ``` ## 项目布局 ``` veritrace/ the agent, MCP server, model providers, ledger, API, CLI agent.py the investigation loop mcp_server.py the Veritrace MCP server (FastMCP) mcp_client.py the MCP client the agent uses evidence.py evidence sources (MCP, direct SDK, fixture) models/ pluggable providers (ollama, vllm, splunk_hosted, replay) ledger.py writes the reasoning ledger into Splunk detection.py detection-as-code generation and backtest scenarios.py the reference incident, shared by data, replay and agent data/generator.py CIM-aligned sample telemetry with the embedded breach server.py FastAPI backend and live SSE stream console/ the React console (the glass-box UI) splunk_app/ the Splunk app (passes App Inspect) tests/ offline end-to-end investigation test ``` ## 配置 对于内置的技术栈，所有设置都具有可用的默认值。有关完整列表（包括 Splunk 连接、MCP URL 和模型提供程序），请参见 [.env.example](.env.example)。 ## 安全说明 - 代理仅通过 MCP 工具访问 Splunk，且每次搜索都会经过拦截写入、执行和导出命令的 SPL 防护检查。 - 遏制操作需要人工审批方可执行。默认情况下已关闭自动执行。 - 推理账本属于数据，因此由常规的 Splunk 基于角色的访问控制来管理谁有权限读取调查记录。 ## 许可证 Apache-2.0。详见 [LICENSE](LICENSE)。

标签：AI代理, AI风险缓解, SOC分析, 告警分诊, 安全运营, 扫描框架, 请求拦截, 逆向工具