ThreatRecall/zettelforge

# ZettelForge **专为网络威胁情报构建的唯一智能体记忆系统。** 当资深分析师离职时，他们带走了两三年的背景信息——客户环境、过往调查、攻击者 TTP、误报模式，以及每一次来之不易的“等等，我们以前见过这个”的经验。ZettelForge 就是为了让这些背景信息留在团队中而构建的智能体记忆系统。 它从分析师的笔记和威胁报告中提取 CVE、威胁行为者、IOC 和 ATT&CK 技术，解析别名（APT28 = Fancy Bear = STRONTIUM = Sofacy），构建 STIX 2.1 知识图谱，并以自然语言将过去的每项调查反馈给你的分析师——以及通过 MCP 反馈给 Claude Code。完全在本地进程内运行。无需 API 密钥。无云依赖。数据绝不离开本地主机。 [](https://pypi.org/project/zettelforge/) [](https://pepy.tech/projects/zettelforge) [](https://star-history.com/#rolandpg/zettelforge&Date) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://github.com/rolandpg/zettelforge/actions) [](https://github.com/rolandpg/zettelforge/issues) **[Star](https://github.com/rolandpg/zettelforge) · [`pip install zettelforge`](https://pypi.org/project/zettelforge/) · [文档](https://docs.threatrecall.ai/) · [ThreatRecall (托管版)](https://threatrecall.ai) · [更新日志](CHANGELOG.md)**

## 问题所在 每个 SOC 都会流失分析师。当他们离职时，调查背景、攻击者归属以及特定环境的误报模式也会随之流失。他们的替代者不得不重新打开相同的工单，重新阅读相同的报告，并从零开始重新构建相同的思维模型。 通用的 AI 记忆系统无法为安全团队解决这一问题。它们无法区分 APT28 和 Fancy Bear，不知道 CVE-2024-3094 是 XZ Utils 后门，无法解析 Sigma 或 YARA，也没有 MITRE ATT&CK 技术 ID 的概念。当 CTI 分析师向它们提供一年的情报报告时，它们只能返回基于聊天记录的模糊语义搜索。 ZettelForge 是为习惯用威胁图谱进行思考的分析师而构建的。它会自动提取 CVE、威胁行为者、IOC 和 ATT&CK 技术，解析不同命名规范中的别名，构建具有因果关系和时序追踪的知识图谱，并使用意图感知的混合检索来提取记忆——所有这些都在本地进程内完成，无需依赖任何外部 API。 | 功能 | ZettelForge | Mem0 | Graphiti | Cognee | |---|---|---|---|---| | CTI 实体提取 (CVE, 行为者, IOC) | 是 | 否 | 否 | 否 | | STIX 2.1 本体 | 是 | 否 | 否 | 否 | | 威胁行为者别名解析 | 是 (APT28 = Fancy Bear) | 否 | 否 | 否 | | 具有因果关系三元组的图谱 | 是 | 否 | 是 | 是 | | 意图分类检索 (5 种类型) | 是 | 否 | 否 | 否 | | 进程内运行 / 无需外部 API | 是 | 否 | 否 | 否 | | OCSF 格式的审计日志 | 是 | 否 | 否 | 否 | | MCP server (Claude Code) | 是 | 否 | 否 | 否 | ## 数据流水线

