VEX 仓库规范 v0.1

VEX 仓库规范 v0.1

本文档中的关键词 "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 字段说明与使用说明

主要字段

字段	必填	说明与使用说明
name	✓	仓库的名称。
description	✓	仓库的简要描述。
versions	✓	包含可用版本详细信息的数组。数组中的每个对象代表一个实现某个 VEX 仓库规范版本的版本。版本必须按升序排列，从最旧到最新。子字段请参阅单独的表格。

版本子字段

字段	必填	说明与使用说明
spec_version	✓	所实现的 VEX 仓库规范的版本（例如 "0.1"）。格式必须为第 1 节中定义的 "X.Y"。
locations	✓	描述 VEX 数据位置的对象数组。必须至少包含一个位置对象。子字段请参阅单独的表格。
update_interval	✓	该版本 VEX 数据的推荐更新检查间隔。使用 Go 持续时间格式（例如 "1h"、"30m"、"24h"）。
repository_specific	-	额外的仓库特定信息。

位置子字段

字段	必填	说明与使用说明
url	✓	VEX 数据位置的 URL，以 "https://" 开头。内容遵循第 3 节和第 4 节中的仓库结构规范。URL 可以通过附加 '//' 后跟子目录路径来指定子目录。

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"
    }
  ]
}

字段说明：

vex-repo-spec

最受欢迎