ValienteTechnologies/grison

# grison grison 是一个位于安全扫描器与 Ghostwriter + BookStack 之间的 markdown 枢纽。它将 扫描器导出的数据解析为单一内部标准的 markdown 发现（findings）架构，并通过 3 方向同步（3-way sync）机制，将本地的类 git 工作区与 Ghostwriter（发现，"GW"）和 BookStack（方法论）进行协调。Markdown 是通用语言——这也使得编辑该工作区的 LLM 成为了转换层，因此 grison 本身没有任何 AI 子系统；它的职责是安全地验证并同步 这些编辑。 支持的扫描器导出格式（自动检测）：Acunetix、Burp、Nessus、Nmap、OpenVAS、Qualys、 sslyze、ZAP。 ## 安装 ``` pipx install grison # or: uv tool install grison grison --help ``` 用于开发： ``` uv sync # Python 3.11+, managed with uv uv run pytest ``` ## 三个动词 | 命令 | 作用 | |---|---| | `grison parse ` | 扫描器导出文件 → `findings/inbox/` 中的 markdown 发现（离线；自动检测扫描器） | | `grison status ` | 每条记录的有效性：schema / enums / CVSS / CWE / GW HTML 白名单 | | `grison sync` | 将工作区与 Ghostwriter + BookStack 进行协调；每条记录的方向由推导得出 | 没有 `pull`/`push`（sync 会推导方向），没有 `init`（第一次 `sync` 会 初始化工作区 + 一个 `.grison/env` 凭证模板），也没有 `validate`（status 会 报告它，sync 会强制执行它）。在单元格之间移动一个发现只需简单的 `cp`/`mv`。 ## 数据模型 — 2×2 结构，精确镜像 工作区树结构*即是*模型。片段 1 = 领域（backend），片段 2 = 层级： ``` findings/ # ⇄ Ghostwriter inbox/ # parse output — local-only, triage then cp into a report library/ # ⇄ GW finding table reports/-/ # ⇄ GW reportedFinding — one dir per EXISTING report -.md evidence/*.png # images attached to a finding methodology/ # ⇄ BookStack library//.md checklists// # per-engagement copies — local-only, cp -r from library/ .grison/ # creds + state; always gitignored ``` **位置即身份。** 文件的所在目录决定了其远程目标；sync 通过 远程 id 匹配，而不是文件名（文件名仅作装饰用途）。所在位置与其 存储 id 不一致的文件属于一次*移动* → 即一条新记录 —— 这就是旧版 `instantiate`/`promote` 动词所做的一切。grison 将发现 + 证据同步至 它从未创建过的报告中。 ## 发现 markdown 架构（示例说明） 一个与层级无关的架构；结构化事实存放在 frontmatter 中，正文位于固定的 `##` 段落。 ``` --- grison: kind: finding tier: instance # library | instance gw: { table: reportedFinding, id: 183, report_id: 6 } synced: { hash: sha256:…, at: 2026-07-14T12:00:00Z } # the 3-way merge base severity: high # informational|low|medium|high|critical finding_type: web # network|physical|wireless|web|mobile|cloud|host cvss: { vector: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", score: 9.8 } cwe: ["CWE-79"] # validated against the embedded CWE index affected_entities: | # instances only https://app.example/ evidence: # instances only; images attached to this finding - { file: evidence/shell.png, caption: Shell, friendly_name: shell, gw: { id: 38, hash: sha256:… } } --- # {title} ## 描述 ## 影响 ## 缓解 ## 复现步骤 ## 参考 ``` `grison/model/` 中的 pydantic 模型**即是**架构；enums 带有它们的 Ghostwriter id（推导得出，从不存储）。CVSS 接受格式良好的 3.0 或 3.1 原始内容。 ## 转换器白名单（markdown ⇄ Ghostwriter HTML） GW 的富文本字段使用极小的封闭词汇表，转换器（`grison/markdown/`） 在遇到任何超出此范围的元素时会大声报错，而不是默默损坏数据： - 行内：`**bold**` ⇄ ``，`` `code` `` ⇄ ``，`*em*` ⇄ ``，`[文本](u)` ⇄ ``。 - 区块：段落 ⇄ `

`，`- ` 列表 ⇄ `

• `（绝不使用 `
  `）。 - 在字段中被拒绝的内容：表格、有序列表、图片、标题。`##` 段落标头是 grison 的结构，映射到 GW 的独立字段中，而不是字段内容。 （BookStack 的方法论页面是原生 markdown，因此它们逐字镜像 —— 无需转换器。） ## 同步与防护机制 方向无需选择 —— 3 方向基准（base，`synced.hash`）会*逐条记录地决定*方向： 仅本地改动 → push，仅远程改动 → pull，两者皆改动 → **碰撞**（远程数据会被 写入 `x.remote.md` 附加文件中；本地绝不会被覆盖 —— 需手动解决后执行 `sync --force-local/--force-remote `），在过时的基准下趋于一致 → 修复。 防护机制旨在阻止**异常或破坏性的结果**，绝不干涉常规操作（无 确认提示；`--dry-run` 为可选行为）。三层结构：验证（通过时静默）、 仅在异常时触发的绊线（批量更改防护、结构漂移、 碰撞、身份重复、断链），以及每次远程 写入批次前的预写入**快照**（配有对应的 `rollback.py`），确保每次写入均可逆。