VEX-Repository-Spezifikation v0.1

• VEX-Repository-Spezifikation v0.1
  • 1. Versionierung
  • 2. Repository-Manifest
    • 2.1 Übersicht
    • 2.2 Dateispeicherort
    • 2.3 Schema
    • 2.4 Beispiel
    • 2.5 Feldbeschreibungen und Verwendungshinweise
      • Hauptfelder
      • Unterfelder der Versionen
      • Unterfelder der Standorte
  • 3. Repository-Struktur
    • 3.1 Dateistruktur
    • 3.2 index.json
    • 3.3 VEX-Dokumente
    • 3.4 Verwendungshinweise
      • Verzeichnisstruktur
      • Inhalt der VEX-Dokumente
    • 3.5 Aktualisieren des Repository
  • 4. Verteilung des Repository
    • 4.1 Übersicht
    • 4.2 Archivformat
  • 5. Richtlinien für die Client-Implementierung
    • 5.1 Auswahl der Version
    • 5.2 Auswahl des Standorts
    • 5.3 Unterstützung mehrerer Repositorys
      • Priorisierung der Repositorys
    • 5.4 Prüfung auf Updates
    • 5.5 Effizienzstrategien

Die Schlüsselwörter "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" und "OPTIONAL" in diesem Dokument sind wie in RFC 2119 beschrieben zu interpretieren.

1. Versionierung

• Die VEX-Repository-Spezifikation (Vulnerability Exploitability eXchange) MUSS die Versionierung vX.Y verwenden.
• Für v1.0 und später:
  • X (Hauptversion) MUSS bei inkompatiblen Änderungen aktualisiert werden.
  • Y (Nebenversion) MUSS bei abwärtskompatiblen Änderungen aktualisiert werden.
• Bei v0.Y-Versionen KÖNNEN inkompatible Änderungen bei Updates der Nebenversion auftreten.

Beim Vergleichen von Versionen:

• Versionen MÜSSEN numerisch und nicht lexikografisch verglichen werden.
• Hauptversionen MÜSSEN zuerst verglichen werden:
  • Wenn sich die Hauptversionen unterscheiden, gilt die Version mit der höheren Hauptversion als neuer.
  • Wenn die Hauptversionen gleich sind, werden die Nebenversionen verglichen.
• Nebenversionen MÜSSEN nur verglichen werden, wenn die Hauptversionen gleich sind:
  • Die Version mit der höheren Nebenversion gilt als neuer.

Beispielvergleiche:

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

2. Repository-Manifest

2.1 Übersicht

Die Manifestdatei stellt Metadaten über ein VEX-Datenrepository bereit. Diese Datei MUSS die Informationen enthalten, die zum Abrufen und Aktualisieren von VEX-Daten erforderlich sind.

2.2 Dateispeicherort

• Für HTTPS: Die Manifestdatei MUSS sich unter https://<domain>/.well-known/vex-repository.json befinden.
• Für GitHub-Repositorys: vex-repository.json MUSS im Stammverzeichnis des Hauptzweigs abgelegt werden.

2.3 Schema

Das JSON-Schema für die Manifestdatei ist hier definiert.

2.4 Beispiel

{
  "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 Feldbeschreibungen und Verwendungshinweise

Hauptfelder

Feld	Erforderlich	Beschreibung und Verwendungshinweise
name	✓	Der Name des Repository.
description	✓	Eine kurze Beschreibung des Repository.
versions	✓	Ein Array mit Details zu den verfügbaren Versionen. Jedes Objekt im Array repräsentiert eine Version, die eine Version der VEX-Repository-Spezifikation implementiert. Versionen MÜSSEN in aufsteigender Reihenfolge sortiert sein, von der ältesten zur neuesten Version. Siehe separate Tabelle für Unterfelder.

Unterfelder der Versionen

Feld	Erforderlich	Beschreibung und Verwendungshinweise
spec_version	✓	Die Version der implementierten VEX-Repository-Spezifikation (z. B. "0.1"). Das Format MUSS "X.Y" sein, wie in Abschnitt 1 definiert.
locations	✓	Ein Array von Objekten, die VEX-Datenspeicherorte beschreiben. MUSS mindestens ein Standortobjekt enthalten. Siehe separate Tabelle für Unterfelder.
update_interval	✓	Das empfohlene Intervall für die Aktualisierungsprüfung der VEX-Daten dieser Version. Verwendet das Go-Dauernformat (z. B. "1h", "30m", "24h").
repository_specific	-	Zusätzliche repository-spezifische Informationen.

Unterfelder der Standorte

Feld	Erforderlich	Beschreibung und Verwendungshinweise
url	✓	Eine URL für den VEX-Datenspeicherort, die mit "https://" beginnt. Der Inhalt entspricht den Spezifikationen zur Repository-Struktur in Abschnitt 3 und 4. Die URL kann eine Unterverzeichnisangabe enthalten, indem '//' gefolgt vom Unterverzeichnispfad angehängt wird.

3. Repository-Struktur

3.1 Dateistruktur