VEX 仓库规范 v0.1

• VEX 仓库规范 v0.1
  • 1. 版本管理
  • 2. 仓库清单
    • 2.1 概述
    • 2.2 文件位置
    • 2.3 模式
    • 2.4 示例
    • 2.5 字段说明与使用说明
      • 主要字段
      • 版本子字段
      • 位置子字段
  • 3. 仓库结构
    • 3.1 文件结构
    • 3.2 index.json
    • 3.3 VEX 文档
    • 3.4 使用说明
      • 目录结构
      • VEX 文档内容
    • 3.5 更新仓库
  • 4. 仓库分发
    • 4.1 概述
    • 4.2 归档格式
  • 5. 客户端实现指南
    • 5.1 版本选择
    • 5.2 位置选择
    • 5.3 多仓库支持
      • 仓库优先级
    • 5.4 检查更新
    • 5.5 效率策略

本文档中的关键词 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"MAY" 和 "OPTIONAL" 应按照 RFC 2119 中的描述进行解释。

1. 版本管理

• VEX（Vulnerability Exploitability eXchange）仓库规范必须使用 vX.Y 进行版本编号。
• 对于 v1.0 及更高版本：
  • X（主版本号）必须针对破坏性变更进行更新。
  • Y（次版本号）必须针对向后兼容的变更进行更新。
• 对于 v0.Y 版本，破坏性变更可以随次版本号更新而出现。

比较版本时：

• 版本必须按数字进行比较，而不是按字典顺序。
• 必须首先比较主版本号：
  • 如果主版本号不同，则主版本号较高的版本视为较新版本。
  • 如果主版本号相同，则继续比较次版本号。
• 仅当主版本号相同时，才比较次版本号：
  • 次版本号较高的版本视为较新版本。

比较示例：

• 1.0 < 2.0
• 1.1 < 1.2
• 1.10 > 1.2

2. 仓库清单

2.1 概述

清单文件提供关于 VEX 数据仓库的元数据。 该文件必须包含获取和更新 VEX 数据所需的信息。

2.2 文件位置

• 对于 HTTPS：清单文件必须位于 https://<domain>/.well-known/vex-repository.json
• 对于 GitHub 仓库：vex-repository.json 必须放置在 main 分支的根目录中。

2.3 模式

清单文件的 JSON 模式定义在此处。

2.4 示例

{
  "name": "Example Org VEX Repository",
  "description": "VEX repository for Example Organization",
  "versions": [
    {
      "spec_version": "0.1",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
        }
      ],
      "update_interval": "24h",
      "repository_specific": {
        "location": {
          "repository_type": "db",
          "db_type": "bbolt",
          "url": "oci://ghcr.io/example.com/vex-db:0"
        }
      }
    },
    {
      "spec_version": "1.0",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
        },
        {
          "url": "https://example.com/vex-api/v1"
        }
      ],
      "update_interval": "1h"
    }
  ]
}

2.5 字段说明与使用说明

主要字段

版本子字段

位置子字段

3. 仓库结构

3.1 文件结构

仓库必须具有以下结构：

vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
    ├── <type>/
    │   ├── <namespace>/
    │   │   ├── <name>/
    │   │   │   └── vex.json
    │   │   └── ...
    │   └── ...
    └── ...

其中 <archive_extension> 是支持的归档格式之一。

当 locations 字段中的 URL 以 // 加子目录路径结尾时，将包含 [optional_subdirectory/]。 这为仓库结构提供了灵活性，特别是在使用现有仓库布局（如 GitHub 仓库中的布局）时。

例如，如果 URL 为 https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main，则文件结构为：

main.tar.gz
└──repo-main/
   ├── index.json
   └── pkg/
       └── ...

在这种情况下，repo-main/ 是 tar.gz 文件内 VEX 仓库的根目录。

3.2 index.json

index.json 文件用作归档文件内容的清单。 它必须放置在归档文件的根目录中，或者如果 URL 中定义了子目录，则放置在该指定子目录中。 该文件必须具有以下结构：

{
  "updated_at": "2023-07-04T12:00:00Z",
  "packages": [
    {
      "id": "pkg:deb/debian/curl",
      "location": "pkg/deb/debian/curl/vex.json"
    },
    {
      "id": "pkg:npm/lodash",
      "location": "pkg/npm/lodash/vex.json",
      "format": "csaf"
    }
  ]
}

字段说明：

索引文件的模式定义在此处。

3.3 VEX 文档

每个软件包的 VEX 信息必须存储在单独的 JSON 文件中，并遵循 index.json 文件中定义的路径结构。这些文件的内容必须符合 format 字段中指定的 VEX 格式规范（OpenVEX 或 CSAF VEX）。 单个 VEX 文档可以包含同一软件包的不同版本、限定符和子路径的信息。

有关 OpenVEX 文档示例，请参阅 OpenVEX 规范。

