vexhub

VEX Hub è un repository centralizzato che raccoglie e gestisce documenti Vulnerability Exploitability eXchange (VEX) provenienti da vari progetti open-source. Funge da risorsa completa per le informazioni sulle vulnerabilità, aiutando utenti e strumenti di sicurezza ad accedere e utilizzare in modo efficiente i dati VEX attraverso più progetti ed ecosistemi.

VEX Hub recupera automaticamente i documenti VEX dai repository sorgente dei progetti registrati. Identificando il repository sorgente a partire dal Package URL (PURL) registrato, VEX Hub copia e organizza i documenti VEX, rendendoli facilmente accessibili alla comunità.

Avvio rapido: aggiunta di documenti VEX a VEX Hub

1. Crea il tuo file VEX
   1. VEX Hub supporta i formati OpenVEX o CSAF.
   2. Conserva i tuoi file VEX nel repository del codice sorgente, nella directory .vex/ alla radice del repository. Maggiori informazioni qui.
   3. Per ulteriori indicazioni sulla creazione di documenti VEX per VEX Hub, vedere qui.
2. Registra il tuo pacchetto con VEX Hub
   1. Apri una Pull Request che aggiunge il PURL del tuo pacchetto al file dei pacchetti sottoposti a crawling.

Tutto qui! VEX Hub recupererà e elaborerà automaticamente i tuoi documenti VEX.

Crawling di VEX

VEX Hub Crawler esegue periodicamente il crawling dei documenti VEX dei pacchetti registrati e li mantiene in VEX Hub. I pacchetti registrati sono definiti come un elenco di PURL in un file che chiunque può aggiornare tramite Pull Request.

Per informazioni dettagliate sulla registrazione dei PURL, sugli ecosistemi supportati e sui requisiti specifici, fare riferimento a VEX Hub Crawler.

Identificazione dei repository sorgente

Il file dei pacchetti specifica solo il PURL del pacchetto da sottoporre a crawling e VEX Hub Crawler identifica automaticamente il repository del codice sorgente in cui si trova il file VEX. Il metodo di identificazione dei repository sorgente varia in base all'ecosistema. Per informazioni dettagliate su come i repository sorgente vengono identificati e sottoposti a crawling per i diversi tipi di pacchetto, fare riferimento alla documentazione di vex-crawler.

Scoperta dei documenti VEX

Dopo aver identificato il repository del codice sorgente, VEX Hub scopre automaticamente i documenti VEX al suo interno. Il processo di scoperta prevede i seguenti punti chiave:

• I documenti VEX vengono cercati nella directory .vex/ alla radice del repository.
• I formati VEX supportati sono OpenVEX e CSAF.
• Vengono considerati i nomi di file che corrispondono a schemi specifici (ad esempio *.vex.json, *.csaf.json).
• I PURL devono essere utilizzati per prodotti e sottocomponenti nei documenti VEX.
• I documenti VEX che non corrispondono al PURL registrato vengono ignorati.

Per informazioni dettagliate sul processo di scoperta, sugli ecosistemi supportati e sui requisiti specifici, fare riferimento alla documentazione di vex-crawler.

Struttura delle directory

VEX Hub è strutturato in base al Package URL (PURL), escludendo version, qualifiers e subpath. La struttura segue le seguenti regole:

1. La gerarchia delle directory deriva dai componenti scheme, type, namespace (se presente) e name del PURL. In caso di oci, viene utilizzato il qualificatore repository_url al suo posto.
2. Versione e qualificatori sono omessi dalla struttura delle directory. Questi elementi devono essere specificati nel campo products dei documenti VEX.
3. La codifica URL viene applicata ai caratteri speciali nei componenti del PURL.

Esempi di formazione della struttura delle directory:

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

Esempio con codifica di caratteri speciali:

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

Distribuzione

VEX Hub è conforme alla VEX Repository Specification. I file vex_repository.json e index.json possono essere utilizzati per accedere programmaticamente ai documenti VEX in VEX Hub.

Più documenti VEX per PURL

VEX Hub ha la capacità di memorizzare più documenti VEX per un singolo PURL, poiché copia tutti i documenti VEX corrispondenti dal repository sorgente. Tuttavia, la VEX Repository Specification consente un solo documento VEX per PURL. Per conformarsi a questa specifica, VEX Hub implementa la seguente strategia di distribuzione:

• Quando esistono più file VEX per un singolo PURL, VEX Hub seleziona il primo file in ordine lessicografico.
• Scrive il file selezionato in index.json per la distribuzione.

