vexhub

VEX Hub ist ein zentrales Repository, das Vulnerability Exploitability eXchange (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) 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 oder 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 hinzufügt.

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

VEX-Crawling

Der VEX Hub Crawler durchsucht regelmäßig VEX-Dokumente registrierter Pakete und pflegt sie in VEX Hub. Registrierte Pakete sind als eine Liste von PURLs in einer Datei 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.

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.

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.

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. 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.

Damit VEX-Dokumente in VEX Hub erscheinen, müssen sie zuerst in das Quellcode-Repository des Hauptpakets eingebracht werden. Dieser Ansatz stützt sich auf die Tatsache, dass Sie als Benutzer den Paketen, die Sie verwenden, bereits vertrauen müssen und damit auch den Betreuern, den Governance-Strukturen und den Prozessen, die sie einsetzen. Jedes Projekt hat sein eigenes Governance-System und seine eigenen Prozesse für das Einbringen von Änderungen in das Quellcode-Repository. Dieselben Systeme und Prozesse, die den Paketcode in Ihren Augen vertrauenswürdig machen, sind die gleichen Systeme und Prozesse, die die VEX-Dokumente für Sie vertrauenswürdig machen. Sie sollten VEX Hub nicht mehr vertrauen als den Paketen, die Sie zu verwenden wählen.

VEX Hub hat keinerlei Verantwortung oder Kenntnis über den Inhalt der VEX-Dokumente, die es speichert, oder der Pakete, die sie beschreiben. Die VEX-Hub-Betreuer überprüfen oder prüfen den Inhalt der VEX-Dokumente nicht, und die Verantwortung für die Genauigkeit und Richtigkeit der Informationen liegt bei den ursprünglichen Paketbetreuern. Wir empfehlen Benutzern, unterdrückte Schwachstellen manuell zu sichten, ähnlich wie sie jede andere Schwachstelle sichten würden.

Fehlerbehebung

Wenn VEX-Dokumente im Quell-Repository einer registrierten PURL in VEX Hub nicht ordnungsgemäß aktualisiert werden, überprüfen Sie bitte Folgendes:

1. Stellen Sie sicher, dass die VEX-Dokumente am richtigen Ort abgelegt sind (.vex/-Verzeichnis im Stammverzeichnis des Repositories).
2. Überprüfen Sie, ob die VEX-Dokumente eine der unterstützten Dateinamenskonventionen verwenden.
3. Bestätigen Sie, dass die PURL im VEX-Dokument mit der in VEX Hub registrierten PURL übereinstimmt.
4. Lesen Sie die Dokumentation des vexhub-crawler, um sicherzustellen, dass alle Spezifikationen für das Crawling erfüllt sind.

Wenn Probleme nach der Überprüfung dieser Punkte weiterhin bestehen, eröffnen Sie bitte ein Issue im VEX-Hub-Repository, um weitere Unterstützung zu erhalten.

Mitwirken

Beiträge zur Verbesserung von VEX Hub sind willkommen! Bitte beachten Sie, dass die Paketliste und der zugehörige Code im VEX Hub Crawler-Repository gepflegt werden. Pull Requests, die diesem Repository direkt VEX-Dokumente hinzufügen, sind nicht erwünscht. Dieses Projekt und alle, die daran teilnehmen, unterliegen dem Aqua Security Code of Conduct.