vexhub

VEX Hub est un référentiel centralisé qui collecte et gère les documents Vulnerability Exploitability eXchange (VEX) de divers projets logiciels open source. Il constitue une ressource complète d'informations sur les vulnérabilités, aidant les utilisateurs et les outils de sécurité à accéder efficacement aux données VEX et à les utiliser dans plusieurs projets et écosystèmes.

VEX Hub récupère automatiquement les documents VEX depuis les dépôts sources des projets enregistrés. En identifiant le dépôt source à partir du Package URL (PURL) enregistré, VEX Hub copie et organise les documents VEX, les rendant facilement accessibles à la communauté dans son ensemble.

Guide de démarrage rapide : Ajout de documents VEX à VEX Hub

1. Créez votre fichier VEX
   1. VEX Hub prend en charge les formats OpenVEX ou CSAF.
   2. Stockez vos fichiers VEX dans votre dépôt de code source, dans le répertoire .vex/ à la racine de votre dépôt. Plus d'informations ici.
   3. Pour des conseils supplémentaires sur la création de documents VEX pour VEX Hub, consultez ici.
2. Enregistrez votre paquet auprès de VEX Hub
   1. Créez une Pull Request qui ajoute le PURL de votre paquet au fichier des paquets explorés.

Et voilà ! VEX Hub récupérera et traitera automatiquement vos documents VEX.

Exploration de VEX

VEX Hub Crawler explore périodiquement les documents VEX des paquets enregistrés et les maintient dans VEX Hub. Les paquets enregistrés sont définis comme une liste de PURL dans un fichier qui peut être mis à jour par n'importe qui via des Pull Requests.

Pour des informations détaillées sur l'enregistrement des PURL, les écosystèmes pris en charge et les exigences spécifiques, veuillez vous référer à VEX Hub Crawler.

Identification des dépôts sources

Le fichier des paquets spécifie uniquement le PURL du paquet à explorer, et VEX Hub Crawler identifie automatiquement le dépôt de code source où se trouve le fichier VEX. La méthode d'identification des dépôts sources varie selon l'écosystème. Pour des informations détaillées sur la façon dont les dépôts sources sont identifiés et explorés pour les différents types de paquets, veuillez vous référer à la documentation du vex-crawler.

Découverte des documents VEX

Après avoir identifié le dépôt de code source, VEX Hub découvre automatiquement les documents VEX qui s'y trouvent. Le processus de découverte comprend les points clés suivants :

• Les documents VEX sont recherchés dans le répertoire .vex/ à la racine du dépôt.
• Les formats VEX pris en charge sont OpenVEX et CSAF.
• Les noms de fichiers correspondant à des motifs spécifiques (par ex., *.vex.json, *.csaf.json) sont pris en compte.
• Les PURL doivent être utilisés pour les produits et les sous-composants dans les documents VEX.
• Les documents VEX qui ne correspondent pas au PURL enregistré sont ignorés.

Pour des informations détaillées sur le processus de découverte, les écosystèmes pris en charge et les exigences spécifiques, veuillez vous référer à la documentation du vex-crawler.

Structure des répertoires

VEX Hub est structuré en fonction du Package URL (PURL), à l'exclusion de version, qualifiers et subpath. La structure respecte les règles suivantes :