3.4 使用说明

目录结构

• 建议根据软件包的 PURL（不包括版本、限定符和子路径）来创建目录结构。例如，PURL 为 "pkg:deb/debian/curl" 的软件包可以存储在 "pkg/deb/debian/curl/vex.json" 中。
• 对于 OCI 软件包，可以使用 PURL 的 repository_url 限定符来创建目录结构。例如，PURL 为 "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" 的软件包可以存储在 "pkg/oci/docker.io/library/debian/vex.json" 中。
• VEX 文件的实际位置可以在 index.json 文件的 location 字段中自由定义，无论建议的结构如何。
• 无论操作系统如何，归档中的所有文件路径都必须使用正斜杠（/）作为分隔符。
• 如果目录结构中的软件包名称包含特殊字符，则必须对其进行 URL 编码。

VEX 文档内容

• 单个 VEX 文档可以包含同一软件包的不同版本、限定符和子路径的信息。
• 在查询特定版本、限定符或子路径时，客户端必须解析整个 VEX 文档以找到相关信息。

3.5 更新仓库

更新 VEX 仓库时：

1. 为受影响的软件包生成新的或更新的 vex.json 文件。
2. 更新 index.json 文件以反映所有更改，包括更新 updated_at 时间戳。
3. 使用更新后的内容创建新的归档文件。
4. 将新的归档文件上传到清单文件（vex-repository.json）中指定的位置。
5. 如有必要，更新清单文件（vex-repository.json）中相关的 locations URL。

4. 仓库分发

4.1 概述

VEX 仓库必须以包含 VEX 数据和相关元数据的归档文件的形式分发。 该归档文件必须由 vex-repository.json 文件中的 locations 字段引用，并且是分发 VEX 信息的主要方式。

4.2 归档格式

归档文件必须是以下格式之一：

• tar.gz 和 tgz
• tar.bz2 和 tbz2
• tar.xz 和 txz
• zip
• gz
• bz2
• xz

5. 客户端实现指南

5.1 版本选择

从 versions 数组中选择版本时：

• 客户端必须根据 spec_version 字段选择其支持的版本。
• 客户端必须按照第 1 节中定义的规则比较版本。
• versions 数组保证按从最旧到最新的顺序排序。客户端可以利用此顺序有效地选择合适的版本。
• 对于 v1.0 及更高版本：
  • 客户端可以选择同一主版本号内所支持的最新版本，因为主版本号内保持向后兼容。
• 对于 v0.Y 版本（其中 Y 为任意次版本号）：
  • 客户端应该选择完全匹配的版本。
  • 这是因为 v0.Y 版本在次版本号之间可能包含破坏性变更。
• 如果没有可用的受支持版本，客户端不得使用该仓库，并且应该通知用户。

5.2 位置选择

处理 locations 数组中的多个位置时：

1. 优先级顺序：客户端必须根据位置在数组中的顺序确定优先级。 应首先尝试列表中列出的第一个位置，然后再尝试后续位置。
2. 模式支持：
   • 目前，规范中仅支持 "https" 协议。
   • 本规范的未来版本可能会引入其他协议。
   • 客户端应该检查每个位置的 URL 协议，并且只使用具有受支持协议的位置。
3. 回退机制：如果客户端在某个位置遇到错误，它应该尝试使用数组中的下一个可用位置。

5.3 多仓库支持

客户端应该设计为支持多个 VEX 仓库。

仓库优先级

• 客户端应该为仓库实现优先级机制。
• 当多个仓库为同一 PURL 提供 VEX 数据时，客户端应该根据仓库优先级选择数据。
• 优先级方法应该是可配置的，以允许用户根据其特定需求和对不同数据源的信任程度进行调整。

5.4 检查更新

客户端应该使用以下过程检查更新：

1. 在本地存储上次成功更新或更新检查的时间戳。
2. 在考虑更新时，从 vex-repository.json 文件中获取 update_interval。
3. 通过将 update_interval 添加到本地存储的时间戳来计算下次更新时间。
4. 将此计算出的时间与当前时间进行比较：
   • 如果当前时间晚于计算出的时间，则继续检查更新：
     • 发出请求以下载最新的仓库内容。
     • 如果有新内容可用，则下载并处理更新后的仓库。
     • 使用当前时间更新本地存储的时间戳。
   • 如果当前时间早于计算出的时间，则继续使用缓存的仓库内容。

5.5 效率策略

为了提高运行效率，客户端可以实施以下策略：

1. 在发出请求检查更新时，使用 HTTP ETag 或 Last-Modified 标头。当内容未更改时，这有助于最大限度地减少不必要的下载。
2. 在更新检查之间设置最小间隔（例如 1 小时），以避免过多的网络请求，尤其是在 update_interval 很短的情况下。
3. 允许手动覆盖更新检查，使用户无论计算出的下次更新时间如何，都能强制立即检查。