aquasecurity/vexhub-crawlerRaccogli documenti VEX e aggiorna VEX Hub
vexhub-crawler è un componente del VEX Hub che recupera automaticamente i documenti VEX dai repository sorgente.
Il crawler identifica i repository sorgente a partire dai PURL (Package URL) registrati e copia i documenti VEX in VEX Hub. Questo processo garantisce che VEX Hub mantenga una raccolta aggiornata di documenti VEX per vari pacchetti software.
Il diagramma seguente illustra il flusso di processo ad alto livello del VEX Hub Crawler, usando npm come esempio:
flowchart TD
Dev[Developer] -->|Register package| PL[Package List]
PL -->|Provide packages for crawling| Crawler
Crawler -->|Identify repository URL| Registry[Package Registry]
Crawler -->|Retrieve VEX documents| Src
Crawler -->|Validate and update VEX documents| Hub
subgraph crawler [VEX Hub Crawler]
Crawler
PL
end
subgraph bottom [ ]
direction LR
Registry
Src
Hub[VEX Hub]
subgraph Src[Source Repository]
direction TB
VEX[VEX documents<br>under .vex/ directory]
end
end
classDef dev fill:#b3d9ff,stroke:#2a4d69,stroke-width:1px,color:#2a4d69;
classDef vexHub fill:#ffd9e6,stroke:#4b3832,stroke-width:1px,color:#4b3832;
classDef crawler fill:#c2f0c2,stroke:#1e4d2b,stroke-width:1px,color:#1e4d2b;
classDef npmReg fill:#ffe6cc,stroke:#5e3023,stroke-width:1px,color:#5e3023;
classDef sourceRepo fill:#e6ccff,stroke:#3b2e58,stroke-width:1px,color:#3b2e58;
classDef pkgList fill:#ccf2ff,stroke:#1c4e5a,stroke-width:1px,color:#1c4e5a;
classDef invisible fill:none,stroke:none;
class Dev dev;
class Hub vexHub;
class crawler crawler;
class Registry npmReg;
class Src,VEX sourceRepo;
class PL pkgList;
class bottom invisible;
Il VEX Hub Crawler mantiene un elenco di PURL per individuare i documenti VEX. Il formato del file di definizione dei PURL è il seguente:
pkg:
npm:
- namespace: "@angular"
name: animations
golang:
- name: github.com/aquasecurity/trivy
pypi:
- name: django
maven:
- namespace: org.junit.jupiter
name: junit-jupiter-api
oci:
- name: trivy
qualifiers:
- key: repository_url
value: index.docker.io/aquasec/trivy
- name: trivy
qualifiers:
- key: repository_url
value: ghcr.io/aquasecurity/trivy
Quando si specificano i PURL, sono richiesti i seguenti componenti:
Il campo version deve essere omesso.
namespace, qualifiers e subpath possono essere necessari per alcuni ecosistemi, come oci.
Per informazioni dettagliate sulla composizione dei PURL, fare riferimento alla specifica PURL.
L'elenco dei PURL può essere aggiornato da chiunque tramite Pull Request. Se i documenti VEX sono già archiviati nel repository sorgente di un progetto open source, chiunque non sia tra i maintainer del progetto è invitato a registrare il PURL in VEX Hub.
Attualmente, il crawler supporta i seguenti ecosistemi:
Il metodo per identificare i repository sorgente varia in base all'ecosistema:
L'API del registry npm verrà utilizzata per risolvere il repository sorgente. Ogni pacchetto dispone di una sezione per definire il repository.
Per l'esempio di React, sarebbe come segue:
$ curl -s https://registry.npmjs.org/react | jq .repository.url
"git+https://github.com/facebook/react.git"
vexhub-crawler recupererà automaticamente i file VEX archiviati in https://github.com/facebook/react.
Verrà effettuata una richiesta HTTP per identificare il repository da go-import.
curl -s "https://k8s.io/client-go?go-get=1"
<html><head>
<meta name="go-import"
content="k8s.io/client-go
git https://github.com/kubernetes/client-go">
<meta name="go-source"
content="k8s.io/client-go
https://github.com/kubernetes/client-go
https://github.com/kubernetes/client-go/tree/master{/dir}
https://github.com/kubernetes/client-go/blob/master{/dir}/{file}#L{line}">
</head></html>
L'API PyPI verrà utilizzata per risolvere il repository.
curl -s https://pypi.org/pypi/<package-name>/json | jq .info.project_urls.Source
L'API di crates.io verrà utilizzata per risolvere il repository.
curl -s https://crates.io/api/v1/crates/<crate-name> | jq .crate.repository
Per i pacchetti Maven, la procedura per identificare il repository sorgente segue questi passaggi:
repository_url in base alla specifica PURL. L'URL predefinito è https://repo.maven.apache.org/maven2.maven-metadata.xml usando namespace e name del PURL. Ad esempio, per com.fasterxml.jackson.core:jackson-databind, l'URL sarebbe: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/maven-metadata.xml.maven-metadata.xml,scm.url o url all'interno del file POM.Per le immagini OCI, il repository sorgente viene identificato esaminando l'etichetta o l'annotazione org.opencontainers.image.source del tag latest.
I metadati vengono solitamente impostati durante il processo di build dell'immagine e forniscono un modo standardizzato per fare riferimento al repository del codice sorgente.
Il processo è il seguente:
repository_url e il tag :latest.latest.org.opencontainers.image.source nelle seguenti posizioni:
Labels della configurazione dell'immagineannotations del manifest dell'immagineEsempio di recupero dell'URL sorgente usando crane:
$ crane config ghcr.io/aquasecurity/trivy:latest | jq -r '.config.Labels["org.opencontainers.image.source"]'
https://github.com/aquasecurity/trivy
Una volta identificato il repository sorgente (attualmente sono supportati solo i repository git), vexhub-crawler cerca i documenti VEX nella directory .vex/ alla radice del repository.
Il crawler considera come documenti VEX i file che corrispondono ai seguenti pattern:
Il crawler esegue le seguenti validazioni:
Il crawler copia i file individuati in VEX Hub con i loro nomi originali. La struttura delle directory in VEX Hub viene creata in base al Package URL (PURL), escludendo version, qualifiers e subpath.
Il crawler adotta un modello di fiducia basato sui documenti VEX archiviati nei repository sorgente. Come menzionato nella sezione Validazione, filtra i documenti VEX che dichiarano prodotti diversi dal PURL originale.
Ad esempio, se un PURL pkg:npm/malicious è registrato in VEX Hub e risolve al repository sorgente github.com/org/malicious, qualsiasi documento VEX ivi archiviato deve avere un product ID pari a pkg:npm/malicious.
I documenti VEX con product ID diversi, come pkg:npm/[email protected], verranno ignorati.
Questo approccio garantisce che in VEX Hub vengano inclusi solo documenti VEX pertinenti e affidabili.
Attualmente, VEX Hub Crawler utilizza le API dei registry per identificare i repository sorgente dei pacchetti. Tuttavia, questo approccio presenta potenziali rischi per la sicurezza poiché le informazioni sul repository possono essere impostate liberamente dai maintainer dei pacchetti, rendendole suscettibili a manomissioni.
Per affrontare questa sfida, stiamo valutando l'uso dell'attestazione di provenienza per una risoluzione più affidabile del repository sorgente in futuro. L'attestazione di provenienza consente di ottenere in modo attendibile l'URL effettivo del repository in cui un pacchetto è stato compilato, permettendo la verifica crittografica della relazione tra il codice sorgente di un pacchetto e i suoi artefatti pubblicati.
In particolare, npm ha già implementato la provenienza nel proprio registry. Questa implementazione rende possibile recuperare le informazioni sul repository sorgente direttamente dal PURL usando i dati di provenienza. Riteniamo che questo approccio possa migliorare l'affidabilità del processo di risoluzione del repository sorgente per i pacchetti.