## 功能特性 **实体提取** —— 自动识别 CVE、威胁行为者、IOC（IP、域名、哈希、URL、电子邮件）、MITRE ATT&CK 技术、攻击战役、入侵集合、工具、人员、位置和组织。全程采用正则表达式 + LLM NER 技术并符合 STIX 2.1 类型标准。 **知识图谱** —— 实体转化为节点，共现关系转化为边。LLM 推断因果关系三元组（例如“APT28 *使用* Cobalt Strike”）。时序边和更迭关系用于追踪情报的演变过程。 **别名解析** —— APT28、Fancy Bear、Sofacy、STRONTIUM 均会解析到同一个行为者节点。在存储和调用时自动运行。 **混合检索** —— 向量相似度（768 维 fastembed，ONNX）+ 图谱遍历（在知识图谱边上执行 BFS），根据意图分类进行加权。包含五种意图类型：事实型、时序型、关系型、探索型和因果型。 **记忆演化** —— 开启 `evolve=True` 后，会将新情报与现有记忆进行比对。由 LLM 决定执行 ADD、UPDATE、DELETE 或 NOOP。过时情报会被取代，矛盾之处会被解决，重复项则会被跳过。 **RAG 综合** —— 通过 `direct_answer` 格式综合所有存储记忆以生成答案。 **架构上的进程内运行** —— 使用 fastembed (ONNX) 生成嵌入，使用 llama-cpp-python 进行可选的本地 LLM 推理，使用 SQLite + LanceDB 进行存储，默认在 localhost 上运行 Ollama。无需外部 API 密钥。首次运行时在下载嵌入/LLM 模型可能会触发外部网络访问；预加载模型后，即可完全离线运行（包括在气隙隔离主机上）。 **OCSF 格式的审计日志** —— 每次操作都会以 Open Cybersecurity Schema Framework 格式发出结构化事件。至于如何处理这些日志流（接入 SIEM、WORM 存储或是不处理）则完全取决于你。 ## 快速开始 ### 30 秒 hello world（无需 LLM） ``` pip install zettelforge ``` ``` from zettelforge import MemoryManager mm = MemoryManager() # 存储 CTI -- 通过 regex 提取的实体（CVEs, actors, ATT&CK IDs, IOCs） mm.remember("APT28 uses Cobalt Strike for lateral movement via T1021") mm.remember("APT28 (Fancy Bear) targets NATO defense contractors with spear-phishing") mm.remember("CVE-2024-3094 is the XZ Utils backdoor (CVSS 10.0) affecting sshd") # 召回结合 vector + graph search；alias resolution 生效（Fancy Bear -> APT28） for note in mm.recall("What tools does Fancy Bear use?", k=3): print(f"[{note.metadata.tier}] {note.content.raw}") ``` 只需全新 `pip install` 即可运行，无需任何外部服务。嵌入通过 fastembed 在进程内运行（首次调用时下载约 80MB 的 ONNX 模型）。`MemoryManager()` 默认写入 `~/.amem/`；可通过 `ZETTELFORGE_DATA_DIR` 或配置文件进行覆盖。完整可运行示例位于 [`examples/quickstart.py`](examples/quickstart.py)。 ### 添加 LLM 以进行综合和更丰富的提取 ``` ollama pull qwen3.5:9b && ollama serve ``` ``` # 在 Ollama 运行的情况下，synthesize() 返回基于已存储笔记的真实摘要 answer = mm.synthesize("Summarize known APT28 TTPs") print(answer["synthesis"]["answer"]) # 后台 LLM NER 还会使用额外实体丰富已存储的笔记 ``` ZettelForge 会自动检测 Ollama。要使用其他提供商（用于本地 llama-cpp 的 `local`、支持 100 多家提供商的 `litellm`、用于测试的 `mock`），请参阅[配置说明](#configuration)。在没有 LLM 的情况下，`synthesize()` 仍会返回结构化响应，但 `answer` 字段将是回退占位符——在仅使用 pip 安装的模式下，只有 `remember` 和 `recall` 会产生有用的结果。 ### 记忆演化 ``` # 新情报到达 -- evolve=True 启用 memory evolution： # LLM 提取事实，与现有笔记进行比较，决定 ADD/UPDATE/DELETE/NOOP mm.remember( "APT28 has shifted tactics. They dropped DROPBEAR and now exploit edge devices.", domain="cti", evolve=True, # existing APT28 note gets superseded, not duplicated ) ``` ## 工作原理 每次调用 `remember()` 都会触发以下流水线： 1. **实体提取** —— 正则表达式 + LLM NER 识别 CVE、入侵集合、威胁行为者、工具、攻击战役、ATT&CK 技术、IOC（IPv4、域名、URL、MD5/SHA1/SHA256、电子邮件）、人员、位置、组织、事件、活动以及时间引用（共 19 种类型） 2. **知识图谱更新** —— 实体转化为节点，共现关系转化为边，LLM 推断因果关系三元组 3. **向量嵌入** —— 768 维 fastembed（ONNX，进程内运行，7ms/次嵌入）存储于 LanceDB 中 4. **更迭检查** —— 实体重叠检测将过时笔记标记为已更迭 5. **双流写入** —— 快速路径在约 45ms 内返回；因果丰富操作延迟至后台 worker 执行 每次调用 `recall()` 都会混合两种检索策略： 1. **向量相似度** —— 在嵌入上进行语义搜索 2. **图谱遍历** —— 在知识图谱的边上进行 BFS，根据跳数进行评分 3. **意图路由** —— 查询被分类为事实型/时序型/关系型/因果型/探索型，并根据类型调整权重 4. **Cross-encoder 重排** —— ms-marco-MiniLM 根据相关性对最终结果进行重新排序 ## 60 秒内在 Claude Desktop 中使用 ZettelForge ``` pip install zettelforge ``` 在你的项目根目录中创建或编辑 `.claude.json`（如需全局访问，请编辑 `~/.claude/.claude.json`）： ``` { "mcpServers": { "zettelforge": { "command": "python3", "args": ["-m", "zettelforge.mcp"] } } } ``` 如果 ZettelForge 安装在虚拟环境中，请使用该 Python 解释器的完整路径： ``` { "mcpServers": { "zettelforge": { "command": "/home/user/.venvs/zettelforge/bin/python", "args": ["-m", "zettelforge.mcp"] } } } ``` 启动 Claude Code 并验证工具是否可用： ``` claude # 在 session 中，提问：“What tools do you have available from zettelforge?” ``` 系统暴露了七个工具：`zettelforge_remember`、`zettelforge_recall`、`zettelforge_synthesize`、`zettelforge_entity`、`zettelforge_graph`、`zettelforge_stats` 和 `zettelforge_sync`（需要企业版包）。有关完整的 schema、JSON-RPC 请求/响应示例、错误代码以及惰性单例生命周期，请参阅 [MCP 协议参考](docs/reference/mcp-protocol.md)。如需故障排除、虚拟环境路径以及手动工具测试，请参阅 [set-up-mcp-server](docs/how-to/set-up-mcp-server.md)。 ## 基准测试 基于已发表的学术基准进行了评估： | 基准测试 | 测量内容 | 得分 | |---|---|---| | **CTI Retrieval** (CTIBench 子集) | 归属、CVE 关联、多跳 | **75.0%** | | **RAGAS** | 检索质量（关键词存在情况） | **78.1%** | | **LOCOMO** (ACL 2024) | 对话记忆调用 | **22.0%** | **得分**列报告的是使用 Ollama 托管模型运行的 ZettelForge 测量结果，但有一个例外：LOCOMO 行是在 v2.1.1 版本中使用 Ollama 云端评估器重新测量的（而非本地生成）。有关特定基准的方法论、版本历史以及各测试套件的评估器配置，请参阅[完整基准报告](benchmarks/BENCHMARK_REPORT.md)。 ## 将检测规则作为记忆 (Sigma + YARA) Sigma 和 YARA 规则是第一 class 的记忆原语。解析、验证并提取一条规则后，其标签就会转化为图谱边：MITRE ATT&CK 技术、CVE、威胁行为者别名、工具和恶意软件家族都会像其他所有笔记一样，根据相同的本体进行解析。共享的 `DetectionRule` 超类型承载了 `SigmaRule` 和 `YaraRule` 子类型，因此单一的规则 UUID 可以在这两种格式中进行寻址。 Sigma 规则会根据内置的 [SigmaHQ JSON schema](https://github.com/SigmaHQ/sigma-specification) 进行验证。YARA 规则使用 plyara 进行解析，并根据 [CCCS YARA metadata standard](https://github.com/CybercentreCanada/CCCS-Yara) 进行检查（级别包括：`strict`、`warn`、`non_cccs`）。提取是幂等的——重新提取未更改的规则会通过内容哈希的 `source_ref` 返回原始笔记。 ``` from zettelforge import MemoryManager from zettelforge.sigma import ingest_rule as ingest_sigma from zettelforge.yara import ingest_rule as ingest_yara mm = MemoryManager() ingest_sigma("rules/proc_creation_win_office_macro.yml", mm) ingest_yara("rules/webshell_china_chopper.yar", mm, tier="warn") ``` ``` # 从 SigmaHQ 或私有 rule repo 批量导入 python -m zettelforge.sigma.ingest /path/to/sigma/rules/ python -m zettelforge.yara.ingest /path/to/yara/rules/ --tier warn # CI fixture check -- parse + validate，不进行写入 python -m zettelforge.sigma.ingest rules/ --dry-run ``` LLM 规则解释器 (`zettelforge.detection.explainer.explain`) 可为任何 `DetectionRule` 生成结构化的 JSON 摘要——包括意图、关键字段、规避说明、误报假设等。在 v1 版本中，它按需同步运行；v1.1 版本将加入异步丰富队列连接。通过 `ZETTELFORGE_EXPLAIN_RPM` 进行速率限制（默认 60 次调用/分钟）。 参考：[Sigma 规范](https://github.com/SigmaHQ/sigma-specification)、[SigmaHQ 规则](https://github.com/SigmaHQ/sigma)、[CCCS YARA](https://github.com/CybercentreCanada/CCCS-Yara)、[YARA 文档](https://yara.readthedocs.io)。 ## 集成 ### ATHF (智能体威胁狩猎框架) 将已完成的 [ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework) 狩猎结果提取到 ZettelForge 记忆中。MITRE 技术和 IOC 将被提取并链接到知识图谱中。 ``` python examples/athf_bridge.py /path/to/hunts/ # 已 parse 12 个 hunt(s) # 已将 12/12 个 hunt(s) 导入 ZettelForge ``` 请参阅 [examples/athf_bridge.py](examples/athf_bridge.py)。 ## ThreatRecall (托管版) [ThreatRecall](https://threatrecall.ai) 是 ZettelForge 的商业发行版，启用了企业级扩展。它默认作为托管 SaaS 提供，并为机密环境提供可选的本地自托管和气隙隔离部署。企业级附加功能： - **TypeDB STIX 2.1 后端** —— 带有推理规则的 schema 强制本体 - **OpenCTI 同步** —— 与你的 OpenCTI 实例进行双向同步 - **多租户认证** —— OAuth/JWT，每个租户的数据隔离 - **Sigma 规则生成** —— 从提取的 IOC 生成检测规则（即将推出） SaaS 版本可在几分钟内部署完毕，无需维护任何基础设施。自托管版本以可部署 bundle 的形式提供，适用于限制或禁止外部网络流出的环境。 **[加入候补名单](https://threatrecall.ai)** —— 目前正在接入设计合作伙伴。 ## 配置 | 变量 | 默认值 | 描述 | |---|---|---| | `AMEM_DATA_DIR` | `~/.amem` | 数据目录 | | `ZETTELFORGE_BACKEND` | `sqlite` | SQLite 社区版后端。可通过扩展使用 TypeDB。 | | `ZETTELFORGE_LLM_PROVIDER` | `local` | `local` (llama-cpp) 或 `ollama` | 有关所有选项，请参阅 [config.default.yaml](config.default.yaml)。 ## License MIT —— 请参阅 [LICENSE](LICENSE)。 由 **Patrick Roland** 构建 —— [LinkedIn](https://www.linkedin.com/in/patrickgroland/) | Summit 7 Systems SOC 服务总监 | 海军核退伍军人 | CISSP, CCP (CMMC 2.0 专业人员) ## 支持该项目 ZettelForge 采用 MIT 许证。欢迎 Star 本仓库、开启 issue 并提交 PR——欢迎所有贡献。 ## 致谢 - 灵感来自 [Zettelkasten](https://en.wikipedia.org/wiki/Zettelkasten) 和 [A-Mem](https://arxiv.org/abs/2602.10715) (NeurIPS 2025) - 两阶段流水线灵感来自 [Mem0](https://mem0.ai/research) - STIX 2.1 schema 参考自 [typedb-cti](https://github.com/typedb-osi/typedb-cti) - 基准测试对比于 [LOCOMO](https://snap-research.github.io/locomo/) (ACL 2024) 和 [CTIBench](https://arxiv.org/abs/2406.07599) (NeurIPS 2024) - [LanceDB](https://lancedb.com) | [fastembed](https://github.com/qdrant/fastembed) | [Pydantic](https://pydantic.dev) | [TypeDB](https://typedb.com)

标签：AI风险缓解, CNCF毕业项目, MCP, Python, RAG, STIX, 威胁情报, 开发者工具, 无后门, 智能体记忆, 逆向工具