VEX Hub Crawler

vexhub-crawler es un componente del [VEX Hub][vexhub] que recupera automáticamente documentos VEX de los repositorios fuente.

Descripción general

El rastreador identifica los repositorios fuente a partir de [PURL (URL de paquete)][purl] registrados y copia los documentos VEX en VEX Hub. Este proceso garantiza que VEX Hub mantenga una colección actualizada de documentos VEX para diversos paquetes de software.

El siguiente diagrama ilustra el flujo de proceso de alto nivel de VEX Hub Crawler, usando npm como ejemplo:

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;

Registro de PURLs

VEX Hub Crawler mantiene una lista de PURLs para descubrir documentos VEX. El formato del archivo de definición de PURL es el siguiente:

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

Al especificar PURLs, se requieren los siguientes componentes:

• type
• name

La version debe omitirse. Los namespace, qualifiers y subpath pueden ser necesarios para ciertos ecosistemas, como oci. Para obtener información detallada sobre la composición de PURL, consulte la especificación PURL.

La lista de PURLs puede ser actualizada por cualquier persona mediante Pull Requests. Si los documentos VEX ya están almacenados en el repositorio fuente de un proyecto de código abierto, personas distintas de los mantenedores del proyecto pueden registrar el PURL en VEX Hub.

Actualmente, el rastreador es compatible con los siguientes ecosistemas:

• npm
• Go
• PyPI
• Maven
• Cargo
• OCI

Identificación de repositorios fuente

El método para identificar repositorios fuente varía según el ecosistema:

npm

Se utilizará la API del registro npm para resolver el repositorio fuente. Cada paquete tiene una sección para definir el repositorio.

Por ejemplo, para React, sería como sigue:

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

vexhub-crawler recuperará automáticamente los archivos VEX almacenados en https://github.com/facebook/react.

Go

Se realizará una petición HTTP para identificar el repositorio a 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

Se utilizará la API de PyPI para resolver el repositorio.

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

Cargo

Se utilizará la API de crates.io para resolver el repositorio.

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

Maven

Para paquetes Maven, se siguen estos pasos para identificar el repositorio fuente:

1. Primero, obtener el repository_url según la especificación PURL. La URL predeterminada es https://repo.maven.apache.org/maven2.
2. Luego, construir la URL del archivo maven-metadata.xml utilizando el namespace y el nombre del PURL. Por ejemplo, para com.fasterxml.jackson.core:jackson-databind, la URL sería: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/maven-metadata.xml.
3. Extraer la última versión de maven-metadata.xml,
4. Con esta versión, descargar el archivo POM correspondiente. Por ejemplo, si la última versión de jackson-databind es 2.17.1, la URL del POM sería: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/2.17.1/jackson-core-2.17.1.pom
5. Finalmente, identificar el repositorio fuente examinando el campo scm.url o url dentro del archivo POM.

Imágenes OCI

Para imágenes OCI, el repositorio fuente se identifica examinando la etiqueta o anotación org.opencontainers.image.source de la etiqueta latest. Estos metadatos se establecen normalmente durante el proceso de construcción de la imagen y proporcionan una forma estandarizada de referenciar el repositorio del código fuente.

El proceso es el siguiente:

1. Para el PURL dado, construir la referencia completa de la imagen añadiendo repository_url y la etiqueta :latest.
2. Recuperar el manifiesto y la configuración de la imagen para la etiqueta latest.
3. Buscar la clave org.opencontainers.image.source en las siguientes ubicaciones:
   • El campo Labels de la configuración de la imagen
   • El campo annotations del manifiesto de la imagen

Ejemplo de obtención de la URL del repositorio fuente usando crane:

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

Descubrimiento de documentos VEX

Una vez identificado el repositorio fuente (actualmente solo se admiten repositorios git), vexhub-crawler busca documentos VEX en el directorio .vex/ en la raíz del repositorio.

El rastreador considera documentos VEX los archivos que coinciden con los siguientes patrones:

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

Validación

El rastreador realiza las siguientes validaciones:

1. Verifica que el PURL escrito en el VEX recuperado coincida con el registrado en VEX Hub.
2. De no ser así, el documento se considera no relacionado y se ignora.

Estructura de directorios de VEX Hub