fa1829/SOCrates

# SOCrates 🦉 — 可解释的自主 SOC 分诊智能体    -orange) SOCrates 会摄取真实的 **Suricata IDS 告警**（`eve.json`），将它们关联为攻击活动，基于本地的 **MITRE ATT&CK 知识库** (RAG) 进行推理，并使用**完全本地化的 LLM (Ollama)** 生成**结构化、可审计的分诊结论**——任何安全遥测数据都不会离开您的设备。遏制操作仅仅是**建议提出**的，未经人工批准绝不会执行。 **起源：** 在一次 CTF 比赛中，一位行业技术主管向我提出挑战：*"你能构建一个自主的 SOC 智能体吗？"* 构建它的过程让我认识到，真正的问题不在于自主性，而在于**信任**。SOCrates 的设计围绕三个约束条件：它必须解释每一个决策；它绝不能脱离人类单独行动；数据必须保持在本地。以下的所有内容，包括测量的失败率和故障排除指南，都来自我自己机器上的真实测试运行。 ## 目录 1. [它的功能](#1-what-it-does) 2. [架构与流水线工作原理](#2-architecture--how-the-pipeline-works) 3. [实战示例：一个完整的告警处理流程](#3-worked-example-one-alert-end-to-end) 4. [分步设置指南 (WSL / Ubuntu / Linux)](#4-step-by-step-setup-guide) 5. [配置参考](#5-configuration-reference) 6. [可解释性契约（真实输出）](#6-the-explainability-contract) 7. [评估：8B vs 3B vs 确定性基线](#7-evaluation-model-comparison-on-real-runs) 8. [观察到的行为 —— 测试实际揭示了什么](#8-observed-behavior) 9. [安全设计决策 (OWASP LLM Top 10 映射)](#9-security-design-decisions) 10. [故障排除与常见问题解答](#10-troubleshooting--faq) 11. [添加 Web UI（使其具备自主感）](#11-adding-a-web-ui) 12. [局限性](#12-limitations) 13. [未来增强功能](#13-future-enhancements) 14. [项目结构、测试与 CI](#14-project-layout-testing--ci) ## 1. 它的功能 | 能力 | 实现方式 | |---|---| | 摄取真实的 IDS 遥测数据 | 解析 Suricata `eve.json`（JSON-lines 格式），容忍损坏或不完整的行 | | 攻击活动上下文 | 根据源 IP 关联告警，以便智能体评估*行为*，而不是孤立的事件 | | 基于事实的推理 (RAG) | 从本地知识库中检索 MITRE ATT&CK 笔记 + 分诊剧本，并引用其使用的内容 | | 本地 LLM 推理 | Ollama（默认为 `llama3.1:8b`）—— SOC 数据绝不会接触第三方 API | | 结构化且经过验证的输出 | LLM 必须以严格的 JSON schema 回答；任何无效的内容都会在代码级的信任边界处被拒绝 | | 优雅降级 | 如果 LLM 宕机、缺失、超时或发出无效的 JSON，一个透明的基于规则的分析师将接管——**并且会明确说明这一点** | | 人机交互 (Human-in-the-loop) | 智能体提出遏制操作建议；由人类批准或拒绝每一项操作 | | 防篡改审计 | 每一个结论和人类决策都被附加到基于 SHA-256 哈希链的日志中；`verify-audit` 会检测任何修改 | | 适合分析师的输出 | Markdown 事件报告 + 机器可读的 `verdicts.json` | ## 2. 架构与流水线工作原理 ``` flowchart LR A[Suricata eve.json] --> B[Ingest & Normalize] B --> C[Correlation
group by source IP] C --> D{Triage Agent} K[(Knowledge Base
MITRE ATT&CK + Playbooks)] -- RAG retrieve --> D L[Ollama
local LLM] -- reason --> D H[Heuristic Analyst
deterministic fallback] -. LLM down / invalid / timeout .-> D D --> V[Validated JSON Verdict
evidence · confidence · MITRE · reasoning] V --> R[Markdown Triage Report] V --> G[Human-in-the-Loop
approve / reject actions] V --> AU[(Hash-chained
Audit Log)] G --> AU ``` 每个告警的处理流水线： 1. **感知** — `ingest.py` 将原始的 `eve.json` 记录标准化为 `Alert`（源/目的地址、签名、类别、Suricata 严重程度）。 2. **关联** — 告警会被置于同一批次中来自相同源 IP 的所有其他告警的上下文中（“4 分钟内来自 203.0.113.45 的 3 个告警”与单个告警的解读截然不同）。 3. **检索 (RAG)** — `rag.py` 通过关键词重叠从 `knowledge/` 中提取最相关的片段（MITRE 技术笔记、严重程度校准规则、误报启发式规则）。检索到的片段名称作为引用随结论一同输出。 4. **推理** — `llm.py` 将告警 + 关联上下文 + 检索到的知识发送给本地的 Ollama 模型，提示词要求其*仅*返回固定 schema 的 JSON 对象，并将 temperature 设为 0 以保持一致性。 5. **验证** — `agent.py` 解析并对响应进行 schema 检查。这是信任边界：未知的结论值、格式错误的置信度或损坏的 JSON 都会被拒绝。任何失败（包括超时）都会打印可见的 `[warn]` 并触发…… 6. **降级/回退** — `heuristic.py`，一个完全确定性的 keyword→MITRE 分析师，会重新生成结论并诚实地将其标记为 `"engine": "heuristic"`。 7. **解释与记录** — 结论（证据、置信度、MITRE 映射、推理轨迹、知识引用）被写入报告、`verdicts.json` 以及基于哈希链的审计日志。 8. **由人类决策** — 在 `--interactive` 模式下，每个建议的操作都需要明确批准；批准和拒绝都会被审计。执行是*模拟的*——接入真实的防火墙 API 是一个刻意为之、标记清晰的集成点。 ## 3. 实战示例：一个完整的告警处理流程 来自 `data/sample_eve.json` 的输入行 —— 一台内部主机正在发起可疑的 DNS 查询： ``` {"timestamp":"2026-07-10T14:31:55...","src_ip":"10.0.0.23","dest_ip":"8.8.4.4","dest_port":53,"proto":"UDP", "alert":{"signature":"ET DNS Tunnel Suspicious Long TXT Query (possible DNS tunneling)","severity":1}} ``` 接下来的过程是：摄取阶段将其标准化 → 关联阶段注意到这是来自 10.0.0.23 的一个孤立事件 → 检索阶段提取了 `T1071.004` 技术笔记（“内部源 IP 发起此行为使其严重程度达到高危至严重：这暗示了现有的入侵”）以及剧本的严重程度校准规则 → LLM 对所有这些进行推理 → 验证通过 → 生成此结论（**来自 llama3.1:8b 的真实输出**，见第 6 节） → 提出的两个操作（对域名进行 Sinkhole 封堵，隔离主机）等待人工批准 → 所有内容最终汇入审计链。 关键时刻：原始 Suricata 严重程度与其他几个告警相同，但智能体将此告警升级为 **CRITICAL**——因为它*推理出*，由于源地址是内部主机，意味着已有的入侵，并引用了它所应用的剧本规则。而只能进行关键词匹配的确定性引擎将其评估为 HIGH。这种差异正是 LLM 分诊的价值主张所在，而引用追踪则是使其值得信赖的关键。 ## 4. 分步设置指南 已在 **WSL2 (Windows 11) 下的 Ubuntu 24.04** 及 Python 3.12 环境中测试。任何具有 Python 3.10+ 的 Linux/macOS 均可运行。 ### 第 1 步 — 克隆并冒烟测试（无需 LLM，约 60 秒） ``` git clone https://github.com/fa1829/socrates && cd socrates PYTHONPATH=src python3 -m socrates triage data/sample_eve.json ``` 核心代码具有**零依赖**——这在裸机 Python 环境中即可运行。如果没有 Ollama，您将看到 `engine: heuristic (Ollama not detected)`，且流水线仍会生成所有三个输出： ``` cat triage_report.md # analyst-readable incident report cat verdicts.json # machine-readable verdicts with full reasoning PYTHONPATH=src python3 -m socrates verify-audit # -> Audit chain VALID ``` 尝试篡改：编辑 `audit_log.jsonl` 中的任何值，重新运行 `verify-audit`，观察哈希链断裂的过程。 ### 第 2 步 — 开发环境与测试 Ubuntu 保护系统自带的 Python (PEP 668)，因此请使用虚拟环境——请**不要**通过 snap 安装： ``` sudo apt update && sudo apt install -y python3-venv python3 -m venv .venv source .venv/bin/activate # prompt now shows (.venv) pip install pytest ruff ruff check src tests && pytest -q # expect: All checks passed! / 5 passed ``` 必须在每个新终端中重新运行 `source .venv/bin/activate`（`python3 -m venv .venv` 创建过程只需进行一次）。 ### 第 3 步 — 安装 Ollama 并拉取模型 ``` curl -fsSL https://ollama.com/install.sh | sh ollama list # what's installed right now ollama pull llama3.1:8b # ~4.9 GB — best quality (needs ~8 GB free RAM) # 或者，对于较慢的机器 / 更快的演示： ollama pull llama3.2:3b # ~2.0 GB ``` **模型名称必须完全匹配。** `llama3:latest` ≠ `llama3.1:8b`。如果未拉取配置的模型，SOCrates 会发出警告并在启发式模式下运行（参见故障排除——在开发过程中确实发生过这种混淆）。 ### 第 4 步 — 使用 LLM 运行 ``` SOCRATES_TIMEOUT=600 PYTHONPATH=src python3 -m socrates triage data/sample_eve.json ``` **预期在 CPU 上运行会很慢** —— 使用 8B 模型大约每条告警需要 100 秒（实测：7 条告警耗时 12分01秒）。结论输出行之间的静默是模型在思考，而非程序卡死。3B 模型速度大约快 2.5 倍（实测：4分51秒），但质量上的权衡在第 7 节中进行了量化： ``` SOCRATES_MODEL=llama3.2:3b PYTHONPATH=src python3 -m socrates triage data/sample_eve.json ``` ### 第 5 步 — 人机交互模式 ``` SOCRATES_TIMEOUT=600 PYTHONPATH=src python3 -m socrates triage data/sample_eve.json --interactive ``` 每个建议的操作都会提示 `APPROVE action ...? [y/N]`。批准后会打印一行**模拟的**执行记录；批准和拒绝均会被写入审计链。系统绝不会自动执行任何强制操作。 ### 第 6 步 — 指向您自己的传感器 ``` PYTHONPATH=src python3 -m socrates triage /var/log/suricata/eve.json --report incident.md ``` 非告警事件（flow、DNS 日志、stats 等）会被自动过滤；损坏的行——这在实时的 eve.json 文件中很常见——会被容忍处理。 ## 5. 配置参考 所有配置均通过环境变量完成——无需管理配置文件： | 变量 | 默认值 | 用途 | |---|---|---| | `SOCRATES_MODEL` | `llama3.1:8b` | 任何已拉取到 Ollama 中的模型 | | `SOCRATES_OLLAMA_URL` | `http://localhost:11434` | Ollama 服务器地址（参见故障排除中的 WSL 说明） | | `SOCRATES_TIMEOUT` | `300` | 每次 LLM 调用允许的秒数——在 CPU 上运行大模型时请增加此值 | CLI 参数：`--knowledge`（知识库目录）、`--report`、`--json`、`--audit-log`、`--interactive`。推理在 temperature 为 0 且使用固定种子的状态下运行，以实现多次运行间的可重复性，并且模型在告警处理期间保持加载状态（`keep_alive`）以避免重载延迟。 ## 6. 可解释性契约 每个结论都是一个经过验证的 JSON 对象。这是来自真实运行（llama3.1:8b）的**实际输出**——即实战示例中提到的 DNS 隧道告警： ``` { "alert_id": "bbe2f0458478", "verdict": "true_positive", "severity": "critical", "confidence": 0.9, "summary": "Potential DNS tunneling detected from internal host, indicating possible compromise.", "evidence": [ "ET DNS Tunnel Suspicious Long TXT Query (possible DNS tunneling) alert triggered", "Internal source IP 10.0.0.23 indicates existing compromise", "Mitre technique T1071.004 - Application Layer Protocol: DNS (C2 / Tunneling) matches" ], "mitre_techniques": ["T1071.004 - Application Layer Protocol: DNS (C2 / Tunneling)"], "recommended_actions": [ "Sinkhole the domain to prevent further communication", "Isolate the internal host for further investigation and forensics" ], "reasoning": "The alert indicates a suspicious long TXT query from an internal host, which is a known indicator of DNS tunneling. The Mitre technique T1071.004 matches this behavior, indicating potential C2 or exfiltration activity. Given the internal source IP, this is considered a critical severity incident.", "engine": "llm:llama3.1:8b", "knowledge_used": [ "mitre_attack.md#T1071.004 - Application Layer Protocol: DNS (C2 / Tunneling)", "triage_playbook.md#Severity calibration" ] } ``` 注意引用链：结论指出了它为达到 CRITICAL 级别所应用的 MITRE 笔记**以及剧本规则**。如果 LLM 返回的任何内容未能通过 schema 验证，结论将由确定性引擎重新生成，并标记为 `"engine": "heuristic"`——系统绝不会默默信任格式错误的模型输出，并且（从 v0.1 版本起）也绝不会*默默地*进行降级回退：每次降级都会打印附带原因的 `[warn]` 信息。 ## 7. 评估：真实运行中的模型比较 相同的 7 告警数据集，同一台机器（纯 CPU，WSL2），使用 `time` 测量： | 引擎 | 总计（7 个告警） | 每个告警 | Schema 有效的结论 | 捕捉到内部主机 → CRITICAL 的升级 | 备注 | |---|---|---|---|---|---| | llama3.1:8b | 12分 01秒 | ~103 秒 | **7/7** | ✅ 每次运行 (置信度 0.90–0.95) | 推理能力最佳；在 CPU 上需要 `SOCRATES_TIMEOUT≥600` | | llama3.2:3b | 4分 51秒 | ~42 秒 | 5/7 | ❌ 评估为 HIGH/0.80 | 快 2.5 倍；JSON 规范性较差且推理深度较浅 | | 启发式基线 | <1 秒 | 瞬间完成 | 7/7 (构造上保证) | ❌ | 确定性；兼作评估基线 | 一张表中体现了两个教训：在 3B 级别下，**格式规范性和多跳推理能力同时下降**——较小的模型既两次破坏了 JSON schema，也未能推断出内部源地址暗示着已有入侵。验证层确保了这些故障能够优雅降级（可见的 `[warn]`，诚实的启发式结论），而不是整个流水线。 ## 8. 观察到的行为 来自真实测试运行的发现保留在此处，因为智能体的*实际测量*行为比其声称的行为更重要： **超越关键词的推理。** 8B 模型将 DNS 隧道告警升级为 CRITICAL，因为源地址是内部主机，并引用了剧本的严重程度规则——这在每次运行中表现一致。而基于关键词的引擎在结构上根本无法做出这种推断。 **测得的降级率。** llama3.2:3b：2/7 次 schema 验证失败。llama3.1:8b 在旧的 120 秒默认超时设置下：在 CPU 上有 2/7 次超时（在 600 秒下为 0/7）。现在这两种失败模式都会通过 `[warn]` 行显现出来，而不是静默降级——这一修复正是直接受到这些观察结果的启发。 **检索 ≠ 服从。** 在一次运行中，检索系统正确提取了针对 TLS 证书策略告警的剧本误报指南——然而模型读取后**却无视了它**，以带有主机隔离建议的 true_positive/HIGH 作为定论（这是一种过度升级）。引用追踪使得这种分歧变得*可见*：您可以确切地看到向智能体展示了哪些指南，以及它选择了违背哪些指南。黑盒系统会完全掩盖这一点。这也是支持人工批准机制的最有力论据。 **非确定性，随后实现确定性。** 在 temperature 为 0.1 时，相同的输入在几分钟内产生了不同的结论（在两次运行之间，一个告警从 needs_review/0.40 变成了 true_positive/0.80）。现在推理在 temperature 为 0 并使用固定种子的状态下运行。 **可重现的故障线索。** 一个特定的告警（SSH 暴力破解）在多次运行和两个模型中都未能通过 schema 验证；它也是唯一一个没有任何知识库引用的告警。工作假设是：糟糕的检索 → 缺乏事实依据的提示词 → 格式错误的输出。调查检索质量与输出有效性之间的这种联系是路线图上的第一项任务。 ## 9. 安全设计决策 | 决策 | 应对的威胁 | |---|---| | 智能体提出建议，人类批准；强制执行是一个标记清晰、尚未实现的集成点 | **OWASP LLM08 — 过度代理 (Excessive Agency)。** 观察到的 TLS 过度升级就是一个鲜活的例子：自主化版本会仅仅因为证书警告而隔离主机 | | 在信任任何结论之前，在代码中验证严格的 JSON schema | **LLM02 — 不安全的输出处理** | | 只有标准化后的告警字段和精心挑选的本地知识进入提示词——绝不包含原始的数据包载荷（这是攻击者可控文本所在之处） | **LLM01 — 提示词注入**（减少攻击面；对抗性测试已列入路线图） | | 通过 Ollama 进行 100% 本地推理 | 数据治理——安全遥测数据不经过任何第三方处理 | | 对每一个结论和人类决策进行基于 SHA-256 哈希链的审计日志记录 (`verify-audit`) | 责任追究、防篡改、事件审查 | | 确定性启发式引擎 | 保证在 LLM 故障下的可用性，**并提供**可测量的评估基线 | ## 10. 故障排除与常见问题解答 以下每一项都是开发过程中实际遇到过的问题。 **横幅显示 `engine: llm:...`，但结论看起来出奇地统一（全是 70%/40%）。** 请求的模型未拉取到 Ollama 中——服务器响应了健康检查，但每次 `generate()` 调用都失败了，智能体降级使用了启发式算法。特征表现：瞬间完成（真正的 8B 模型在 CPU 上每条告警约需 100 秒），置信度统一，以及 `verdicts.json` 中显示为 `"engine": "heuristic"`。请使用 `ollama list` 进行检查，切记名称必须完全一致：`llama3:latest` **不是** `llama3.1:8b`。修复方法：`ollama pull llama3.1:8b` 或者将 `SOCRATES_MODEL` 设置为您已有的模型。（从 v0.1 版本起，启动检查也会验证模型，而不仅仅是服务器，并会给出明确的警告。） **`[warn] LLM call failed ...: timed out`。** 在 CPU 上对 8B 模型进行推理可能会超过单次调用的超时限制，特别是在内存压力较大的情况下（8B 模型需要约 6+ GB 内存；使用交换内存会使其极其缓慢）——通常是批次中*较后*的告警先超时。修复方法：设置 `SOCRATES_TIMEOUT=600`，或使用更小的模型（`SOCRATES_MODEL=llama3.2:3b`）。模型在告警处理期间会保持加载状态，以避免重新加载导致的卡顿。 **`[warn] LLM output failed schema validation`。** 模型做出了回答，但破坏了 JSON 契约（如散文、缺失字段、无效的枚举值）。这在较小的模型中更为常见（实测 3B 为 2/7，而 8B 为 0/7）。结论将由启发式引擎重新生成并如实打上标签。如果某个告警反复失败，请检查它是否检索到了任何知识（`knowledge_used` 是否为空？）——参见“观察到的行为”。 **显示横幅后运行似乎卡住了。** 并没有卡住——结论行只有在每个告警处理完成后才会出现，并且在 CPU 上每个告警可能需要 1-2 分钟。如果您想确认状态，可以在另一个终端中查看 `htop`。 **`-bash: .venv/bin/activate: No such file or directory`。** 虚拟环境从未被*创建*过——激活只有在项目目录中运行过一次 `python3 -m venv .venv` 后才有效。不要通过 snap 安装 ruff/pytest；请将工具保留在虚拟环境中。 **粘贴代码片段时出现 `try:: command not found` 或 `syntax error near unexpected token`。** 该代码片段是用于文件的 Python 代码，而不是 Shell 命令。经验法则：以 `def`、`try:`、`import` 或缩进代码块开头的行 → 通过编辑器写入文件（在 WSL 中使用 `code .` 会打开 VS Code）；诸如 `pytest`、`git`、`ollama` 之类的命令 → 直接输入终端。 **Ollama 在 Windows 上运行，但 SOCrates 在 WSL 中运行且无法连接到它。** WSL2 的 `localhost` 并不总是能路由到 Windows 主机。使用 `ip route show default` 查找主机 IP，然后设置 `SOCRATES_OLLAMA_URL=http://:11434`。在较新的 Windows 11 版本中，在 `.wslconfig` 中启用镜像网络可以使普通的 `localhost` 正常工作。 **`grep '"knowledge_used"' verdicts.json` 只显示空的 `[]` 条目。** 这是 grep 的显示伪影，而不是 bug：grep 是基于行的，而在格式化的 JSON 中，包含内容的数组会跨越多行。请改用 Python 进行检查：`python3 -c "import json; [print(v['alert_id'], v['knowledge_used']) for v in json.load(open('verdicts.json'))]"`。 **为什么相同的输入在两次运行中得出了不同的结论？** LLM 采样的非确定性（在 temperature 为 0.1 时观察到）。现在推理使用的是 temperature 为 0 + 固定种子的设置。但在不同的硬件/Ollama 版本之间，仍然无法保证逐字节的精确可重复性——这也是审计日志每次都要记录决策结果的另一个原因。 **`No alert events found in file`。** 该文件不包含任何 `"event_type": "alert"` 记录——Suricata 的 eve.json 混合了多种事件类型（如 flow、dns、stats），只有告警会被分诊。可以使用 `grep -c '"event_type":"alert"' yourfile.json` 进行检查。 **我的告警数据会被发送到任何地方吗？** 不会。推理是本地的（Ollama），检索的是本地文件，输出的也是本地文件。该项目在运行时不会发起任何外部网络调用。 **旧的结论混入了我的报告/审计日志中。** 审计日志在设计上就是追加写入的（这是哈希链的意义所在）。如果需要进行干净演示运行：请先执行 `rm -f audit_log.jsonl triage_report.md verdicts.json`。 **我可以使用 Hugging Face 模型代替 Ollama 吗？** 可以——Ollama 拉取了大多数开源模型的 GGUF 版本（`ollama pull qwen2.5:7b`、`mistral` 等）。直接基于 `transformers` 的推理可以无缝接入到 `llm.py` 中相同的客户端接口背后。 ## 11. 添加 Web UI CLI 证明了流水线的有效性；而一个小型的 Web 仪表板则能让“自主 SOC 团队成员”的体验变得直观——告警源源不断地涌入，结论随着推理过程的展开而显现，**“批准/拒绝”按钮**取代了 `[y/N]` 提示符。计划设计（路线图）： **最快路径 —— Streamlit（约 1 天）：** 一个单一的 Python 文件，包含用于 `eve.json` 的文件上传器、模型选择器、带有可展开的推理/证据/引用的实时结论文本表格，以及针对每个操作写入同一审计链的批准/拒绝按钮。免费、本地化、零 JavaScript。 **作品集级路径 —— FastAPI + 一个 HTML 页面（约 1 个周末）：** ``` POST /triage upload eve.json -> triage job starts GET /verdicts stream verdicts as they complete (Server-Sent Events) POST /decision {alert_id, action, approved} -> audit chain GET /audit/verify chain integrity check, shown as a green/red badge in the UI ``` 现有的模块已经符合这种结构：每个告警都会调用一次 `TriageAgent.triage()`（天然的流式处理单元），`AuditLog.record()` 处理决策记录，而 `Verdict.to_dict()` 则是 API 载荷。UI 是一个表格，在模型思考时会逐行填充——这种等待本身就表明真正的推理是在本地发生的。 **UI 必须遵守的设计规则：** 批准/拒绝必须保持在单个操作级别（不要设置“全部批准”按钮——那将悄悄把人类从闭环中剔除）；每个结论行都必须显示引擎、置信度和引用；审计链状态必须始终可见。**安全提示：** 务必只绑定到 `127.0.0.1`——这个仪表板是一个本地工具，将未经身份验证的分诊和批准接口暴露给网络，将是一种本项目无法承受的讽刺。 ## 12. 局限性 - **关键词检索较为浅层。** RAG 使用关键词重叠机制；词汇与知识库不匹配的告警将无法检索到任何内容（已观察到，并且与 LLM 输出失败相关联）。密集/嵌入检索是计划中的修复方案。 - **LLM 可能会无视其事实基础。** 检索会将正确的知识放入提示词中；但这并不能强制其服从——这在 TLS 剧本覆盖中已经观察到。目前的缓解措施是可见性（引用）+ 人工批准，而不是彻底预防。 - **CPU 推理速度缓慢。** 8B 模型约为 100 秒/条告警。这对于批量分诊和演示没问题；真实的 SOC 业务量需要 GPU 服务或经过调优的更小模型。 - **仅支持单批次关联。** 告警是在同一个文件内按源 IP 分组的；目前尚无跨运行的内存记忆、时间窗口逻辑或基于目的地址的关联。 - **操作是模拟的。** 强制执行（如防火墙 API、EDR 隔离）被刻意保持未实现状态；该集成点已在 `hitl.py` 中标记。 - **合成的评估集。** 7 个手工制作的告警证明了流水线的有效性；但关于现实世界中精确度/召回率的主张则需要路线图中的带标签数据集测试工具来支持。 - **提示词注入面仅被减少，未被测试。** 标准化字段将原始载荷排除在提示词之外，但签名本身属于半攻击者可控的文本；目前尚未进行对抗性测试。 ## 13. 未来增强功能 1. **检索 → 有效性研究 + 嵌入式 RAG** — 利用工具检测观察到的“空检索”与“schema 验证失败”之间的联系，然后在现有的 `KnowledgeBase` 接口之后，将关键词重叠替换为 sentence-transformers + ChromaDB。 2. **评估工具** — 带标签的告警集；测量 LLM 对比启发式算法相对于真实标签的精确度/召回率/F1 分数；将每个结论的延迟记录在结论本身中。 3. **Web 仪表板**（第 11 节）。 4. **实时 SIEM 摄取** — 从 Elastic/OpenSearch 中提取告警，而不是从文件中读取。 5. **多智能体拆分 (LangGraph)** — 分诊智能体 + 威胁情报富化智能体 + 报告智能体，并由一个 Supervisor 统一管理。 6. **对抗性测试** — 制作包含注入尝试的告警签名；测试 schema 边界是否能有效防御。 7. **CP 服务器** — 将 SOCrates 作为工具暴露出来，供其他 AI 助手调用。 8. **真实的强制执行集成** — 仅限选择性开启、在白名单内且可逆的操作（例如，通过防火墙 API 阻断单个 IP），且依然必须在人工批准之后执行。 ## 14. 项目结构、测试与 CI ``` src/socrates/ ingest.py # eve.json parsing + source-IP correlation rag.py # local knowledge retrieval (embedding-ready interface) llm.py # Ollama client, timeout/keep-alive/seed handling, robust JSON extraction agent.py # triage loop: retrieve -> reason -> validate -> explain (with visible fallback warnings) heuristic.py # transparent deterministic fallback / evaluation baseline hitl.py # human approval gate for proposed actions audit.py # SHA-256 hash-chained tamper-evident log report.py # Markdown incident report models.py # Alert & Verdict dataclasses — the explainability contract knowledge/ # MITRE ATT&CK notes + triage playbook (the RAG corpus) data/ # synthetic sample eve.json (safe to publish) tests/ # pytest suite: ingestion, verdict schema, campaign escalation, audit tamper-detection ``` ``` source .venv/bin/activate ruff check src tests && pytest -q # 5 tests, including one that tampers with the audit log and verifies detection ``` GitHub Actions 会在每次推送时运行 lint 和测试。 ## 许可证 MIT — 可免费使用、学习和在此基础上进行构建。

标签：AI风险缓解, C2, RAG, SOC分诊, 安全运营, 审计日志, 扫描框架, 逆向工具