Creazione di documenti VEX per VEX Hub

Per evitare confusione e garantire coerenza, non è consigliato suddividere le dichiarazioni VEX per lo stesso PURL in più file, poiché VEX Hub distribuisce un solo file VEX per PURL.

Gli approcci consigliati sono:

1. Consolidare le dichiarazioni VEX per tutti i prodotti gestiti dal repository sorgente in un unico file.
2. Dividere i documenti VEX per PURL.

Scenario di esempio: Considera un repository sorgente https://github.com/org/repo che mantiene due prodotti, un modulo Go e un'immagine OCi.

Il primo approccio consiste nel creare un unico file VEX, vex.json, contenente le dichiarazioni VEX per entrambi i prodotti.

• openvex.json: Per entrambi i prodotti, con i PURL pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo e pkg:oci/repo?repository_url=ghcr.io/org/repo

Il secondo approccio consiste nel creare file VEX separati per ciascun prodotto.

• golang.vex: Per il modulo Go, con PURL pkg:golang/github.com/org/repo
• oci.vex: Per l'immagine OCI, con i PURL pkg:oci/repo?repository_url=docker.io/org/repo e pkg:oci/repo?repository_url=ghcr.io/org/repo

La seguente struttura non è consigliata:

• v1.vex: Per il modulo Go, con PURL pkg:golang/github.com/org/[email protected]
• v2.vex: Per il modulo Go, con PURL pkg:golang/github.com/org/[email protected]

In questo esempio, v1.vex viene selezionato per la distribuzione e v2.vex viene ignorato. Dovrebbero essere combinati in un unico file VEX, golang.vex, con più versioni e qualificatori.

Modello di fiducia di VEX Hub

Poiché VEX Hub (e VEX in generale) può potenzialmente ampliare i risultati della scansione di sicurezza, è giusto che tu esamini attentamente la correttezza dei documenti VEX che consumi. A differenza di altri feed di scambio di vulnerabilità o feed di advisory di sicurezza predisposti per VEX, VEX Hub non è la fonte dei dati delle dichiarazioni VEX. VEX Hub aggrega solo i documenti VEX esistenti e li organizza in un repository centrale e conveniente.

Per comparire in VEX Hub, i documenti VEX devono essere prima commitati nel repository del codice sorgente del pacchetto principale. Questo approccio si basa sul fatto che, in quanto utente, devi già fidarti dei pacchetti che usi e quindi dei maintainer, della governance e dei processi che adottano. Ogni progetto ha il proprio sistema di governance e i propri processi per il commit nel repository del codice sorgente. Quei sistemi e processi che rendono il codice del pacchetto affidabile ai tuoi occhi sono gli stessi sistemi e processi che rendono affidabili per te i documenti VEX. Non dovresti fidarti di VEX Hub più di quanto ti fidi dei pacchetti che scegli di utilizzare.

VEX Hub non ha alcuna responsabilità o conoscenza del contenuto dei documenti VEX che detiene o dei pacchetti che descrivono. I maintainer di VEX Hub non esaminano né verificano il contenuto dei documenti VEX e la responsabilità dell'accuratezza e della correttezza delle informazioni ricade sui maintainer dei pacchetti di origine. Consigliamo agli utenti di fare manualmente il triage delle vulnerabilità soppresse, così come farebbero il triage di qualsiasi altra vulnerabilità.

Risoluzione dei problemi

Se i documenti VEX nel repository sorgente di un PURL registrato non vengono aggiornati correttamente in VEX Hub, controlla quanto segue:

1. Assicurati che i documenti VEX siano collocati nella posizione corretta (directory .vex/ alla radice del repository).
2. Verifica che i documenti VEX utilizzino una delle convenzioni di denominazione dei file supportate.
3. Conferma che il PURL nel documento VEX corrisponda al PURL registrato in VEX Hub.
4. Consulta la documentazione di vexhub-crawler per assicurarti che tutti i requisiti per il crawling siano soddisfatti.

Se i problemi persistono dopo aver verificato questi punti, apri una issue nel repository di VEX Hub per ulteriore assistenza.

Contribuire

I contributi per migliorare VEX Hub sono benvenuti! Nota che l'elenco dei pacchetti e il codice associato sono mantenuti nel repository di VEX Hub Crawler. Le Pull Request che aggiungono direttamente documenti VEX a questo repository sono sconsigliate. Questo progetto e tutti coloro che vi partecipano sono regolati dal Codice di condotta di Aqua Security.