first commit
This commit is contained in:
336
README.md
Normal file
336
README.md
Normal file
@ -0,0 +1,336 @@
|
||||
# SOC Memory POC
|
||||
|
||||
面向 SOC case 研判辅助场景的记忆系统 POC。这个项目不是泛化记忆平台，而是验证 AI agent 在处理钓鱼邮件、O365 异常登录等告警时，能否稳定获得更好的历史 case、KB / Playbook、Obsidian 研判笔记和可沉淀结论。
|
||||
|
||||
当前项目阶段：**最小可运行 POC / Hermes 集成验证阶段**。
|
||||
|
||||
## 当前已经完成什么
|
||||
|
||||
### 1. 总体设计与文档
|
||||
|
||||
已完成 SOC 记忆系统的核心设计文档：
|
||||
|
||||
- [docs/architecture.md](/home/tom/soc_memory_poc/docs/architecture.md)：整体架构、模块边界、数据流
|
||||
- [docs/poc-scope.md](/home/tom/soc_memory_poc/docs/poc-scope.md)：第一阶段 POC 范围
|
||||
- [docs/data-model.md](/home/tom/soc_memory_poc/docs/data-model.md)：SOC memory 数据模型
|
||||
- [docs/namespaces.md](/home/tom/soc_memory_poc/docs/namespaces.md)：OpenViking namespace / URI 设计
|
||||
- [docs/sample-data-spec.md](/home/tom/soc_memory_poc/docs/sample-data-spec.md)：mock case / KB 样本规范
|
||||
- [docs/hermes-demo-prompts.md](/home/tom/soc_memory_poc/docs/hermes-demo-prompts.md)：Hermes demo 输入样例
|
||||
|
||||
### 2. Mock 数据集
|
||||
|
||||
当前没有真实 SOC 数据，所以项目先构造了两类典型场景的数据：
|
||||
|
||||
- 钓鱼邮件：4 个历史 case
|
||||
- O365 异常登录：5 个历史 case
|
||||
- KB / Playbook：7 个条目
|
||||
- normalized case：9 个
|
||||
- normalized KB / Playbook：7 个
|
||||
|
||||
数据目录：
|
||||
|
||||
```text
|
||||
evaluation/datasets/
|
||||
├── mock_cases/
|
||||
├── mock_kb/
|
||||
├── normalized_cases/
|
||||
└── normalized_kb/
|
||||
```
|
||||
|
||||
这些数据用于验证检索、研判、Obsidian note 生成和 Hermes skill 的完整链路。
|
||||
|
||||
### 3. Normalize Pipeline
|
||||
|
||||
已完成基础数据标准化脚本：
|
||||
|
||||
- [pipeline/transforms/normalize_case.py](/home/tom/soc_memory_poc/pipeline/transforms/normalize_case.py)：把 mock / 原始 case 转成统一 case memory 格式
|
||||
- [pipeline/transforms/normalize_kb.py](/home/tom/soc_memory_poc/pipeline/transforms/normalize_kb.py)：把 KB / Playbook 转成统一 knowledge memory 格式
|
||||
- [pipeline/jobs/ingest_case.py](/home/tom/soc_memory_poc/pipeline/jobs/ingest_case.py)：批量生成 normalized case
|
||||
- [pipeline/jobs/ingest_kb.py](/home/tom/soc_memory_poc/pipeline/jobs/ingest_kb.py)：批量生成 normalized KB / Playbook
|
||||
|
||||
### 4. Memory Gateway + OpenViking 接入
|
||||
|
||||
[Memory Gateway](/home/tom/soc_memory_poc/memory_gateway/server.py) 已经可以作为统一入口访问 OpenViking：
|
||||
|
||||
- REST `/health`
|
||||
- REST `/api/search`
|
||||
- REST `/api/memories`
|
||||
- REST `/api/resources`
|
||||
- MCP `tools/list`
|
||||
- MCP `search`
|
||||
- MCP `add_memory`
|
||||
- MCP `add_resource`
|
||||
- API Key 校验已生效
|
||||
- FastAPI lifespan 已挂载，启动时会检查 OpenViking 健康状态
|
||||
|
||||
OpenViking resource URI 当前采用：
|
||||
|
||||
```text
|
||||
viking://resources/soc-memory-poc/case/<scenario>/<case_id>.json
|
||||
viking://resources/soc-memory-poc/knowledge/<doc_type>/<doc_id>.json
|
||||
```
|
||||
|
||||
### 5. Skills
|
||||
|
||||
当前已实现 3 个项目内 skill：
|
||||
|
||||
- [retrieve_context_skill](/home/tom/soc_memory_poc/skills/retrieve_context_skill/retrieve_context.py)：支持本地 normalized 数据检索和 OpenViking 检索
|
||||
- [commit_memory_skill](/home/tom/soc_memory_poc/skills/commit_memory_skill/commit_to_openviking.py)：把 normalized case / KB 写入 OpenViking resource
|
||||
- [summarize_case_skill](/home/tom/soc_memory_poc/skills/summarize_case_skill/generate_case_note.py)：从 normalized case 生成 Obsidian case note，并可用 OpenViking 检索结果增强关联内容
|
||||
|
||||
### 6. Obsidian Vault
|
||||
|
||||
已创建 Obsidian vault 骨架和模板：
|
||||
|
||||
```text
|
||||
obsidian-vault/
|
||||
├── 02_Cases/
|
||||
│ ├── phishing/
|
||||
│ └── o365_suspicious_login/
|
||||
└── 05_Templates/
|
||||
```
|
||||
|
||||
当前已生成 9 篇 case note，覆盖钓鱼邮件和 O365 异常登录两类场景。
|
||||
|
||||
模板包括：
|
||||
|
||||
- [case-note-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/case-note-template.md)
|
||||
- [playbook-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/playbook-template.md)
|
||||
- [report-summary-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/report-summary-template.md)
|
||||
|
||||
### 7. Hermes Agent 集成
|
||||
|
||||
已在本机 Hermes skill 目录创建 `soc-memory-poc` skill：
|
||||
|
||||
```text
|
||||
/home/tom/.hermes/skills/soc-memory-poc/
|
||||
├── SKILL.md
|
||||
└── scripts/
|
||||
├── search_context.py
|
||||
├── search_obsidian_docs.py
|
||||
├── triage_alert.py
|
||||
├── triage_email.py
|
||||
├── triage_from_text.py
|
||||
├── generate_case_note.py
|
||||
└── commit_case_memory.py
|
||||
```
|
||||
|
||||
当前 Hermes 可通过该 skill 完成：
|
||||
|
||||
- 输入结构化告警或原始邮件文本
|
||||
- 自动抽取 sender、subject、attachment、URL、IP、host、user 等关键信息
|
||||
- 查询 OpenViking 中相似历史 case
|
||||
- 查询 OpenViking 中相关 KB / Playbook
|
||||
- 查询 Obsidian 中相关 case note
|
||||
- 输出包含 `研判结果`、`关键证据`、`关联 Memory Retrieval`、`关联 Obsidian 文档`、`建议动作` 的研判报告
|
||||
- 从 normalized case 生成 Obsidian case note
|
||||
|
||||
## 当前还没有完成什么
|
||||
|
||||
当前项目还不能算生产可用，主要缺口如下：
|
||||
|
||||
- 还没有接入真实 SOC 数据源，例如 SIEM、EDR、邮件网关、ticket system、情报平台、月报、PO、历史报告。
|
||||
- 还没有自动 Obsidian sync。现在 Obsidian 新增或修改 md 不会自动总结并写入 OpenViking。
|
||||
- 还没有实现 EverMemOS worker。长期记忆抽取、合并、衰减、演化目前仍停留在设计和目录占位。
|
||||
- 检索排序仍是 POC 级别。当前可用，但还没有基于真实 SOC 数据做 rerank、误报模式识别、字段权重优化。
|
||||
- 评估闭环还不完整。已有 mock 数据，但还缺少批量 evaluation scripts、命中率统计、人工满意度记录和对比实验。
|
||||
- 安全治理还未生产化。缺少真实环境需要的权限隔离、审计日志、敏感字段脱敏、租户隔离、数据保留策略。
|
||||
- Agent 写回策略还比较保守。当前支持提交 normalized artifact，但还没有完善的“高价值记忆判定 -> 审核 -> 写回 -> 去重”工作流。
|
||||
|
||||
## 如何启动
|
||||
|
||||
使用已有环境：
|
||||
|
||||
```bash
|
||||
cd /home/tom/soc_memory_poc
|
||||
source /home/tom/OpenViking/.venv/bin/activate
|
||||
```
|
||||
|
||||
启动 Memory Gateway：
|
||||
|
||||
```bash
|
||||
python -m memory_gateway.server --config /home/tom/soc_memory_poc/config.yaml
|
||||
```
|
||||
|
||||
默认监听：
|
||||
|
||||
```text
|
||||
http://127.0.0.1:1934
|
||||
```
|
||||
|
||||
健康检查：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:1934/health
|
||||
```
|
||||
|
||||
如果 `1934` 端口被占用，先检查已有进程，不要重复启动：
|
||||
|
||||
```bash
|
||||
ss -ltnp | grep 1934
|
||||
```
|
||||
|
||||
## 如何重新生成样本数据
|
||||
|
||||
```bash
|
||||
cd /home/tom/soc_memory_poc
|
||||
source /home/tom/OpenViking/.venv/bin/activate
|
||||
|
||||
PYTHONPATH=/home/tom/soc_memory_poc python pipeline/jobs/ingest_case.py \
|
||||
--input-dir evaluation/datasets/mock_cases \
|
||||
--output-dir evaluation/datasets/normalized_cases
|
||||
|
||||
PYTHONPATH=/home/tom/soc_memory_poc python pipeline/jobs/ingest_kb.py \
|
||||
--input-dir evaluation/datasets/mock_kb \
|
||||
--output-dir evaluation/datasets/normalized_kb
|
||||
```
|
||||
|
||||
## 如何写入 OpenViking
|
||||
|
||||
写入 case：
|
||||
|
||||
```bash
|
||||
cd /home/tom/soc_memory_poc
|
||||
source /home/tom/OpenViking/.venv/bin/activate
|
||||
|
||||
PYTHONPATH=/home/tom/soc_memory_poc python skills/commit_memory_skill/commit_to_openviking.py \
|
||||
--directory evaluation/datasets/normalized_cases
|
||||
```
|
||||
|
||||
写入 KB / Playbook：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=/home/tom/soc_memory_poc python skills/commit_memory_skill/commit_to_openviking.py \
|
||||
--directory evaluation/datasets/normalized_kb
|
||||
```
|
||||
|
||||
## 如何测试
|
||||
|
||||
运行单元测试：
|
||||
|
||||
```bash
|
||||
cd /home/tom/soc_memory_poc
|
||||
source /home/tom/OpenViking/.venv/bin/activate
|
||||
PYTHONPATH=/home/tom/soc_memory_poc pytest -q
|
||||
```
|
||||
|
||||
运行 Python 编译检查：
|
||||
|
||||
```bash
|
||||
python -m compileall -q memory_gateway pipeline skills tests
|
||||
python -m py_compile /home/tom/.hermes/skills/soc-memory-poc/scripts/*.py
|
||||
```
|
||||
|
||||
运行一次核心 triage smoke test：
|
||||
|
||||
```bash
|
||||
python /home/tom/.hermes/skills/soc-memory-poc/scripts/triage_email.py --text "From: billing@vendor-payments.com
|
||||
To: alice@corp.example
|
||||
Subject: Invoice overdue notice
|
||||
Attachment: invoice_review.html
|
||||
User clicked the link after opening the HTML attachment. DMARC failed. Review at https://vendor-payments-login.com/review from IP 198.51.100.20 on host FIN-LAPTOP-12."
|
||||
```
|
||||
|
||||
预期输出应包含：
|
||||
|
||||
- `研判结果`
|
||||
- `关键证据`
|
||||
- `关联 Memory Retrieval`
|
||||
- `关联 Obsidian 文档`
|
||||
- `建议动作`
|
||||
|
||||
## 如何用 Hermes 演示
|
||||
|
||||
确保 Memory Gateway 已启动，然后执行：
|
||||
|
||||
```bash
|
||||
/home/tom/.local/bin/hermes chat --quiet --skills soc-memory-poc -q "Use the soc-memory-poc skill. Triage this email alert and include Memory Retrieval and Obsidian references.
|
||||
|
||||
From: billing@vendor-payments.com
|
||||
To: alice@corp.example
|
||||
Subject: Invoice overdue notice
|
||||
Attachment: invoice_review.html
|
||||
User clicked the link after opening the HTML attachment. DMARC failed. Review at https://vendor-payments-login.com/review from IP 198.51.100.20 on host FIN-LAPTOP-12."
|
||||
```
|
||||
|
||||
演示重点不是让 Hermes 凭空研判，而是展示它会先调用 SOC Memory POC skill，检索历史 case、KB / Playbook 和 Obsidian note，再把这些证据带入最终研判。
|
||||
|
||||
## 如何生成 Obsidian Case Note
|
||||
|
||||
```bash
|
||||
cd /home/tom/soc_memory_poc
|
||||
source /home/tom/OpenViking/.venv/bin/activate
|
||||
|
||||
PYTHONPATH=/home/tom/soc_memory_poc python skills/summarize_case_skill/generate_case_note.py \
|
||||
--input evaluation/datasets/normalized_cases/CASE-2026-0001.json \
|
||||
--enrich-from-openviking \
|
||||
--top-k 3
|
||||
```
|
||||
|
||||
输出文件位于：
|
||||
|
||||
```text
|
||||
obsidian-vault/02_Cases/<scenario>/
|
||||
```
|
||||
|
||||
## 当前效果
|
||||
|
||||
当前 POC 已经可以完成一条基础 SOC 研判辅助链路：
|
||||
|
||||
1. analyst 或 Hermes 输入告警 / 邮件内容。
|
||||
2. Hermes skill 抽取关键字段并判断场景。
|
||||
3. 通过 Memory Gateway 查询 OpenViking 中的相似历史 case。
|
||||
4. 通过 Memory Gateway 查询相关 KB / Playbook。
|
||||
5. 本地检索 Obsidian case note。
|
||||
6. 输出带证据来源的研判报告。
|
||||
7. 对成熟 case，可生成 Obsidian case note，并可将 normalized artifact 写回 OpenViking。
|
||||
|
||||
在真实 SOC 场景中，当前版本适合做 demo、POC 验证和离线评估；不建议直接作为生产系统接入真实告警闭环。
|
||||
|
||||
## 下一阶段开发计划
|
||||
|
||||
### P0：补齐真实输入与评估闭环
|
||||
|
||||
- 设计真实 ticket / alert 的最小字段映射，不先接全量日志。
|
||||
- 增加 `evaluation/scripts/`，批量跑 mock case，统计 case 命中率、KB 命中率、输出完整率。
|
||||
- 为 phishing / O365 两类场景定义人工标注答案，用于评估检索质量。
|
||||
|
||||
### P1：增强 Obsidian 与 OpenViking 的同步
|
||||
|
||||
- 新增 Obsidian md 扫描脚本，读取新增 / 修改 note。
|
||||
- 从 Obsidian note 中抽取 title、tags、scenario、case_id、summary、IOC、verdict。
|
||||
- 生成 normalized knowledge / case artifact。
|
||||
- 经过去重和质量阈值后写入 OpenViking。
|
||||
|
||||
### P1：完善 Hermes 研判工作流
|
||||
|
||||
- 让 Hermes 输出更稳定地引用具体 `case_id`、`doc_id`、Obsidian 相对路径。
|
||||
- 增加 O365 异常登录专用 triage prompt 和 demo。
|
||||
- 增加 case 结束后的“是否沉淀为记忆”判断模板。
|
||||
|
||||
### P2：实现 EverMemOS 长期记忆整理层
|
||||
|
||||
- 从 case note、process summary、agent final report 中抽取长期可复用记忆。
|
||||
- 对重复 case pattern 做合并。
|
||||
- 对低价值、过时、误导性记忆做衰减或清理。
|
||||
- 将高价值 pattern 回灌到 OpenViking，必要时生成 Obsidian 摘要 note。
|
||||
|
||||
### P2：生产化安全与治理
|
||||
|
||||
- 增加 API Key / token 的部署规范。
|
||||
- 增加数据脱敏策略。
|
||||
- 增加写入审计日志。
|
||||
- 增加 namespace / workspace / agent 级别隔离。
|
||||
|
||||
## 推荐落地顺序
|
||||
|
||||
1. 固定 phishing 和 O365 两类场景的 normalized schema。
|
||||
2. 建立 20 到 50 条脱敏样本，先覆盖真实高频告警。
|
||||
3. 完成批量 evaluation，明确检索命中率和输出质量基线。
|
||||
4. 接入 Obsidian -> OpenViking 的半自动同步。
|
||||
5. 接入一个真实 agent 工作流，例如 Hermes triage。
|
||||
6. 再实现 EverMemOS 长期记忆整理，不要过早做复杂长期记忆平台。
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user