企业官网建设流程全解析

kube-state-metrics 的 OpenVEX 漏洞披露数据：从模板文件到发布自动化的完整机制

【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics

本篇基于 kube-state-metrics 仓库中的 .openvex/templates/README.md 及其配套文件展开。kube-state-metrics 作为 Kubernetes 生态的组件，遵循了 OpenVEX（VEX 的一种精简 JSON-LD 实现）这一供应链安全数据格式，用于向下游用户公开声明项目对特定漏洞的官方影响结论。读完本文后，你将掌握 OpenVEX 模板文件的字段含义、发布时 VEX 文档的自动生成与上传流程，以及如何用 vexctl 为项目追加一条新的漏洞影响声明。

一、.openvex/templates目录的定位

仓库中.openvex/templates/README.md对该目录的定位说明如下：

This directory contains the OpenVEX data for this repository. The files stored in this directory are used as templates byvexctl generatewhen generating VEX data for a release or a specific artifact.

这段话包含两个关键信息：

1. 该目录存放的就是本仓库的 OpenVEX 数据，即项目对漏洞影响的持久化声明记录；
2. 目录下的文件是模板（templates），由vexctl generate命令在"生成某个发布版本或某个具体构件（artifact）的 VEX 数据"时作为输入使用。

当前目录内容很简单，只有两个文件：

• .openvex/templates/README.md：说明文档；
• .openvex/templates/main.openvex.json：模板文件本体，是vexctl add命令的实际操作对象。

这种"模板进仓库 + 发布时生成"的模式意味着：维护者通过 Pull Request 把漏洞结论提交进模板文件（可评审、可追溯），而面向用户的最终 VEX 文档则在发布时刻由工具从模板衍生出来，二者职责分离。

二、模板文件main.openvex.json逐字段解析

.openvex/templates/main.openvex.json 的完整内容如下：

{ "@context": "https://openvex.dev/ns/v0.2.0", "@id": "https://openvex.dev/docs/public/vex-2912204db7d51d98234a931d600f7cc2dd0bf24a5b5b326de138d64b30c22911", "author": "vexctl (automated template)", "timestamp": "2023-12-15T22:55:18.754525+05:30", "version": 1, "statements": [] }

各字段含义：

statements是整份文档的"数据主体"：README 中介绍的vexctl add命令所做的，就是往这个数组中追加一条 statement（包含受影响的 PURL、漏洞编号、影响结论等）。目前数组为空，意味着模板处于"干净基线"状态——发布时生成的 VEX 文档在未有人工提交声明之前，同样不含任何 statement。

三、发布时的自动化生成流程：openvex.yml

模板如何变成随发布交付的最终 VEX 文档？答案是 GitHub Actions 工作流 .github/workflows/openvex.yml。逐段解析：

触发条件

on: workflow_dispatch: release: types: - released

两种触发方式：workflow_dispatch（在 GitHub 页面上手动触发，便于调试）和release事件中的released（Release 正式创建时自动触发）。这与 README 所说的 "cutting a new release" 场景一一对应。

权限最小化

permissions: contents: read # workflow 级默认只读 jobs: vexctl: permissions: contents: write # 仅在需要的 job 内提升为可写

顶层权限只读，只有vexctl这个 job（因为要执行 Release 上传）在 job 级别提升为contents: write，是典型的按需授权写法。

版本号与环境准备

- name: Set environment variables run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV

