VEX Hub Crawler

vexhub-crawler est un composant de VEX Hub qui récupère automatiquement les documents VEX depuis les dépôts sources.

Aperçu

Le crawler identifie les dépôts sources à partir des PURLs (Package URLs) enregistrés et copie les documents VEX dans VEX Hub. Ce processus garantit que VEX Hub conserve une collection à jour de documents VEX pour divers packages.

Le diagramme suivant illustre le flux de processus de haut niveau du VEX Hub Crawler, en prenant npm comme exemple :

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;

Enregistrement des PURLs

VEX Hub Crawler maintient une liste de PURLs pour découvrir les documents VEX. Le format du fichier de définition des PURLs est le suivant :

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

Lors de la spécification des PURLs, les composants suivants sont requis :

type
name

Le version doit être omis. Les namespace, qualifiers et subpath peuvent être nécessaires pour certains écosystèmes, comme oci. Pour des informations détaillées sur la composition des PURLs, veuillez consulter la spécification des PURLs.

La liste des PURLs peut être mise à jour par toute personne via des Pull Requests. Si des documents VEX sont déjà stockés dans le dépôt source d'un projet open-source, les personnes autres que les mainteneurs du projet sont invitées à enregistrer le PURL dans VEX Hub.

Actuellement, le crawler prend en charge les écosystèmes suivants :

npm
Go
PyPI
Maven
Cargo
OCI

Identification des dépôts sources

La méthode d'identification des dépôts sources varie selon l'écosystème :

npm

L'API du registre npm sera utilisée pour résoudre le dépôt source. Chaque package dispose d'une section pour définir le dépôt.

Pour l'exemple de React, cela donnerait :

$ curl -s https://registry.npmjs.org/react | jq .repository.url
"git+https://github.com/facebook/react.git"

vexhub-crawler récupérera automatiquement les fichiers VEX stockés dans https://github.com/facebook/react.

Go

Une requête HTTP sera effectuée pour identifier le dépôt à partir de 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>

PyPI

L'API PyPI sera utilisée pour résoudre le dépôt.

curl -s https://pypi.org/pypi/<package-name>/json | jq .info.project_urls.Source

Cargo

L'API crates.io sera utilisée pour résoudre le dépôt.

curl -s https://crates.io/api/v1/crates/<crate-name> | jq .crate.repository

Maven

Pour les packages Maven, le processus suit les étapes suivantes pour identifier le dépôt source :

Tout d'abord, obtenez le repository_url basé sur la spécification PURL. L'URL par défaut est https://repo.maven.apache.org/maven2.
Ensuite, construisez l'URL du fichier maven-metadata.xml en utilisant le namespace et le nom du PURL. Par exemple, pour com.fasterxml.jackson.core:jackson-databind, l'URL serait : https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/maven-metadata.xml.
Extrayez la dernière version à partir du maven-metadata.xml,
Avec cette version, téléchargez le fichier POM correspondant. Par exemple, si la dernière version de jackson-databind est 2.17.1, l'URL du POM serait : https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/2.17.1/jackson-core-2.17.1.pom
Enfin, identifiez le dépôt source en examinant le champ scm.url ou url dans le fichier POM.

Images OCI

Pour les images OCI, le dépôt source est identifié en examinant le label ou l'annotation org.opencontainers.image.source du tag latest. Ces métadonnées sont généralement définies lors du processus de construction de l'image et fournissent un moyen standardisé de référencer le dépôt du code source.

Le processus est le suivant :

Pour le PURL donné, construisez la référence complète de l'image en ajoutant repository_url et le tag :latest.
Récupérez le manifeste et la configuration de l'image pour le tag latest.
Recherchez la clé org.opencontainers.image.source aux emplacements suivants :
- Le champ Labels de la configuration de l'image
- Le champ annotations du manifeste de l'image

Exemple de récupération de l'URL source à l'aide de crane :

$ crane config ghcr.io/aquasecurity/trivy:latest | jq -r '.config.Labels["org.opencontainers.image.source"]'
https://github.com/aquasecurity/trivy

Découverte des documents VEX

Une fois le dépôt source identifié (seuls les dépôts git sont actuellement pris en charge), vexhub-crawler recherche les documents VEX dans le répertoire .vex/ à la racine du dépôt.

Le crawler considère comme documents VEX les fichiers correspondant aux modèles suivants :

*.csaf.json
*.openvex.json
*.vex.json
.openvex.json
vex.json

Validation

Le crawler effectue les validations suivantes :

Vérifie que le PURL écrit dans le VEX récupéré correspond à celui enregistré dans VEX Hub.
Dans le cas contraire, le document est considéré comme sans rapport et ignoré.

Structure du répertoire VEX Hub

Le crawler copie les fichiers découverts vers VEX Hub avec leurs noms de fichiers d'origine. La structure du répertoire dans VEX Hub est créée sur la base du Package URL (PURL), à l'exclusion de la version, des qualifiers et du subpath.

Justification

Fiabilité

Le crawler adopte un modèle de confiance basé sur les documents VEX stockés dans les dépôts sources. Comme mentionné dans la section Validation, il exclut les documents VEX qui déclarent des produits différents du PURL d'origine.

Par exemple, si un PURL pkg:npm/malicious est enregistré dans VEX Hub et résout vers le dépôt source github.com/org/malicious, tous les documents VEX qui y sont stockés doivent avoir un ID de produit pkg:npm/malicious. Les documents VEX avec des ID de produit différents, tels que pkg:npm/[email protected], seront ignorés.

Cette approche garantit que seuls les documents VEX pertinents et dignes de confiance sont inclus dans VEX Hub.

Travaux futurs

Résolution plus fiable du dépôt source

Actuellement, VEX Hub Crawler utilise les API de registres pour identifier les dépôts sources des packages. Cependant, cette approche présente des risques de sécurité potentiels, car les informations sur le dépôt peuvent être librement définies par les mainteneurs de packages, ce qui la rend susceptible d'être falsifiée.

Pour relever ce défi, nous envisageons d'utiliser l'attestation de provenance pour une résolution plus fiable du dépôt source à l'avenir. L'attestation de provenance permet d'obtenir de manière fiable l'URL réelle du dépôt où un package a été construit, permettant une vérification cryptographique de la relation entre le code source d'un package et ses artefacts publiés.

Notamment, npm a déjà implémenté la provenance dans son registre. Cette implémentation permet de récupérer les informations du dépôt source directement à partir du PURL en utilisant les données de provenance. Nous pensons que cette approche peut renforcer la fiabilité du processus de résolution du dépôt source pour les packages.

vexhub-crawler

Populaires