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 バージョニングを使用しなければならない（MUST）。
v1.0 以降の場合：
- X（メジャーバージョン）は、破壊的変更がある場合に更新しなければならない（MUST）。
- Y（マイナーバージョン）は、後方互換性のある変更の場合に更新しなければならない（MUST）。
v0.Y バージョンの場合、破壊的変更はマイナーバージョンの更新に伴って発生してもよい（MAY）。

バージョンを比較する場合：

バージョンは、辞書順ではなく数値で比較しなければならない（MUST）。
メジャーバージョンを最初に比較しなければならない（MUST）：
- メジャーバージョンが異なる場合、メジャーバージョンが大きい方が新しいバージョンとみなされる。
- メジャーバージョンが等しい場合は、マイナーバージョンの比較に進む。
マイナーバージョンの比較は、メジャーバージョンが等しい場合にのみ行わなければならない（MUST）：
- マイナーバージョンが大きい方が新しいバージョンとみなされる。

比較の例：

1.0 < 2.0
1.1 < 1.2
1.10 > 1.2

2. リポジトリマニフェスト

2.1 概要

マニフェストファイルは、VEX データリポジトリに関するメタデータを提供する。このファイルには、VEX データの取得と更新に必要な情報が含まれていなければならない（MUST）。

2.2 ファイルの場所

HTTPS の場合：マニフェストファイルは https://<domain>/.well-known/vex-repository.json に配置しなければならない（MUST）。
GitHub リポジトリの場合：vex-repository.json はメインブランチのルートディレクトリに配置しなければならない（MUST）。

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 リポジトリ仕様のバージョンを実装するバージョンを表す。バージョンは古いものから新しいものへ昇順にソートされなければならない（MUST）。サブフィールドについては別表を参照。

バージョンサブフィールド

フィールド	必須	説明と使用上の注意
spec_version	✓	実装されている VEX リポジトリ仕様のバージョン（例："0.1"）。形式はセクション 1で定義されているとおり "X.Y" でなければならない（MUST）。
locations	✓	VEX データのロケーションを記述するオブジェクトの配列。少なくとも 1 つのロケーションオブジェクトを含まなければならない（MUST）。サブフィールドについては別表を参照。
update_interval	✓	このバージョンの VEX データに対する推奨される更新確認間隔。Go の duration 形式を使用する（例："1h"、"30m"、"24h"）。
repository_specific	-	リポジトリ固有の追加情報。

ロケーションサブフィールド

フィールド	必須	説明と使用上の注意
url	✓	VEX データのロケーションの URL。"https://" で始まる。コンテンツはセクション 3および4のリポジトリ構造の仕様に準拠する。URL には、'//' に続けてサブディレクトリパスを付加することで、サブディレクトリの指定を含めることができる。

3. リポジトリ構造

3.1 ファイル構造

リポジトリは以下の構造でなければならない（MUST）：

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

ここで <archive_extension> は、サポートされているアーカイブ形式のいずれかである。

[optional_subdirectory/] は、locations フィールドの URL が // に続くサブディレクトリパスで終わる場合に含まれる。これにより、特に 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 でサブディレクトリが定義されている場合はその指定されたサブディレクトリに配置しなければならない（MUST）。このファイルは以下の構造でなければならない（MUST）：

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

フィールドの説明：

フィールド	必須	説明
updated_at	✓	この index.json が最後に更新された日時を示すタイムスタンプ。
packages	✓	オブジェクトの配列。各オブジェクトはリポジトリ内のパッケージを表す。
packages[].id	✓	パッケージの識別子。現時点では Package URL（PURL）のみが受け入れられる。バージョン、クォリファイア、サブパスは VEX ドキュメントに含まれるため、省略しなければならない（MUST）。OCI タイプのパッケージの場合、`repository_url` クォリファイアを id に含めなければならない（MUST）。
packages[].location	✓	アーカイブ内のこのパッケージの VEX ファイルへの相対パス。クライアントは、特定のパッケージの VEX ファイルを特定するためにこのフィールドを使用しなければならない（MUST）。
packages[].format	-	VEX データの形式。"openvex" または "csaf" のいずれか。省略された場合は "openvex" とみなされる。

インデックスファイルのスキーマはこちらで定義されている。

3.3 VEX ドキュメント

各パッケージの VEX 情報は、index.json ファイルで定義されたパス構造に従って、個別の JSON ファイルに格納しなければならない（MUST）。これらのファイルの内容は、format フィールドで指定された VEX 形式仕様（OpenVEX または CSAF VEX）に準拠しなければならない（MUST）。単一の VEX ドキュメントには、同じパッケージの異なるバージョン、クォリファイア、サブパスの情報を含めてもよい（MAY）。

OpenVEX ドキュメントの例については、OpenVEX 仕様を参照のこと。

3.4 使用上の注意

ディレクトリ構造

パッケージのディレクトリ構造は、バージョン、クォリファイア、サブパスを除いた PURL に基づいて作成することが推奨される（RECOMMENDED）。例えば、PURL が "pkg:deb/debian/curl" のパッケージは、"pkg/deb/debian/curl/vex.json" に格納できる。
OCI パッケージの場合、PURL の repository_url クォリファイアをディレクトリ構造の作成に使用してもよい（MAY）。例えば、PURL が "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" のパッケージは、"pkg/oci/docker.io/library/debian/vex.json" に格納できる。
VEX ファイルの実際の場所は、推奨される構造に関係なく、index.json ファイルの location フィールドで自由に定義してもよい（MAY）。
アーカイブ内のすべてのファイルパスは、オペレーティングシステムに関係なく、区切り文字としてスラッシュ（/）を使用しなければならない（MUST）。
ディレクトリ構造内のパッケージ名は、特殊文字を含む場合、URL エンコードされなければならない（MUST）。

VEX ドキュメントの内容

単一の VEX ドキュメントには、同じパッケージの異なるバージョン、クォリファイア、サブパスの情報を含めてもよい（MAY）。
特定のバージョン、クォリファイア、サブパスを照会する場合、クライアントは関連情報を見つけるために VEX ドキュメント全体を解析しなければならない（MUST）。

3.5 リポジトリの更新

VEX リポジトリを更新する場合：

vex-repo-spec

人気