${GITHUB_REF#refs/*/}是 shell 参数展开，把refs/tags/vX.Y.Z这类引用剥掉前缀，得到纯版本号（如v2.13.0），供后续步骤使用。checkout 步骤也使用了按 commit SHA 钉死的actions/checkout@3d3c42e5...（v7.0.1），避免供应链层面的引用漂移。

核心步骤：运行 vexctl 生成 VEX 文档

- uses: openvex/generate-vex@c59881b41451d7ccba5c3b74cd195382b8971fcd name: Run vexctl with: product: pkg:golang/k8s.io/kube-state-metrics/v2@${{ env.RELEASE_VERSION }} file: kube-state-metrics.openvex.json

该步骤封装了vexctl generate，两个关键入参：

• product：本次生成所针对的产品 PURL，格式为pkg:golang/k8s.io/kube-state-metrics/v2@<版本>——包类型是 Golang module，命名空间为k8s.io，主版本段v2显式写进 PURL（Go module 的 v2+ 版本按语义化导入版本规范必须携带），版本部分由RELEASE_VERSION填充；
• file：输出文件名kube-state-metrics.openvex.json。

工具会以仓库中的.openvex/templates/模板为输入，把其中已提交的 statements 合并进来，生成面向该 Release 的最终 VEX 文档。工作流中有一行注释# Refer: .../vexctl#operational-model，指向 vexctl 官方的"操作模型"文档，即本节所描述的"模板 → 生成"协作方式。

上传到 GitHub Release

- name: Upload OpenVEX document to GitHub Release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | gh release upload ${{ env.RELEASE_VERSION }} kube-state-metrics.openvex.json

生成的kube-state-metrics.openvex.json通过gh release upload作为 Release 资产上传。最终效果是：下游用户拉取某个版本的 kube-state-metrics 时，可以在同一个 Release 页面下载到与版本严格对应的 VEX 文档，用工具（消费 VEX 的安全平台、依赖治理工具等）核对项目对该版本已知漏洞的官方立场。

综合起来，整条链路是：人工提交 statement 到.openvex/templates/（可评审）→ 发布时vexctl generate以模板为输入、以 Release PURL 为目标生成文档 → 文档作为 Release 资产分发。这正是 README 中 "the new file will be incorporated to the release's VEX data" 一句在仓库中的具体落地。

四、用vexctl add追加一条新的 VEX 声明

当项目确认了某个漏洞对自身发布产物的实际影响后，需要把它记录为一条 statement。README 给出的标准操作如下：

1. 先安装 vexctl（具体安装方式参见 vexctl 官方文档与示例仓库）；
2. 对模板文件执行vexctl add：

vexctl add --in-place main.openvex.json pkg:oci/test CVE-2014-1234567 fixed

参数拆解：

执行后，statements数组中会追加一条对应 statement，描述"该漏洞在此 PURL 产物上的影响是 fixed"。README 还提示：下一次切版本发布时，pkg:oci/test对应的这份新文件内容会被合并进该 Release 的 VEX 数据——即声明通过模板持久化，随发布自动生效。

需要提醒的是：README 中的命令是教学示例（pkg:oci/test与CVE-2014-1234567均为占位值），真实提交流程应使用项目实际的 PURL 与真实漏洞编号，并以 Pull Request 形式提交模板变更，保证可评审、可追溯。

五、与项目安全流程的衔接

OpenVEX 机制并非孤立存在，它与仓库中的其他安全设施相互配套：

• SECURITY.md 声明了漏洞报告流程：kube-state-metrics 遵循 Kubernetes 的安全披露流程（Kubernetes Security and Disclosure Information），漏洞公告通过kubernetes-security-announce邮件组发布，支持的版本范围以 Kubernetes 官方的版本支持策略为准。也就是说：上游漏洞的"发现与报告"走 Kubernetes 披露流程，而项目对这些漏洞"影响结论的公开表达"则由 OpenVEX 文档承载；
• 从 .github/workflows/ 目录可以看到，除 openvex.yml 外还有govulncheck.yml与sbom.yaml两个工作流，从命名可推断分别对应 Go 依赖漏洞检查与 SBOM 生成。三者组合起来构成一个完整的供应链安全数据面：SBOM 回答"这个版本包含哪些组件"，漏洞扫描回答"其中已知存在哪些漏洞"，OpenVEX 则回答"项目对每个漏洞的官方结论是什么"（已修复 / 不受影响 / 调查中）。

六、使用时的注意事项

1. statements为空是正常状态：当前 .openvex/templates/main.openvex.json 中statements: []，说明截至仓库当前提交，尚无已提交的人工漏洞声明；此时发布生成的 VEX 文档同样只含空声明集，不代表机制缺失。
2. 模板与发布文档是两个文档：模板的@id是模板自身的规范标识；从源码结构看，vexctl generate针对pkg:golang/k8s.io/kube-state-metrics/v2@<version>生成 Release 文档时，会以该产品 PURL 和版本为语境产出最终文档，二者不应混淆。
3. 版本号语义：文档中的version字段用于追踪文档内容的更新次数；若通过vexctl add修改了 statements，最终交付文档的版本演进以工具生成的 Release 文档为准。
4. PURL 书写规范：本项目产品 PURL 采用pkg:golang/k8s.io/kube-state-metrics/v2@<版本>形式，v2是 Go module 主版本段的规范要求，引用或校验该文档时务必保留。

七、关键文件索引

通过上述文件，可以完整复现 kube-state-metrics 从"提交漏洞影响声明"到"随 Release 交付 VEX 文档"的全流程，也可以照此模式为其他遵循 OpenVEX 规范的组件建立自己的漏洞披露数据管线。

【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics