vexhub

VEX Hub 是一个集中式仓库，用于收集和管理来自各种开源软件项目的漏洞可利用性交换（VEX）文档。 它作为漏洞信息的综合资源，帮助用户和安全工具跨多个项目和生态系统高效访问和利用 VEX 数据。

VEX Hub 会自动从已注册项目的源代码仓库中检索 VEX 文档。 通过从已注册的软件包 URL（PURL）中识别源代码仓库，VEX Hub 会复制并组织 VEX 文档，使其便于更广泛的社区访问。

快速入门：向 VEX Hub 添加 VEX 文档

1. 创建您的 VEX 文件
   1. VEX Hub 支持 OpenVEX 或 CSAF 格式。
   2. 将您的 VEX 文件存储在源代码仓库根目录下的 .vex/ 目录中。更多信息请参见此处。
   3. 关于为 VEX Hub 创建 VEX 文档的更多指导，请参见此处。
2. 向 VEX Hub 注册您的软件包
   1. 提交一个 Pull Request，将您软件包的 PURL 添加到已爬取软件包文件中。

就这么简单！ VEX Hub 会自动检索并处理您的 VEX 文档。

VEX 爬取

VEX Hub Crawler 会定期爬取已注册软件包的 VEX 文档，并将其维护在 VEX Hub 中。 已注册软件包定义为文件中的 PURL 列表，任何人都可以通过 Pull Request 更新该文件。

有关 PURL 注册、支持的生态系统和具体要求的详细信息，请参阅 VEX Hub Crawler。

识别源代码仓库

软件包文件仅指定要爬取的软件包的 PURL，VEX Hub Crawler 会自动识别 VEX 文件所在的源代码仓库。 识别源代码仓库的方法因生态系统而异。有关如何针对不同软件包类型识别和爬取源代码仓库的详细信息，请参阅 vex-crawler 文档。

发现 VEX 文档

识别源代码仓库后，VEX Hub 会自动发现其中的 VEX 文档。发现过程包括以下关键点：

• 在仓库根目录的 .vex/ 目录中搜索 VEX 文档。
• 支持的 VEX 格式为 OpenVEX 和 CSAF。
• 匹配特定模式的文件名（例如 *.vex.json、*.csaf.json）会被纳入考虑。
• VEX 文档中的产品和子组件必须使用 PURL。
• 与已注册 PURL 不匹配的 VEX 文档将被忽略。

有关发现过程、支持的生态系统和具体要求的详细信息，请参阅 vex-crawler 文档。

目录结构

VEX Hub 基于软件包 URL（PURL）组织，排除了 version、qualifiers 和 subpath。 该结构遵循以下规则：

1. 目录层级源自 PURL 的 scheme、type、namespace（如有）和 name 组件。对于 oci，使用 repository_url 限定符代替。
2. 目录结构中省略版本和限定符。这些元素必须在 VEX 文档的 products 字段中指定。
3. 对 PURL 组件中的特殊字符应用 URL 编码。

目录结构示例：

• pkg:npm/express → /npm/express/
• pkg:golang/github.com/gorilla/mux → /golang/github.com/gorilla/mux/
• pkg:maven/org.apache.xmlgraphics/batik-anim → /maven/org.apache.xmlgraphics/batik-anim/
• pkg:oci/trivy?repository_url=ghcr.io/aquasecurity/trivy → /oci/ghcr.io/aquasecurity/trivy/

特殊字符编码示例：

• pkg:npm/@angular/core → /npm/%40angular/core/

分发

VEX Hub 遵循 VEX 仓库规范。可以使用 vex_repository.json 和 index.json 文件以编程方式访问 VEX Hub 中的 VEX 文档。

每个 PURL 有多个 VEX 文档

VEX Hub 能够为一个 PURL 存储多个 VEX 文档，因为它会从源代码仓库中复制所有匹配的 VEX 文档。 但 VEX 仓库规范只允许每个 PURL 对应一个 VEX 文档。 为符合该规范，VEX Hub 实施了以下分发策略：

• 当单个 PURL 存在多个 VEX 文件时，VEX Hub 会按字典顺序选择第一个文件。
• 将选中的文件写入 index.json 进行分发。

为 VEX Hub 创建 VEX 文档

为避免混淆并确保一致性，不建议将同一 PURL 的 VEX 语句拆分成多个文件，因为 VEX Hub 每个 PURL 仅分发一个 VEX 文件。

推荐做法：

1. 将源代码仓库所管理的所有产品的 VEX 语句合并到一个文件中。
2. 按 PURL 拆分 VEX 文档。

示例场景： 假设源代码仓库 https://github.com/org/repo 维护两个产品：一个 Go 模块和一个 OCI 镜像。

第一种方法是创建一个包含两个产品 VEX 语句的单个 VEX 文件 vex.json。

• openvex.json：用于两个产品，PURL 为 pkg:golang/github.com/org/repo、pkg:oci/repo?repository_url=docker.io/org/repo 和 pkg:oci/repo?repository_url=ghcr.io/org/repo

第二种方法是为每个产品创建单独的 VEX 文件。

• golang.vex：用于 Go 模块，PURL 为 pkg:golang/github.com/org/repo
• oci.vex：用于 OCI 镜像，PURL 为 pkg:oci/repo?repository_url=docker.io/org/repo 和 pkg:oci/repo?repository_url=ghcr.io/org/repo

不建议采用以下结构：

• v1.vex：用于 Go 模块，PURL 为 pkg:golang/github.com/org/[email protected]
• v2.vex：用于 Go 模块，PURL 为 pkg:golang/github.com/org/[email protected]

在此示例中，v1.vex 会被选中用于分发，而 v2.vex 会被忽略。 它们应合并为单个 VEX 文件 golang.vex，包含多个版本和限定符。

VEX Hub 信任模型

由于 VEX Hub（以及广义上的 VEX）可能会增强安全扫描结果，您理应严格审查所消费的 VEX 文档的正确性。与其他漏洞交换源或支持 VEX 的安全公告源不同，VEX Hub 不是 VEX 语句的数据来源。VEX Hub 仅聚合现有 VEX 文档，并将其组织成一个集中、便捷的仓库。

要出现在 VEX Hub 中，VEX 文档首先需要提交到主软件包的源代码仓库中。这种方法基于一个事实：作为用户，您必须已经信任您所使用的软件包，因此也信任其维护者、治理体系以及他们采用的过程。每个项目都有自己的治理体系和向源代码仓库提交内容的流程。那些让包代码在您眼中值得信赖的系统和流程，也正是让 VEX 文档值得您信赖的系统和流程。 您对 VEX Hub 的信任程度，不应超过您对所选择使用的软件包的信任程度。

VEX Hub 对其持有的 VEX 文档内容或其所描述的软件包不承担任何责任，也不了解相关内容。VEX Hub 维护者不会审查或核验 VEX 文档的内容，信息的准确性和正确性由来源软件包维护者负责。我们建议用户像手动分类其他漏洞一样，对抑制的漏洞进行手动分类。

故障排查

如果已注册 PURL 的源代码仓库中的 VEX 文档未在 VEX Hub 中正确更新，请检查以下各项：

1. 确保 VEX 文档放在正确的位置（仓库根目录下的 .vex/ 目录）。
2. 验证 VEX 文档使用受支持的文件命名约定之一。
3. 确认 VEX 文档中的 PURL 与 VEX Hub 中注册的 PURL 匹配。
4. 查阅 vexhub-crawler 文档，确保满足所有爬取规范。

如果确认这些要点后问题仍然存在，请在 VEX Hub 仓库中提交 issue 以获取进一步帮助。

贡献

欢迎贡献以改进 VEX Hub！ 请注意，软件包列表及相关代码维护在 VEX Hub Crawler 仓库 中。 不鼓励直接向本仓库提交添加 VEX 文档的 Pull Request。 本项目及其所有参与者受 Aqua Security 行为准则 约束。