vexhub

VEX Hub ist ein zentrales Repository, das [Vulnerability Exploitability eXchange (VEX)][vex]-Dokumente aus verschiedenen Open-Source-Softwareprojekten sammelt und verwaltet. Es dient als umfassende Ressource für Schwachstelleninformationen und hilft Benutzern und Sicherheitswerkzeugen, effizient auf VEX-Daten zuzugreifen und sie über mehrere Projekte und Ökosysteme hinweg zu nutzen.

VEX Hub ruft automatisch VEX-Dokumente aus Quell-Repositories registrierter Projekte ab. Durch die Identifizierung des Quell-Repositories anhand der registrierten [Package URL (PURL)][purl] kopiert und organisiert VEX Hub die VEX-Dokumente und macht sie der breiteren Gemeinschaft leicht zugänglich.

Schnellstart: Hinzufügen von VEX-Dokumenten zu VEX Hub

1. Erstellen Sie Ihre VEX-Datei
   1. VEX Hub unterstützt die Formate [OpenVEX][openvex] oder [CSAF][csaf].
   2. Speichern Sie Ihre VEX-Dateien im .vex/-Verzeichnis im Stammverzeichnis Ihres Quellcode-Repositories. Weitere Informationen hier.
   3. Weitere Hinweise zur Erstellung von VEX-Dokumenten für VEX Hub finden Sie hier.
2. Registrieren Sie Ihr Paket bei VEX Hub
   1. Erstellen Sie einen Pull Request, der die PURL Ihres Pakets zur Datei [crawled packages][purl-list] hinzufügt.

Das war's! VEX Hub wird Ihre VEX-Dokumente automatisch abrufen und verarbeiten.

VEX-Crawling

Der [VEX Hub Crawler][vexhub-crawler] durchsucht regelmäßig VEX-Dokumente registrierter Pakete und pflegt sie in VEX Hub. Registrierte Pakete sind als eine Liste von [PURLs][purl] in [einer Datei][purl-list] definiert, die von jedem über Pull Requests aktualisiert werden kann.

Detaillierte Informationen zur PURL-Registrierung, zu unterstützten Ökosystemen und zu spezifischen Anforderungen finden Sie unter [VEX Hub Crawler][vexhub-crawler].

Identifizierung von Quell-Repositories

Die Paketdatei gibt nur die PURL des zu crawlenden Pakets an, und der VEX Hub Crawler identifiziert automatisch das Quellcode-Repository, in dem sich die VEX-Datei befindet. Die Methode zur Identifizierung von Quell-Repositories variiert je nach Ökosystem. Detaillierte Informationen darüber, wie Quell-Repositories für verschiedene Pakettypen identifiziert und gecrawlt werden, finden Sie in der Dokumentation des [vex-crawler][vexhub-crawler].

Auffinden von VEX-Dokumenten

Nach der Identifizierung des Quellcode-Repositories erkennt VEX Hub automatisch VEX-Dokumente darin. Der Erkennungsprozess umfasst die folgenden Kernpunkte:

• VEX-Dokumente werden im .vex/-Verzeichnis im Stammverzeichnis des Repositories gesucht.
• Unterstützte VEX-Formate sind OpenVEX und CSAF.
• Dateinamen, die bestimmten Mustern entsprechen (z. B. *.vex.json, *.csaf.json), werden berücksichtigt.
• Für Produkte und Unterkomponenten in den VEX-Dokumenten müssen PURLs verwendet werden.
• VEX-Dokumente, die nicht zur registrierten PURL passen, werden ignoriert.

Detaillierte Informationen zum Erkennungsprozess, zu unterstützten Ökosystemen und zu spezifischen Anforderungen finden Sie in der Dokumentation des [vex-crawler][vexhub-crawler].

Verzeichnisstruktur

VEX Hub ist basierend auf der Package URL (PURL) strukturiert, wobei version, qualifiers und subpath ausgeschlossen sind. Die Struktur folgt den folgenden Regeln:

1. Die Verzeichnishierarchie wird aus Scheme, Typ, Namespace (falls vorhanden) und Namenskomponenten der PURL abgeleitet. Im Fall von oci wird stattdessen der Qualifier repository_url verwendet.
2. Version und Qualifier werden in der Verzeichnisstruktur weggelassen. Diese Elemente müssen im Feld products der VEX-Dokumente angegeben werden.
3. Für Sonderzeichen in den PURL-Komponenten wird URL-Encoding angewendet.

