kgateway CVE 依赖升级实战:基于 OSV-Scanner 的八阶段漏洞修复工作流

原创2026-10-11 20:42:321,832 阅读
文章标签:API网关云原生微服务

kgateway CVE 依赖升级实战:基于 OSV-Scanner 的八阶段漏洞修复工作流

本文面向需要在 kgateway 仓库中治理 Go 依赖 CVE 的维护者与安全工程实践者。文章完整呈现仓库内置的 cve-bump 技能所编码的端到端流程:从 GitHub code-scanning 拉取告警、逐条规划(区分真实漏洞、伪版本误报与受保护依赖)、执行 go get 升级并维护 osv-scanner.toml 忽略清单,再到用 make osv-scan 本地复扫验证与镜像目标跟进。读完你将掌握一套可复用、可提交评审、可追溯的单次闭环修复方法论。

为什么 kgateway 的 CVE 修复需要一套固定工作流

kgateway 的 CVE 治理在 .claude/skills/cve-bump/SKILL.md 中被明确描述为"比看起来更机械化,但移动部件很容易遗漏"。几个核心原因决定了不能随手 go get 一把梭:

  • 扫描结果不在本地:告警来自 GitHub code-scanning(OSV-Scanner 上传的结果),本地工作树里没有。hack/osvtool 是仓库内置的、拉取这些告警的规范工具。
  • 按分支隔离:结果按分支上传,只有 .github/workflows/osv-scanner.yaml 白名单内的分支才会被扫描(当前为 main、v2.3.x、v2.4.x)。因此主题分支必须查询其基准分支的数据。
  • 伪版本误报真实存在:OSV-Scanner 对伪版本(pseudo-version)的比较是词法级的,v0.0.0-<时间戳>-<sha> 会被判定为小于任何 1.x 修复版本,即使固定的 commit 早已包含修复。这类条目属于忽略清单而非 go.mod 变动。
  • 间接依赖的升级策略有讲究:要么 go get 拉入修复版本的父模块,要么显式加 require 强制 MVS 选择修复版本。做错了就表现为"升级没生效"。
  • 部分依赖不能乱动:Envoy 系列、k8s.io/*、istio.io/*、Gateway API 等属于"承重墙",升级可能破坏数据面、与托管 Kubernetes 版本的兼容性以及 Gateway API conformance 契约。

这套技能把这些决策点固化下来,让人只需要审批计划,而不是每次重新学习规则。

工具链:jq / yq / osvtool / make osv-scan

这是纯 Go 仓库,不内置 Python 工具链,也不假设贡献者装了 Python。SKILL.md 明确要求所有解析、过滤、整形任务一律使用:

  • jq 处理 JSON,hack/osvtool 本身就依赖它;
  • yq 处理 YAML,可用 yq -p=yaml -o=json 把 osvtool 输出的 YAML 转回 JSON 交给 jq;
  • go、make 与标准 shell 内建命令。

严禁引入 python、node、ruby 或 pip/npm install。SKILL.md 给出的一个实用起点是把保存的 YAML 告警文件还原成 JSON 数组并开始过滤:

yq -p=yaml -o=json /tmp/cve-bump/alerts-<branch>-<ts>.yaml \
  | jq '[ .[] | {
      ghsa: .rule.id,
      sev:  .rule.security_severity_level,
      msg:  .most_recent_instance.message.text,
      help: .rule.help,
      url:  .html_url
    } ]'

CVE ID 通常出现在 rule.full_description 或 message 文本(与包名、版本号同现),help 字段则包含 GO-XXXX-XXXX 公告表与修复版本。提取用 jq 的 capture/正则辅助或 sed/grep 管道即可。

hack/osvtool:拉取 GitHub code-scanning 告警

hack/osvtool 是仓库内置的 shell 脚本,封装了对 GitHub code-scanning API 的分页拉取、权限探测与告警整形。从源码看,其主要参数为:

参数 取值 含义
--branch <branch> 可重复 查询的分支;缺省时读取 OSV workflow 的白名单
--repo <owner/repo> 默认 kgateway-dev/kgateway 查询的仓库
--state <state> open / fixed / dismissed / todo todo = 仅 open 中 critical/high
--target <target> all / source / image source = osv-scanner 的依赖发现;image = osv-image-scanner 的容器镜像发现
--raw — 输出原始告警 YAML(单分支为告警序列,多分支为按分支映射)
--worst — 输出跨分支最高严重级;任一分支最近扫描缺失或超过 72 小时则非零退出
--table — 紧凑 markdown 表格(每分支一行)
--workflow <path> 默认 .github/workflows/osv-scanner.yaml 用于发现默认分支的 workflow 文件
-h/--help — 帮助文本

从 osvtool 源码 可以看到它在 main 入口强制 require_cmd gh、require_cmd jq、require_cmd yq,三者缺一不可;--raw、--worst、--table 互斥。另外它会在拉取前做一次 repo 级 code-scanning 权限探测,失败时会输出完整的诊断与修复指引(如 gh auth refresh --scopes security_events 或带 Code scanning alerts: Read-only 权限的 fine-grained PAT),SKILL.md 要求直接把这段帮助文本原样呈现给用户,不要掩盖。

make osv-scan:本地复扫的唯一入口

本地验证阶段不允许直接调用 osv-scanner,必须走 Makefile 中的 osv-scan 目标。从源码看这个目标:

  • 用 Docker 运行 ghcr.io/google/osv-scanner-action:v2.3.5(由 OSV_SCANNER_IMAGE 变量指定),因此本地不需要装 osv-scanner 二进制;
  • 源码扫描使用 scan source,并带 --no-call-analysis=go、--no-call-analysis=rust、-r ./;
  • 结果写到 _output/osv/<safe-branch>/results.json 与同目录 results.sarif;<safe-branch> 是把当前分支中的 /、. 替换为 -;
  • 若设置了 OSV_SCAN_IMAGES,还会对每个镜像依次 skopeo copy/docker pull + docker save 后执行 scan image --archive --config=/workspace/osv-scanner.toml,输出落在 _output/osv/<safe-branch>/images/;
  • 结束时用容器内的 chown 把输出目录所有权归还当前用户。

Makefile 还提供两个镜像扫描快捷目标:osv-scan-latest-main-images(对滚动 main 镜像 kgateway、sds、envoy-wrapper 扫描)和 osv-scan-local-images(先构建当前分支镜像再扫描)。注意 make osv-scan 在任意分支都可用(因为它是本地扫描),这与 osvtool 只能查有 GitHub 上传结果的分支不同。

阶段 1:跨分支扫描全景(landscape)

任何规划之前,先用表格模式把两个 target 的结果并排展示,让用户同时看到 source 与 image 的发现。不带 --branch 时 osvtool 恰好扫描 OSV workflow 白名单内的分支,所以当 LTS 分支被裁剪或退役时这个命令不会失效:

# Source 目标的全景(本技能规划的输入)
./hack/osvtool --table --target source --state open

# Image 目标的全景(阶段 8 会再看)
./hack/osvtool --table --target image --state open

每次调用输出一个紧凑 markdown 表格:每分支一行,列为 branch | C | H | M | L | max age | last scan | code-scanning(分别对应 critical/high/medium/low 计数、最大告警年龄、最近扫描时间与 code-scanning 链接)。源码中这个表格由 emit_table 生成(hack/osvtool#L470-L524)。

这里刻意用 --state open 而非 todo,是为了让 medium/low 计数可见——用户马上要决定是否纳入它们,应先看到数字。不要用默认的 YAML summary 模式:每分支约 60 行嵌套字段,用户不需要。若确实想要完整结构化形式,重定向到 /tmp/cve-bump/ 下的文件而不是贴进聊天。

阶段 2:确定严重性范围与目标分支

连续向用户提两个简短问题:

  1. 严重性范围:只处理 critical/high(--state todo),还是全部 open 严重级(--state open)?技能推荐 critical/high(与团队常规优先级一致),但阶段 1 的全景给出了完整严重级分布,用户可据此决策(例如发布前想清空 v2.2.x 上的 30 个 medium)。

  2. 规划基准分支:原始拉取是单分支的,因为规划依赖该分支的 go.mod 状态。运行辅助脚本求默认值:

    .claude/skills/cve-bump/scripts/detect_base.sh
    

    从 detect_base.sh 的源码可以看到它的策略:从 OSV 扫描 workflow 的白名单解析候选分支(通过 sed 提取 branches='["main","v2.3.x","v2.4.x"]' 这一行的 JSON 数组),逐个与当前 HEAD 求 merge-base,选 merge-base commit 最新者;若 HEAD 已在候选分支上则直接输出该分支;无法判定时回退到 main。它打印一行分支名,用户确认:"Planning against <X>. OK, or pick another?"

若阶段 1 在所选分支、所选严重级上的告警数为零,立即停下告知用户——没有可规划的内容。

阶段 3:拉取原始告警

./hack/osvtool --raw --branch <branch> --target source --state <state>

<state> 是阶段 2 用户选择的 todo 或 open。

关键约束:

  • --target source 把本轮过滤到 Go-mod 发现。镜像发现因动作不同(Dockerfile / 基础镜像 / apk 修改)且很多会在 source 升级落地后被传递性消除,放到阶段 8 单独处理,不要在同一张表里规划。
  • 输出是 YAML。保存到仓库之外的临时路径以免误提交,规范路径为 /tmp/cve-bump/alerts-<branch>-<UTC-timestamp>.yaml(先 mkdir -p)。这既给用户留下记录,也避免为复解析再打一次 GitHub 请求。

若 osvtool 报认证错误,原样呈现它打印的帮助文本即可(如 gh auth refresh --scopes security_events 或 fine-grained PAT 的 security_events 权限),不要自行绕过。

阶段 4:逐条规划与决策树

对每条告警提取:

  • CVE ID(rule.id 通常是 GHSA;CVE 在 rule.full_description 或 most_recent_instance.message.text);
  • 严重级(rule.security_severity_level);
  • 受影响的 Go 模块与当前固定版本;
  • 修复版本(公告中解决该公告的最低版本),可能缺失——见下方"无修复"分支;
  • 该模块在仓库 go.mod 中是 direct 还是 indirect;
  • 是否为受保护依赖。

然后按决策树选动作:

flowchart TD
    A[Finding] --> N{公告里有没有<br/>修复版本?}
    N -- 没有 --> NF[仅报告:<br/>加入 "no fix available" 列表]
    N -- 有 --> P{是受保护依赖吗<br/>envoy / k8s.io/* / istio.io/* / gateway-api?}
    P -- 是 --> PA[需要批准:<br/>计划中标记 "needs approval protected dep"<br/>不并入批量 go get]
    P -- 否 --> B{考虑伪版本后,<br/>固定版本是否已 >= 修复版本?}
    B -- 是 --> C[误报 → 加入 osv-scanner.toml]
    B -- 否 --> D{在 go.mod 中是 direct 吗?}
    D -- 是 --> E[go get module@fixed-version]
    D -- 否 --> F{有单个父依赖<br/>独占这个传递依赖吗?}
    F -- 有且升级它合理 --> G[go get parent@能拉入修复的版本]
    F -- 没有, 或父依赖升级太冒险 --> H[显式 require<br/>go get module@fixed-version<br/>强制 MVS 选择修复]

伪版本误报的检测

当受影响版本形如 v0.0.0-<14位时间戳>-<sha> 而修复版本是 1.x 这样的常规 semver 时,OSV-Scanner 按词法比较 "0.0.0" < "1.x",不管固定的 commit 是否已包含修复都会报警。做法是:读取伪版本内嵌的时间戳,与修复发布日期比较;若固定 commit 更新,即为误报——加入 osv-scanner.toml,reason 必须点名时间戳、修复发布日期与年份/月份差。

osv-scanner.toml 中现存的五个 istio.io 条目就是标准模板。例如:

[[IgnoredVulns]]
id = "CVE-2022-31045"
reason = "False positive: fixed in Istio 1.12.18 / 1.13.5 / 1.14.1. At the time this entry was added our pin v0.0.0-20260605182440-f18fd540c0e8 was an Istio 1.31-dev build"

对照 go.mod,istio.io/istio 当前确实固定在 v0.0.0-20260605182440-f18fd540c0e8,注释说明了其 VERSION 文件读取为 1.31,比所有修复(2019–2022 年的 Istio 1.x 发布)晚出多个 minor。文件头部还写明:只有无歧义的误报才能进忽略清单,每条必须解释"为什么是误报",供未来读者复核。

osv-scanner.toml 中另有一条非版本类条目:GO-2026-5932 是 golang.org/x/crypto/openpgp 的"设计上永修"(won't-fix)公告,没有修复版本会发布。该包只经由 Helm 的 chart 签名校验路径链接进 kgateway(pkg/deployer → helm.sh/helm/v3/pkg/action → helm.sh/helm/v3/pkg/provenance)。从 pkg/deployer/deployer.go 的导入可见它只用 Helm 的 action、chart、storage、storage/driver 包,进程内渲染内嵌 chart,从不启用 provenance 校验或配置 keyring,因此运行时不可达。注释里还给出了复核命令:

go list -deps -tags e2e ./... | grep x/crypto/openpgp
grep -rn 'provenance\|Keyring\|Verify' pkg/deployer/

父依赖升级与显式 require 的选择

优先父依赖升级,当且仅当:(a) 父依赖本身只落后一个小版本/patch 版本;(b) 其 changelog 未标注对我们用法有破坏性变更。否则走显式 require——这是最小干预,Go 的 MVS 会尊重它。

计划输出:最多三张表

1. 可执行升级——你打算 go get 或 ignore 的对象。列:CVE | severity | module | from → to | action。

| CVE             | sev | module                | from           | to        | action                |
| --------------- | --- | --------------------- | -------------- | --------- | --------------------- |
| CVE-2025-1111   | H   | golang.org/x/net      | v0.20.0        | v0.27.0   | go get (direct)       |
| CVE-2025-2222   | M   | gopkg.in/foo.v3       | v3.1.0         | v3.2.1    | explicit require      |
| CVE-2022-31045  | H   | istio.io/istio        | v0.0.0-2026... | (n/a)     | ignore: false pos     |

2. 需要批准——受保护依赖(空则省略)。列:CVE | severity | module | from → to | reason。用户必须逐行说"是",任何一行都不能进入批量 go get。

| CVE             | sev | module                  | from     | to       | reason                  |
| --------------- | --- | ----------------------- | -------- | -------- | ----------------------- |
| CVE-2025-9999   | H   | k8s.io/apimachinery     | v0.31.2  | v0.31.5  | only fix is a k8s.io bump |

3. 无修复可用(空则省略)。列:CVE | severity | module | pinned | advisory。只读,不提出任何动作,最终报告中原样复述。

| CVE             | sev | module                | pinned    | advisory                                        |
| --------------- | --- | --------------------- | --------- | ----------------------------------------------- |
| CVE-2025-7777   | M   | example.com/foo       | v1.4.0    | https://github.com/advisories/GHSA-xxxx-yyyy-zz |

(第三列的 advisory URL 为占位示例,实际应填公告页地址。)

然后请用户:确认可执行表、逐行决定受保护依赖、知悉无修复列表。在拿到明确批准前不碰任何文件。

受保护依赖的完整边界

以下依赖属于"承重墙",没有对话中明确的口头同意就绝不升级,即使 CVE 是 critical:

  • github.com/envoyproxy/*(Envoy 与 go-control-plane)
  • k8s.io/*(api、apimachinery、client-go 等)
  • istio.io/*
  • sigs.k8s.io/gateway-api 及其他 Gateway API 模块

关键子规则:若父依赖的传递升级会通过 MVS 把受保护依赖拉上新版本,这也算升级受保护依赖——需要在父升级后用 go list -m -json <module> 检测并回报用户。绝不允许用 osv-scanner.toml 忽略受保护依赖的 CVE 来回避询问——忽略清单只服务于误报。

无上游修复的 CVE

OSV-Scanner 有时会报出尚无修复版本(或上游已撤回)的公告。禁止:固定到 fork 或个人补丁、仅为了清告警而加 ignore 条目、编造公告中未声明的"缓解措施"。正确做法是把它们收集进阶段 4 的 "no fix available" 列表,并在阶段 7 报告中原样呈现:CVE / 严重级 / 模块 / 固定版本 / 公告 URL。它们是被跟踪的,而非被修复的。

阶段 5:执行升级

获批后按顺序执行:

  1. 受保护依赖门控:任何 action 为 needs approval (protected dep) 的行,只有用户对该行明确说"是"才继续;不确定就再问。受保护依赖不能并入第 2 步批量执行——go get 要一次一个,以便出现传递性意外时用户可以随时叫停。
  2. 对其余每个 go get 动作执行 go get <module>@<version>。
  3. 最后统一执行一次 go mod tidy。
  4. 检查意外的受保护依赖传递升级:go mod tidy 后 diff go.mod,看是否有 envoy / k8s.io / istio.io / gateway-api 行发生变化且不在已批准计划中。有则停下、呈现给用户,由其决定(回退或批准)。
  5. 对每个 ignore 动作,向 osv-scanner.toml 追加一个 [[IgnoredVulns]] 条目。reason 必须具体——点名伪版本时间戳、修复发布日期与差距,禁止写 "false positive" 或 "not applicable" 这类泛化理由。永远不要为无修复 CVE 或受保护依赖 CVE 加 ignore 条目来清噪声。
  6. 若 go.sum 有变化,运行 make generate-licenses 刷新许可证归属文件(对应 Makefile 的 generate-licenses 目标)。
  7. 运行 make fmt-changed 保持 diff 整洁(见 Makefile)。

不 stage(git add)、不 commit,脏工作树交给用户自行审查。

关于手改 go.mod 与重型 codegen,技能有明确禁令:永远经由 go get(保持 go.sum 一致),绝不手改 go.mod;依赖升级不需要 make generate-all 等重型 codegen 目标(非 API 变更用不到,且白白拖慢约 30 秒)。

阶段 6:本地验证

用户只签收了"构建 + 扫描器复跑":

  1. go build -tags e2e ./... —— e2e tag 是编译全部源码所必需的,这一点写在该仓库的 CLAUDE.md 中("run go commands that accept -tags with -tags e2e")。构建失败即升级不安全,停下并报告。
  2. make osv-scan —— 仓库内本地跑 OSV-Scanner 的规范方式。它壳到 Docker(镜像 ghcr.io/google/osv-scanner-action:v2.3.5),无需本地 osv-scanner 二进制。不要直接调用独立的 osv-scanner 命令。结果落在 _output/osv/<safe-branch>/results.json(及 SARIF 兄弟文件)。
    • make osv-scan 的 JSON schema 是 osv-scanner 原生格式(results[].packages[].vulnerabilities[].id),与阶段 3 的 GitHub code-scanning YAML 结构不同。对比时用 jq/yq 分别提取两侧的 vuln ID 集合再比较集合,不要逐字段对齐记录。报告两类信息:用户预期清除但仍在的 CVE;扫描器新发现、原计划中未出现的 CVE。
  3. 若 Docker 未运行,make osv-scan 会以 Docker 报错失败。告诉用户并停下——不要尝试从源码安装 osv-scanner 作为变通。

阶段 7:报告

按顺序以以下三节收尾:

  1. What changed(什么变了):每个获得动作的 CVE 一行——CVE、模块、from → to(或 "ignore: ")、触及的文件。用户拿着它对照 git diff 阅读。
  2. Deferred — protected dep(受保护依赖延迟):用户拒绝(或未回应)的受保护依赖行,列出 CVE / 模块 / 提议版本 / 延迟原因,让下一位维护者有上下文。
  3. No fix available:原样复述阶段 4 表格——CVE / 严重级 / 模块 / 固定版本 / 公告 URL。不提议变通方案,不为这些条目加 osv-scanner.toml。

阶段 8:镜像目标跟进

source 升级落地后,镜像发现往往会被传递性解决(例如打进镜像的 Go 二进制随之获得修复依赖),但 base-image CVE 与 apk 包需要 Dockerfile 或基础镜像改动,不会自动消失。

对规划分支刷新镜像全景:

./hack/osvtool --table \
    --branch <branch> \
    --target image --state open

然后询问用户:"The source bumps are done. Image findings above remain on the published scan — most should clear once these bumps ship, but base-image / apk CVEs need a Dockerfile change. Want to plan that now, or defer?"

必须向用户言明两点:

  • --table 视图反映的是上次 GitHub 上传的扫描,不是工作树。刚做的 source 升级要等 CI 重建并重新发布结果后才会反映到镜像扫描中。
  • 本地镜像扫描(make osv-scan OSV_SCAN_IMAGES="<image-ref> ...",参见 Makefile 中 osv-scan-latest-main-images 对滚动 main 镜像的规范调用)扫描的是已构建并发布的镜像,不是刚升级的工作树。用户问"为什么修复了的 CVE 本地还在"时说明这一点。

用户说 "defer" 就到此为止;说 "go" 则把镜像流当作独立规划轮次——从 Dockerfile 级动作开始新计划(不要往 Go-mod 计划里塞镜像动作,它们在不同文件里,且上面的决策树不适用)。

值得知道的边界情况

  • 修复侧也是伪版本:罕见但确实存在——修复只存在于未打 tag 的 commit,此时 go get module@<sha> 可行。在计划里明确标注,避免用户对 go.mod 里出现伪版本感到意外。
  • 模块改名/迁移:若公告的模块路径在上游已不存在,可能需要 replace 指令。这应视为有歧义,提交给用户裁决而不是默默写入 replace。
  • 同一模块多个 CVE:合并成单次 go get,升到所需最高版本。计划表里分行列出,但 action 列标注 "(combined bump)"。
  • 回移植分支:扫描 v2.2.x 等分支时,某模块可接受的升级窗口可能更窄(例如不能跨大版本)。默认在同一 major 内选择解决 CVE 的最小版本。
  • 主题分支在基准分支上无告警:分支刚 rebase 过、紧跟在一次近期扫描之后时可能出现。告知用户,并提议等 CI 上传新结果后重跑。
  • 基线分支的 go.mod 状态是规划前提:原始拉取必须单分支进行,因为后续的决策树判断(direct/indirect、伪版本、父依赖归属)全部依赖该分支的 go.mod。

红线清单(Things not to do)

以下禁令直接来自 SKILL.md,实践时应逐条遵守:

  • 不 commit / 不 stage,由用户完成。
  • 不手改 go.mod,一律走 go get 保证 go.sum 一致。
  • 不批量升级受保护依赖,更不做传递性拉入;呈现给用户、等待批准。
  • 不为无修复 CVE 编造变通方案:不固定到 fork、不用 osv-scanner.toml 静音,列入 no-fix 桶继续。
  • 不在 source 升级后停下:阶段 8 的镜像跟进是流程组成部分,每次都要提示用户剩余镜像发现。
  • 不为清噪声加 osv-scanner.toml 条目:reason 字段要能向未来读者自证。
  • 不跑 make generate-all 等重型 codegen:非 API 变更不需要,纯属拖慢循环。
  • 不直接扫描无上传结果的分支(如个人功能分支)——osvtool 查不到数据;本地验证 make osv-scan 例外,它任意分支都能跑。
  • 不引入 Python/Node 等解析器:一律 jq/yq。
  • 不直接调用 osv-scanner:用 make osv-scan(Docker 内运行,带正确配置与输出路径)。
  • 不用默认 YAML summary 做跨分支全景:用 ./hack/osvtool --table——一小张 markdown 表格胜过几十行嵌套 YAML。

涉及的关键仓库文件

登录后查看全文
kgateway