1. La hiérarchie des répertoires est dérivée des composants scheme, type, namespace (s'il est présent) et name du PURL. Dans le cas de oci, le qualificateur repository_url est utilisé à la place.
2. La version et les qualificateurs sont omis de la structure des répertoires. Ces éléments doivent être spécifiés dans le champ products des documents VEX.
3. L'encodage URL est appliqué aux caractères spéciaux des composants du PURL.

Exemples de formation de la structure des répertoires :

• 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/

Exemple avec encodage de caractères spéciaux :

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

Distribution

VEX Hub est conforme à la spécification du référentiel VEX. Les fichiers vex_repository.json et index.json peuvent être utilisés pour accéder par programmation aux documents VEX de VEX Hub.

Documents VEX multiples par PURL

VEX Hub a la capacité de stocker plusieurs documents VEX pour un seul PURL, car il copie tous les documents VEX correspondants du dépôt source. Cependant, la spécification du référentiel VEX n'autorise qu'un seul document VEX par PURL. Pour se conformer à cette spécification, VEX Hub met en œuvre la stratégie de distribution suivante :

• Lorsque plusieurs fichiers VEX existent pour un seul PURL, VEX Hub sélectionne le premier fichier dans l'ordre lexicographique.
• Écrit le fichier sélectionné dans index.json pour la distribution.

Création de documents VEX pour VEX Hub

Pour éviter toute confusion et garantir la cohérence, il n'est pas recommandé de répartir les déclarations VEX pour le même PURL dans plusieurs fichiers, car VEX Hub ne distribue qu'un seul fichier VEX par PURL.

Les approches recommandées sont :

1. Regroupez les déclarations VEX pour tous les produits gérés par le dépôt source dans un seul fichier.
2. Divisez les documents VEX par PURL.

Exemple de scénario : Considérons un dépôt source https://github.com/org/repo qui gère deux produits : un module Go et une image OCi.

La première approche consiste à créer un seul fichier VEX, vex.json, contenant les déclarations VEX pour les deux produits.

• openvex.json : Pour les deux produits, avec les PURL pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo et pkg:oci/repo?repository_url=ghcr.io/org/repo

La deuxième approche consiste à créer des fichiers VEX séparés pour chaque produit.

• golang.vex : Pour le module Go, avec le PURL pkg:golang/github.com/org/repo
• oci.vex : Pour l'image OCI, avec les PURL pkg:oci/repo?repository_url=docker.io/org/repo et pkg:oci/repo?repository_url=ghcr.io/org/repo

La structure suivante n'est pas recommandée :

• v1.vex : Pour le module Go, avec le PURL pkg:golang/github.com/org/[email protected]
• v2.vex : Pour le module Go, avec le PURL pkg:golang/github.com/org/[email protected]

Dans cet exemple, v1.vex est sélectionné pour la distribution et v2.vex est ignoré. Ils doivent être combinés en un seul fichier VEX, golang.vex, avec plusieurs versions et qualificateurs.

Modèle de confiance de VEX HUB

Étant donné que VEX Hub (et VEX en général) peut potentiellement compléter les résultats des analyses de sécurité, vous êtes en droit d'examiner attentivement l'exactitude des documents VEX que vous consommez. Contrairement à d'autres flux d'échange de vulnérabilités ou aux flux d'avis de sécurité compatibles VEX, VEX Hub n'est pas la source des données des déclarations VEX. VEX Hub se contente d'agréger les documents VEX existants et de les organiser dans un référentiel central et pratique.

Pour apparaître dans VEX Hub, les documents VEX doivent d'abord être validés dans le dépôt de code source du paquet principal. Cette approche s'appuie sur le fait qu'en tant qu'utilisateur, vous devez déjà faire confiance aux paquets que vous utilisez, et donc aux mainteneurs, à la gouvernance et aux processus qu'ils emploient. Chaque projet a son propre système de gouvernance et ses propres processus de validation dans le dépôt de code source. Ces systèmes et processus qui rendent le code des paquets digne de confiance à vos yeux sont les mêmes systèmes et processus qui rendent les documents VEX dignes de confiance pour vous. Vous ne devriez pas faire plus confiance à VEX Hub qu'aux paquets que vous choisissez d'utiliser.

VEX Hub n'a aucune responsabilité ni connaissance quant au contenu des documents VEX qu'il héberge ou des paquets qu'ils décrivent. Les mainteneurs de VEX Hub ne révisent ni ne contrôlent le contenu des documents VEX, et la responsabilité de l'exactitude et de la justesse des informations incombe aux mainteneurs des paquets d'origine. Nous recommandons aux utilisateurs de trier manuellement les vulnérabilités supprimées de la même manière qu'ils trieraient toute autre vulnérabilité.

Dépannage

Si les documents VEX du dépôt source d'un PURL enregistré ne sont pas mis à jour correctement dans VEX Hub, veuillez vérifier les points suivants :

1. Assurez-vous que les documents VEX sont placés au bon endroit (répertoire .vex/ à la racine du dépôt).
2. Vérifiez que les documents VEX utilisent l'une des conventions de nommage de fichiers prises en charge.
3. Confirmez que le PURL du document VEX correspond au PURL enregistré dans VEX Hub.
4. Consultez la documentation du vexhub-crawler pour vous assurer que toutes les spécifications d'exploration sont respectées.

Si les problèmes persistent après avoir vérifié ces points, veuillez ouvrir une issue dans le dépôt VEX Hub pour obtenir de l'aide.

Contribuer

Les contributions visant à améliorer VEX Hub sont les bienvenues ! Veuillez noter que la liste des paquets et le code associé sont maintenus dans le dépôt VEX Hub Crawler. Les Pull Requests ajoutant directement des documents VEX à ce dépôt sont déconseillées. Ce projet et toutes les personnes qui y participent sont régis par le Code de conduite Aqua Security.