Beispiele für die Bildung der Verzeichnisstruktur:

• pkg:npm/express → /npm/express/
• pkg:golang/github.com/gorilla/mux → /golang/github.com/gorilla/mux/
• pkg:maven/org.apache.xmlgraphics/batik-anim → /maven/org.apache.xmlgraphics/batik-anim/
• pkg:oci/trivy?repository_url=ghcr.io/aquasecurity/trivy → /oci/ghcr.io/aquasecurity/trivy/

Beispiel mit Kodierung von Sonderzeichen:

• pkg:npm/@angular/core → /npm/%40angular/core/

Verteilung

VEX Hub entspricht der [VEX Repository Specification][vex-repo-spec]. Die Dateien vex_repository.json und index.json können verwendet werden, um programmatisch auf VEX-Dokumente in VEX Hub zuzugreifen.

Mehrere VEX-Dokumente pro PURL

VEX Hub kann mehrere VEX-Dokumente für eine einzelne PURL speichern, da es alle passenden VEX-Dokumente aus dem Quell-Repository kopiert. Die VEX Repository Specification erlaubt jedoch nur ein VEX-Dokument pro PURL. Um dieser Spezifikation zu entsprechen, implementiert VEX Hub die folgende Verteilungsstrategie:

• Wenn mehrere VEX-Dateien für eine einzelne PURL vorhanden sind, wählt VEX Hub die erste Datei in lexikografischer Reihenfolge aus.
• Die ausgewählte Datei wird zur Verteilung in index.json geschrieben.

Erstellung von VEX-Dokumenten für VEX Hub

Um Verwirrung zu vermeiden und Konsistenz zu gewährleisten, wird nicht empfohlen, VEX-Aussagen für dieselbe PURL auf mehrere Dateien aufzuteilen, da VEX Hub nur eine VEX-Datei pro PURL verteilt.

Die empfohlenen Ansätze sind:

1. Fassen Sie VEX-Aussagen für alle Produkte, die vom Quell-Repository verwaltet werden, in einer einzigen Datei zusammen.
2. Teilen Sie VEX-Dokumente nach PURL auf.

Beispielszenario: Betrachten Sie ein Quell-Repository https://github.com/org/repo, das zwei Produkte pflegt: ein Go-Modul und ein OCi-Image.

Der erste Ansatz besteht darin, eine einzige VEX-Datei vex.json zu erstellen, die VEX-Aussagen für beide Produkte enthält.

• openvex.json: Für beide Produkte, mit den PURLs pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo und pkg:oci/repo?repository_url=ghcr.io/org/repo

Der zweite Ansatz besteht darin, separate VEX-Dateien für jedes Produkt zu erstellen.

• golang.vex: Für das Go-Modul, mit der PURL pkg:golang/github.com/org/repo
• oci.vex: Für das OCI-Image, mit den PURLs pkg:oci/repo?repository_url=docker.io/org/repo und pkg:oci/repo?repository_url=ghcr.io/org/repo

Die folgende Struktur wird nicht empfohlen:

• v1.vex: Für das Go-Modul, mit der PURL pkg:golang/github.com/org/[email protected]
• v2.vex: Für das Go-Modul, mit der PURL pkg:golang/github.com/org/[email protected]

In diesem Beispiel wird v1.vex für die Verteilung ausgewählt und v2.vex ignoriert. Sie sollten in einer einzigen VEX-Datei golang.vex mit mehreren Versionen und Qualifiern zusammengefasst werden.

Vertrauensmodell von VEX HUB

Da VEX Hub (und VEX im Allgemeinen) potenziell die Ergebnisse von Sicherheitsüberprüfungen erweitert, haben Sie das Recht, die Korrektheit der VEX-Dokumente, die Sie konsumieren, zu hinterfragen. Im Gegensatz zu anderen Vulnerability-Exchange-Feeds oder VEX-fähigen Security-Advisory-Feeds ist VEX Hub nicht die Datenquelle für VEX-Aussagen. VEX Hub aggregiert lediglich vorhandene VEX-Dokumente und organisiert sie in einem zentralen, praktischen Repository.