PentHertz/grimoire

# Grimoire **攻防知识，离线获取。一个搜索框搞定所有手册。** Grimoire 会克隆一系列精选的安全知识库，将其所有的 markdown/YAML 内容索引到一个统一的全文搜索索引中，并提供一个快速的 Web UI。 输入 `ssrf`、`xss`、`sql`、`kerberoast`、`sudo`、`jwt` 等，它会瞬间从*每一个*来源中——包括 HackTricks、PayloadsAllTheThings、OWASP 指南、living-off-the-land 数据库以及你自己的笔记——提取出匹配的页面，并提供指向原始页面的链接。 它旨在可在任何地方运行（单个 Python 脚本，无强制依赖服务），并可被嵌入到 RF-Swift 中。 ``` GRIMOIRE offensive knowledge, offline > ssrf_ -> HackTricks . PayloadsAllTheThings . WSTG . API Top 10 ... ``` ## 功能 - 通过 SQLite **FTS5** 和 BM25 排序，对 20 多个来源进行**统一搜索** —— 无论各个仓库采用何种编写方式（mdBook、mkdocs、Jekyll、Hugo、纯 markdown、YAML），都使用统一的查询语言。 - 拉取后**完全离线**。运行时无遥测，无外部调用。 - **可生成的 Web 服务** - `grimoire.py serve`（绑定主机/端口；可在后台运行或作为容器服务）。 - **溯源** - 每个文档都会显示其来源以及指向 **GitHub 上原始文件** 的链接，因此你始终知道指导内容的出处。 - **丰富的渲染** - 图片可正常显示，相对 `.md` 链接可在查看器内导航（相对的 ``/链接会被重写为受保护的 `/asset` / `/doc` 端点）。注意：对于稀疏检出（sparse）的来源（例如 Ghidra），存储在检出路径之外的图片将无法显示 - 如有需要，请扩大来源的 `sparse:` 列表。 - **一键复制** - 每个代码/命令块上都有点击复制按钮。 - **OSINT 注意事项** - OSINT 工具通常针对个人；请在授权评估允许的范围内收集信息并进行记录（GDPR），特别是涉及具体人员时。 - **Obsidian 友好** - 将其指向你的知识库；支持处理 `[[wikilinks]]`、`#tags` 和 YAML frontmatter（链接/标签会变为可点击的搜索）。 - **自带文档** - 将 markdown 放入 `custom/` 目录或注册一个本地路径。 - **可选的原生构建** - 在工具链可用时，渲染来源自身的 mdBook/mkdocs 站点；搜索功能从不依赖于此。 - **附加 AI 模型 (MCP)** - `grimoire.py mcp` 通过 Model Context Protocol 暴露索引，以便 Claude / Codex / Gemini 或任何 MCP 客户端进行搜索、 阅读文档、构建基于来源的技术清单、将某个主题的阅读材料整合为完整的带引用教程，并审查文档是否最新 / 寻找更好的技术。它还能适应你的**评估上下文**（目标、 接口、硬件/SDR、SIM、RF），从而使建议符合你的评估需求。 默认的 `read` 模式为只读（无 shell，无写入）；可选择启用 `--mode assist|auto`，允许其检测/安装缺失的工具（RF-Swift recipe，否则使用宿主机的包管理器）并运行步骤，同时受到破坏性命令黑名单和目标范围的限制。详见 [docs/MCP_TUTORIAL.md](docs/MCP_TUTORIAL.md)。 ## 来源 在 [`sources.yaml`](sources.yaml) 中精选，按类别分组： | 类别 | 来源 | |---|---| | `wikis` | HackTricks, HackTricks Cloud, PayloadsAllTheThings, The Hacker Recipes, six2dez Pentest Book | | `ad-internal` | InternalAllTheThings, ired.team, OCD mindmaps | | `c2` | Sliver | | `hardware-iot` | HardwareAllTheThings | | `mobile` | OWASP MASTG, OWASP MASVS | | `web-api` | OWASP WSTG, Cheat Sheet Series, ASVS, API Security Top 10 | | `lotl` | GTFOBins, LOLBAS, GTFOArgs, LOLDrivers, LOOBins, WADComs | | `re-books` | mytechnotalent/Reverse-Engineering, Nightmare, how2heap（在 `custom/` 中放入 PDF 书籍即可添加） | | `re-tools` | radare2book, rizin book, angr docs, Ghidra (in-tree docs) | | `re-indexes` | Awesome-Reversing (ReversingID + tylerha97), reverse-engineering (wtsxDev), Awesome Malware Analysis, Awesome Android RE | | `firmware` | Awesome Firmware Security | | `osint` | awesome-osint (jivoi), OSINT Framework (JSON tree), OSINT Collection, Awesome-OSINT-List, osint_stuff_tool_collection, sinwindie/OSINT, Trace Labs awesome-osint | | `dfir` | awesome-forensics, awesome-incident-response, awesome-memory-forensics, ForensicArtifacts, KapeFiles, CERT-SG IRM, PagerDuty IR, IR-plan-template, Velociraptor, Volatility 3, plaso, Dissect | | `glitching` | findus/fault-injection-library, ChipWhisperer (+ Jupyter Fault101/201), ChipSHOUTER-PicoEMP, Faulty Cat, SimpleLink-FI, PicoGlitcher-LPC1343 | | `bluetooth` | awesome-bluetooth-security, BlueToolkit, Sniffle, Ubertooth, InternalBlue, SweynTooth, BrakTooth, KNOB/BIAS/BLUFFS, Mirage, BtleJack, bleah, OpenHaystack, Continuity, apple_bleee, BLE CTF | | `wifi` | awesome-wifi-security, 0xor0ne awesome-list, MacStealer/FragAttacks/KRACK (Vanhoef), Dragonslayer/Dragondrain/Dragonforce, hcxdumptool/hcxtools, aircrack-ng, AngryOxide, airgeddon, eaphammer, hostapd-mana, wifipumpkin3, DragonShift, WiFiChallengeLab | | `sdr` | PySDR, ThinkDSP, SDR-for-Engineers (lectures+labs), SDRangel, SDR++, inspectrum, URH, liquid-dsp, mhostetter/sdr, scikit-dsp-comm, CommPy, SoapySDR, learnSDR | | `compliance` | awesome-compliance, NIST OSCAL, OWASP SAMM (NIST PDFs / CIS / SCF crosswalk / CCM / SANS / ANSSI-EBIOS / NIS2-DORA-CRA / CNIL / CISO Assistant = drop-in or run-the-tool) | ## 安装与运行 使用 pipx（推荐）或 pip 作为 CLI 工具安装 - 这会将 `grimoire` 添加到你的 PATH 中： ``` pipx install . # (from a checkout) grimoire all # clone every source + build the index grimoire serve # http://127.0.0.1:8000 grimoire mcp # attach an AI model over MCP ``` 安装后，用户状态（可编辑的 `sources.yaml`、`custom/` 和 `data/` 索引）位于 `$GRIMOIRE_HOME`（默认为 `~/.local/share/grimoire`）；清单会在首次运行时从打包的默认配置中生成。 或者直接从检出版运行（无需安装）： ``` pip install -r requirements.txt # PyYAML + markdown (both optional-degrading) ./grimoire.py all # clone every source + build the index ./grimoire.py serve # http://127.0.0.1:8000 ``` 有关日常命令和搜索技巧，请参阅 [docs/QUICKSTART.md](docs/QUICKSTART.md)。 ## 命令 | 命令 | 功能 | |---|---| | `fetch [--only N...]` | git clone/pull 源到 `data/sources/` | | `build` | 可选的原生 mdBook/mkdocs 渲染到 `data/build/` | | `index [--force]` | 在 `data/index.db` 进行增量 FTS5 索引（仅重新索引 git 提交/内容发生变化的源；`--force` = 全量重建） | | `serve [--host H --port P]` | 启动 Web 搜索 UI | | `all [--only N...]` | `fetch` + `index` | | `update [--only N...]` | 刷新文档：`fetch` + `index`（`all` 的别名） | | `mcp` | 通过 MCP (stdio) 暴露 Grimoire，以便 AI 模型接入 | 也可以通过 Web UI 中的 **Update docs** 按钮实时刷新文档 （运行后台 `fetch` + 重新索引并流式传输进度）。 ## 代码布局 (MVC) 入口点 `grimoire.py` 是一个轻量级启动器；具体实现位于 `grimoire_app/` 包中，结构划分清晰： | 模块 | 职责 | |---|---| | `config.py` | 文件系统路径 + 索引常量（单一事实来源） | | `model.py` | 数据：来源清单、拉取、索引、`Index` 存储 + 搜索 | | `view.py` | 渲染：markdown/obsidian/pdf/notebook -> 安全的 HTML，应用 CSP 的页面 | | `controller.py` | HTTP 处理程序 + 将模型和视图连接在一起的 CLI 命令 | | `mcp.py` | MCP 服务器（搜索/文档/清单/教程/审查工具 + prompts） | | `context.py` | 用于 MCP 层的评估上下文（目标、硬件、SIM、RF） | | `runner.py` | 受控执行：环境检测、安装解析器、命令运行器 | 该软件包还附带了 `web/`（UI）和 `sources.default.yaml`（种子清单），因此 pip/pipx 安装是完全独立的。 所有 SQL 都通过 `model.Index` 处理，其中每条语句都是参数化的（值被绑定，绝不进行字符串格式化），自由文本查询在到达 MATCH 表达式之前会经过 `_fts_query` 处理（仅限字母数字前缀 token）—— 因此，恶意的查询既无法突破 SQL，也无法突破 FTS5 语法。测试套件包含专门的 SQLi、XSS、SSTI、CSRF 和路径遍历测试用例（`python3 -m unittest`）。 ## 工作原理 - **fetch** 浅克隆每个 `sources.yaml` 仓库到 `data/sources/`。 - **index** 遍历每个 `*.md` / `*.markdown` / `*.mdx` / `*.rst` / `*.yml` / `*.yaml` 文件（包含 `.rst` 是为了让由 Sphinx 记录的项目贡献其*完整*的文档，而不仅仅是 README）并将其存储在 SQLite FTS5 表（`data/index.db`）中，并带有 BM25 排序。这是统一层：所有来源，一个查询，无论采用何种编写格式。一个源可以通过 `index_ext:` 拉取额外的扩展名（例如 `.ipynb`、`.json`），并且为了提取最大量的内容，除非设置了 `docs_dir:`/`sparse:` 来限制庞大仓库的范围，否则将对源进行整体索引。 - **serve** 是一个无依赖的 `http.server`，暴露 UI 以及一个小型 API： - `GET /` 搜索 UI - `GET /api/search?q=&cat=` 排序后的 JSON 结果（带有高亮片段） - `GET /api/sources` 用于过滤标签的类别 - `GET /doc?src=&path=` 渲染文档（markdown -> HTML），带有来源横幅、 复制按钮和 Obsidian 链接/标签处理 - **build**（可选）在工具可用时运行 `mdbook`/`mkdocs` 以实现像素级完美的 浏览；索引始终读取原始 markdown，因此没有它该工具也能工作。 ## 添加你自己的文档 两者都会被 `grimoire.py index` 识别： 1. **直接放入** - 将 markdown 放入 [`custom/`](custom/) 中（作为源 `custom` 进行索引）。 2. **注册路径 / Obsidian 知识库** - 添加到 `sources.yaml`： - name: my-vault title: My Vault type: local path: /home/me/ObsidianVault category: custom ## 嵌入 RF-Swift Grimoire 是 `grimoire.py` 启动器 + `grimoire_app/` 包 + 清单 + Web 目录，没有必需的服务（标准库 `sqlite3` / `http.server`； `PyYAML` / `markdown` 为可选）。要将离线知识库 构建到镜像中：在构建时运行 `fetch` + `index`，发布 `data/index.db`（以及用于文档查看器的 `data/sources/`），然后作为运行时命令运行 `grimoire.py serve`。 ## 安全 请参阅 [docs/SECURITY.md](docs/SECURITY.md) 了解威胁模型、控制措施（参数化 SQL、CSP/XSS、路径遍历和文档扩展名白名单、工具名称和 git-URL 验证、默认关闭执行），以及在暴露 `serve` 或启用 MCP `-- assist|auto` 之前必须了解的残余风险。 ## 许可证与归属 Grimoire 自身的代码基于 **MIT License** 发布（参见 [`LICENSE`](LICENSE)）。 该许可证仅涵盖 Grimoire 本身。Grimoire 聚合并索引 第三方文档；每个源保留其自身的许可证和作者身份， 并在运行时克隆，而不是在此处重新分发。查看器中的 来源横幅会为每个文档链接回上游仓库。在重新分发之前，请审查并尊重每个项目的许可证。

标签：全文搜索, 安全知识库, 恶意代码分类, 离线工具, 逆向工具, 防御加固