aquasecurity/vex-repo-specVEX-Repository-Spezifikation
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.
Beim Vergleichen von Versionen:
Beispielvergleiche:
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.
https://<domain>/.well-known/vex-repository.json befinden.vex-repository.json MUSS im Stammverzeichnis des Hauptzweigs abgelegt werden.Das JSON-Schema für die Manifestdatei ist hier definiert.
{
"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"
}
]
}
| 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. |
| 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. |
| 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. |
Das Repository MUSS die folgende Struktur aufweisen:
vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
├── <type>/
│ ├── <namespace>/
│ │ ├── <name>/
│ │ │ └── vex.json
│ │ └── ...
│ └── ...
└── ...
Wobei <archive_extension> eines der unterstützten Archivformate ist.
Das [optional_subdirectory/] ist enthalten, wenn die URL im Feld locations mit // gefolgt von einem Unterverzeichnispfad endet. Dies ermöglicht Flexibilität bei der Repository-Struktur, insbesondere bei der Verwendung vorhandener Repository-Layouts wie denen in GitHub-Repositorys.
Wenn die URL beispielsweise https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main lautet, wäre die Dateistruktur:
main.tar.gz
└──repo-main/
├── index.json
└── pkg/
└── ...
In diesem Fall ist repo-main/ das Stammverzeichnis für das VEX-Repository innerhalb der tar.gz-Datei.
Die Datei index.json dient als Manifest für den Inhalt der Archivdatei. Sie MUSS im Stammverzeichnis des Archivs oder im angegebenen Unterverzeichnis abgelegt werden, sofern eines in der URL definiert ist. Die Datei MUSS die folgende Struktur aufweisen:
{
"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"
}
]
}
Feldbeschreibungen:
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| updated_at | ✓ | Zeitstempel, der angibt, wann diese index.json zuletzt aktualisiert wurde. |
| packages | ✓ | Array von Objekten, die jeweils ein Paket im Repository darstellen. |
| packages[].id | ✓ | Kennung des Pakets. Derzeit wird nur Package URL (PURL) akzeptiert. Version, Qualifizierer und Unterpfad MÜSSEN weggelassen werden, da sie im VEX-Dokument enthalten sind. Bei Paketen vom Typ OCI MUSS der Qualifizierer repository_url in der id enthalten sein. |
| packages[].location | ✓ | Relativer Pfad zur VEX-Datei für dieses Paket innerhalb des Archivs. Clients MÜSSEN dieses Feld verwenden, um die VEX-Dateien bestimmter Pakete zu finden. |
| packages[].format | - | Format der VEX-Daten. Entweder "openvex" oder "csaf". Wenn es weggelassen wird, wird "openvex" angenommen. |
Das Schema für die Indexdatei ist hier definiert.
Die VEX-Informationen jedes Pakets MÜSSEN in einer separaten JSON-Datei gespeichert werden, die der in der Datei index.json definierten Pfadstruktur folgt. Der Inhalt dieser Dateien MUSS der Spezifikation des VEX-Formats (OpenVEX oder CSAF VEX) entsprechen, wie im Feld format angegeben. Ein einzelnes VEX-Dokument KANN Informationen für verschiedene Versionen, Qualifizierer und Unterpfade desselben Pakets enthalten.
Beispiele für OpenVEX-Dokumente finden Sie in der OpenVEX-Spezifikation.
repository_url der PURL verwendet werden, um die Verzeichnisstruktur zu erstellen. Beispielsweise könnte ein Paket mit der PURL "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" unter "pkg/oci/docker.io/library/debian/vex.json" gespeichert werden.location der Datei index.json frei definiert werden, unabhängig von der empfohlenen Struktur.Beim Aktualisieren des VEX-Repository:
updated_at.locations-URL in der Manifestdatei (vex-repository.json) aktualisieren.Das VEX-Repository MUSS als Archivdatei verteilt werden, die die VEX-Daten und zugehörige Metadaten enthält. Dieses Archiv MUSS über das Feld locations in der Datei vex-repository.json referenziert werden und ist das primäre Mittel zur Verteilung von VEX-Informationen.
Die Archivdatei MUSS in einem der folgenden Formate vorliegen:
tar.gz und tgztar.bz2 und tbz2tar.xz und txzzipgzbz2xzBei der Auswahl einer Version aus dem versions-Array:
spec_version auswählen.Bei mehreren Standorten im locations-Array:
Clients SOLLTEN so konzipiert sein, dass sie mehrere VEX-Repositorys unterstützen.
Clients SOLLTEN den folgenden Prozess verwenden, um auf Updates zu prüfen:
update_interval aus der Datei vex-repository.json abrufen.update_interval zum lokal gespeicherten Zeitstempel addiert wird.Für einen effizienten Betrieb KÖNNEN Clients die folgenden Strategien implementieren:
update_interval sehr kurz ist.