Chaelsoo/Zetsu

一个用于攻防安全知识的个人离线 RAG 系统。导入你的 writeup、实验室解题、漏洞赏金报告和安全博客，然后在实际操作时使用自然语言进行查询。无需云服务，无需 SaaS，你的知识始终属于你。 ## 功能简介 ZETSU 将你积累的知识转化为可查询的助手。你不再需要在 markdown 文件中 grep 或苦苦回忆哪篇 writeup 包含那条 certipy 命令，而是可以直接用自然语言提问： ``` how do i escalate with SeImpersonatePrivilege what did i do after getting ADFS access sliver socks5 pivot setup explain ESC8 vs ESC4 ``` 它会优先从你的实际笔记中检索，然后根据你记录的内容生成答案，而不是依赖于网络上的通用知识。 ## 架构 ### 数据导入 pipeline  ### 查询 pipeline  ## 特性 - **FARR 提取：** 在导入时，LLM 会阅读你的 writeup 的每个部分，并提取出结构化的攻击步骤（Finding、Action、Reasoning、Result）。你检索到的是一个语义单元，而不是随机截取的 800-token 窗口。 - **混合检索：** 使用 BM25 进行精确的 token 匹配（工具名称、CVE 编号、CLI 参数）+ 向量搜索计算语义相似度。通过 RRF 融合算法将两者结合。 - **Cross-encoder 重排序：** 在发送给 LLM 之前，根据实际的关联度对检索到的数据块进行重新排序。 - **双响应风格：** Operator 模式优先提供精确的命令，Concept 模式优先提供推理过程。使用相同的检索结果，不同的呈现方式。在 TUI 中使用 `Ctrl+M` 进行切换。 - **多种 LLM 后端：** 支持 Anthropic、兼容 OpenAI 的 API（DeepSeek 等），或本地的 Ollama。支持为数据导入和查询配置独立的后端。 - **多种数据源类型：** 本地 markdown 文件、单个 URL、GitHub wiki、Atom/RSS 订阅源。 - **持久化聊天记录：** 保存至 `~/.zetsu/history/YYYY-MM-DD.json`，可通过 `/history` 浏览。 - **TUI + Web UI + CLI：** 根据场景选择合适的模式。实战操作使用 TUI，学习研究使用 Web UI，编写脚本使用 CLI。 ## 安装说明 ``` git clone https://github.com/chaelsoo/zetsu cd zetsu pip install -r requirements.txt ``` 设置你的 API key： ``` cp .env.example .env # 编辑 .env 并添加你的 key ``` ## 快速开始 **1. 添加你的 writeup** 将 `.md` 文件放入 `docs/` 目录。支持 Notion 导出、Obsidian 笔记、博客导出等任何 markdown 格式。 **2. 在 `config.toml` 中配置数据源** ``` [llm] backend = "openai" openai_model = "deepseek-chat" base_url = "https://api.deepseek.com/v1" [[sources]] type = "markdown_dir" path = "./docs" name = "my_writeups" extract = "farr" enabled = true ``` **3. 导入数据** ``` python zetsu.py ingest ``` **4. 开始使用** ``` python zetsu.py tui # terminal UI python zetsu.py web # browser at localhost:8000 python zetsu.py ask "how do i abuse SeImpersonatePrivilege" ``` ## CLI 参考 ``` python zetsu.py ingest # ingest enabled sources python zetsu.py ingest --force # wipe and rebuild everything python zetsu.py ingest --dry-run # estimate without making LLM calls python zetsu.py ingest --all-sources # enable all sources regardless of enabled flag python zetsu.py tui # terminal UI python zetsu.py web # web UI python zetsu.py ask "query" # one-shot CLI python zetsu.py ask "query" --style concept python zetsu.py stats # vector store stats ``` ## TUI 快捷键 | 按键 | 操作 | |-----|--------| | `Enter` | 发送查询 | | `Ctrl+M` | 切换 Operator / Concept 模式 | | `Ctrl+Y` | 复制上次回复到剪贴板 | | `Ctrl+L` | 清除当前会话 | | `Ctrl+C` | 退出 | | `/help` | 显示命令 | | `/stats` | Vector store + 历史记录统计 | | `/history` | 今日的历史查询 | | `/clear` | 清除当前会话 | ## 数据源类型 | 类型 | 用途 | 提取模式 | |------|---------|--------------| | `markdown_dir` | 你的 writeup、笔记 | `farr` | | `markdown_file` | 单个 markdown 文件 | `farr` | | `url` | 工具 wiki、参考页面 | `headers` | | `atom` | 带有订阅源的安全博客 | `farr+narrative` | ### 提取模式 - **`farr`：** LLM 将离散的攻击步骤提取为结构化的 JSON（Finding、Action、Reasoning、Result）。最适合具有明确攻击链的 writeup。 - **`farr+narrative`：** 与 farr 相同，并增加了一段捕捉作者推理过程的叙述性摘要。最适合注重思考过程的博客。 - **`headers`：** 不使用 LLM，仅根据标题进行分割并保留原文。最适合命令参考和工具文档。 ## LLM 后端 在 `config.toml` 中配置。为数据导入（批量提取）和查询（生成内容）提供独立的后端： ``` [llm] # query time backend = "openai" openai_model = "deepseek-chat" base_url = "https://api.deepseek.com/v1" [ingest] # ingest time backend = "openai" openai_model = "deepseek-chat" base_url = "https://api.deepseek.com/v1" workers = 8 # parallel files during FARR extraction ``` 支持的后端包括：`anthropic`、`openai`（任何兼容 OpenAI 的 API）、`ollama`。 ## 基准测试 在涵盖 12 个攻防安全类别的 910 个问题中进行了评估 （ADCS、Kerberos、AD enumeration、MSSQL、Sliver C2、privilege escalation、 web attacks、credentials、lateral movement、cloud/Entra ID、OPSEC、工具）。 | 指标 | 结果 | |--------|--------| | 已回答的问题 | 910 / 910 (100%) | | 包含代码/命令的回答 | 842 / 910 (93%) | | 上下文缺失（模型承认缺少信息） | 66 / 910 (7.3%) | | 平均检索时间 | 68ms | | 平均总响应时间 | 3.8s | 为回答做出贡献的主要数据源：个人 HTB writeup、dirkjanm 博客、shenaniganslabs 研究、HackTricks ADCS、Sliver wiki、netexec cheatsheet。 简而言之，你需要确保添加高质量且结构化良好的资源供 RAG 导入，本项目 100% 专注于使用知识库，而不是信任 LLM 的记忆或预训练知识。 完整的评估数据集和结果见 [`eval/`](eval/)。 ## 参考文献 - [rank-bm25](https://github.com/dorianbrown/rank_bm25)，BM25 检索 - FARR 概念来自 [CIPHER](https://github.com/ibndias/CIPHER) - RAG pipeline 灵感来自 [rag-chatbot](https://github.com/umbertogriffo/rag-chatbot)

标签：AI风险缓解, LLM, Petitpotam, RAG, Ruby, Unmanaged PE, 数据展示, 本地大模型, 知识库, 红队, 逆向工具