kgateway CVE 依赖升级实战:基于 OSV-Scanner 的八阶段漏洞修复工作流
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:确定严重性范围与目标分支
连续向用户提两个简短问题:
-
严重性范围:只处理 critical/high(
--state todo),还是全部 open 严重级(--state open)?技能推荐 critical/high(与团队常规优先级一致),但阶段 1 的全景给出了完整严重级分布,用户可据此决策(例如发布前想清空v2.2.x上的 30 个 medium)。 -
规划基准分支:原始拉取是单分支的,因为规划依赖该分支的 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:执行升级
获批后按顺序执行:
- 受保护依赖门控:任何 action 为
needs approval (protected dep)的行,只有用户对该行明确说"是"才继续;不确定就再问。受保护依赖不能并入第 2 步批量执行——go get要一次一个,以便出现传递性意外时用户可以随时叫停。 - 对其余每个
go get动作执行go get <module>@<version>。 - 最后统一执行一次
go mod tidy。 - 检查意外的受保护依赖传递升级:
go mod tidy后 diffgo.mod,看是否有 envoy / k8s.io / istio.io / gateway-api 行发生变化且不在已批准计划中。有则停下、呈现给用户,由其决定(回退或批准)。 - 对每个 ignore 动作,向
osv-scanner.toml追加一个[[IgnoredVulns]]条目。reason必须具体——点名伪版本时间戳、修复发布日期与差距,禁止写 "false positive" 或 "not applicable" 这类泛化理由。永远不要为无修复 CVE 或受保护依赖 CVE 加 ignore 条目来清噪声。 - 若
go.sum有变化,运行make generate-licenses刷新许可证归属文件(对应 Makefile 的generate-licenses目标)。 - 运行
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:本地验证
用户只签收了"构建 + 扫描器复跑":
go build -tags e2e ./...——e2etag 是编译全部源码所必需的,这一点写在该仓库的 CLAUDE.md 中("rungocommands that accept-tagswith-tags e2e")。构建失败即升级不安全,停下并报告。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。
- 若 Docker 未运行,
make osv-scan会以 Docker 报错失败。告诉用户并停下——不要尝试从源码安装 osv-scanner 作为变通。
阶段 7:报告
按顺序以以下三节收尾:
- What changed(什么变了):每个获得动作的 CVE 一行——CVE、模块、from → to(或 "ignore:
")、触及的文件。用户拿着它对照 git diff阅读。 - Deferred — protected dep(受保护依赖延迟):用户拒绝(或未回应)的受保护依赖行,列出 CVE / 模块 / 提议版本 / 延迟原因,让下一位维护者有上下文。
- 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。
涉及的关键仓库文件
- .claude/skills/cve-bump/SKILL.md — 本文的完整工作流来源
- .claude/skills/cve-bump/scripts/detect_base.sh — 基准分支探测脚本
- hack/osvtool — GitHub code-scanning 告警拉取工具
- .github/workflows/osv-scanner.yaml — 分支白名单与 source/image 扫描矩阵(唯一事实来源)
- osv-scanner.toml — 误报忽略清单(含 5 条 istio.io 伪版本条目与 GO-2026-5932)
- Makefile —
osv-scan、osv-scan-latest-main-images、osv-scan-local-images、generate-licenses、fmt-changed目标 - go.mod — 直接依赖与固定版本(如
istio.io/istio v0.0.0-20260605182440-f18fd540c0e8、k8s.io/* v0.36.2、sigs.k8s.io/gateway-api v1.6.2) - CLAUDE.md —
-tags e2e构建约定 - pkg/deployer/deployer.go — 印证 GO-2026-5932 忽略理由的 Helm 导入路径