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	✓

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

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

フィールド	必須	説明と使用上の注意
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"
    }
  ]
}

フィールドの説明：

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

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.json ファイルを生成する。
変更を反映するために index.json ファイルを更新する。updated_at タイムスタンプの更新も含む。
更新された内容で新しいアーカイブを作成する。
新しいアーカイブをマニフェストファイル（vex-repository.json）で指定されたロケーションにアップロードする。
必要に応じて、マニフェストファイル（vex-repository.json）の該当する locations URL を更新する。

4. リポジトリの配布

4.1 概要

VEX リポジトリは、VEX データと関連メタデータを含むアーカイブファイルとして配布しなければならない（MUST）。このアーカイブは、vex-repository.json ファイルの locations フィールドで参照されなければならず（MUST）、VEX 情報を配布する主要な手段である。

4.2 アーカイブ形式

アーカイブファイルは、以下の形式のいずれかでなければならない（MUST）：

tar.gz および tgz
tar.bz2 および tbz2
tar.xz および txz
zip
gz
bz2
xz

5. クライアント実装ガイドライン

5.1 バージョンの選択

versions 配列からバージョンを選択する場合：

クライアントは、spec_version フィールドに基づいてサポートするバージョンを選択しなければならない（MUST）。
クライアントは、セクション 1で定義された規則に従ってバージョンを比較しなければならない（MUST）。
versions 配列は古いものから新しいものへソートされていることが保証されている。クライアントはこの順序を使用して、適切なバージョンを効率的に選択できる。
v1.0 以降のバージョンの場合：
- クライアントは、同じメジャーバージョン内でサポートする最新バージョンを選択してもよい（MAY）。メジャーバージョン内では後方互換性が維持されるためである。
v0.Y バージョン（Y は任意のマイナーバージョン）の場合：
- クライアントは正確に一致するバージョンを選択すべきである（SHOULD）。
- これは、v0.Y バージョンがマイナーバージョン間で破壊的変更を含む可能性がある（MAY）ためである。
サポートされているバージョンがない場合、クライアントはリポジトリを使用してはならず（MUST NOT）、ユーザーに通知すべきである（SHOULD）。

5.2 ロケーションの選択

locations 配列内の複数のロケーションを扱う場合：

優先順位：クライアントは、配列内の順序に基づいてロケーションに優先順位を付けなければならない（MUST）。最初にリストされたロケーションは、後続のロケーションに進む前に試行されるべきである。
スキーマのサポート：
- 現在、仕様でサポートされているのは "https" スキームのみである。
- この仕様の将来のバージョンでは、追加のスキームが導入される可能性がある。
- クライアントは、各ロケーションの URL スキームを確認し、サポートされているスキームのものだけを使用すべきである（SHOULD）。
フォールバックメカニズム：クライアントがあるロケーションでエラーに遭遇した場合、配列内の次の利用可能なロケーションを使用することを試みるべきである（SHOULD）。

5.3 複数リポジトリのサポート

クライアントは、複数の VEX リポジトリをサポートするように設計されるべきである（SHOULD）。

リポジトリの優先順位付け

クライアントは、リポジトリの優先順位付けメカニズムを実装すべきである（SHOULD）。
複数のリポジトリが同じ PURL に対して VEX データを提供する場合、クライアントはリポジトリの優先順位に基づいてデータを選択すべきである（SHOULD）。
優先順位付けの方法は、ユーザーが特定のニーズやさまざまなデータソースへの信頼に基づいて調整できるように、設定可能であるべきである（SHOULD）。

5.4 更新の確認

クライアントは、更新を確認するために以下のプロセスを使用すべきである（SHOULD）：

最後に成功した更新または更新確認のタイムスタンプをローカルに保存する。
更新を検討する際は、vex-repository.json ファイルから update_interval を取得する。
ローカルに保存されたタイムスタンプに update_interval を加算して、次の更新時刻を計算する。
この計算された時刻を現在の時刻と比較する：
- 現在の時刻が計算された時刻より後の場合、更新の確認を進める：
  - 最新のリポジトリコンテンツをダウンロードするリクエストを行う。
  - 新しいコンテンツが利用可能な場合、更新されたリポジトリをダウンロードして処理する。
  - ローカルに保存されたタイムスタンプを現在の時刻で更新する。
- 現在の時刻が計算された時刻より前の場合、キャッシュされたリポジトリコンテンツを引き続き使用する。

5.5 効率化戦略

効率的な運用のために、クライアントは以下の戦略を実装してもよい（MAY）：

更新を確認するリクエストを行う際に、HTTP ETag または Last-Modified ヘッダーを使用する。これにより、コンテンツが変更されていない場合の不要なダウンロードを最小限に抑えることができる。
過剰なネットワークリクエストを避けるために、更新確認の間隔に最小値を実装する（例：1 時間）。特に update_interval が非常に短い場合に有効である。
更新確認の手動オーバーライドを許可し、計算された次の更新時刻に関係なく、ユーザーが即時の確認を強制できるようにする。

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" とみなされる。

vex-repo-spec

人気

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