aquasecurity/vexhub-crawlerRecopila documentos VEX y actualiza VEX Hub
vexhub-crawler es un componente del VEX Hub que recupera automáticamente documentos VEX de los repositorios fuente.
El rastreador identifica los repositorios fuente a partir de PURL (URL de paquete) 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;
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:
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:
El método para identificar repositorios fuente varía según el ecosistema:
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.
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>
Se utilizará la API de PyPI para resolver el repositorio.
curl -s https://pypi.org/pypi/<package-name>/json | jq .info.project_urls.Source
Se utilizará la API de crates.io para resolver el repositorio.
curl -s https://crates.io/api/v1/crates/<crate-name> | jq .crate.repository
Para paquetes Maven, se siguen estos pasos para identificar el repositorio fuente:
repository_url según la especificación PURL. La URL predeterminada es https://repo.maven.apache.org/maven2.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.maven-metadata.xml,scm.url o url dentro del archivo POM.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:
repository_url y la etiqueta :latest.latest.org.opencontainers.image.source en las siguientes ubicaciones:
Labels de la configuración de la imagenannotations del manifiesto de la imagenEjemplo 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
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:
El rastreador realiza las siguientes validaciones:
El rastreador copia los archivos descubiertos a VEX Hub con sus nombres de archivo originales. La estructura de directorios en VEX Hub se crea basándose en el URL de paquete (PURL), excluyendo version, qualifiers y subpath.
El rastreador adopta un modelo de confianza basado en documentos VEX almacenados en repositorios fuente. Como se menciona en la sección Validación, filtra los documentos VEX que declaran productos distintos del PURL original.
Por ejemplo, si un PURL pkg:npm/malicious está registrado en VEX Hub y se resuelve al repositorio fuente github.com/org/malicious, cualquier documento VEX almacenado allí debe tener un ID de producto de pkg:npm/malicious.
Los documentos VEX con ID de producto diferentes, como pkg:npm/[email protected], se ignorarán.
Este enfoque garantiza que solo se incluyan en VEX Hub documentos VEX relevantes y confiables.
Actualmente, VEX Hub Crawler utiliza las API de los registros para identificar los repositorios fuente de los paquetes. Sin embargo, este enfoque conlleva posibles riesgos de seguridad, ya que la información del repositorio puede ser establecida libremente por los mantenedores de paquetes, lo que lo hace susceptible a manipulación.
Para abordar este desafío, estamos considerando utilizar la atestación de procedencia para una resolución más fiable del repositorio fuente en el futuro. La atestación de procedencia permite obtener la URL real del repositorio donde se construyó un paquete de manera confiable, lo que permite la verificación criptográfica de la relación entre el código fuente de un paquete y sus artefactos publicados.
Cabe destacar que npm ya ha implementado la procedencia en su registro. Esta implementación hace posible recuperar la información del repositorio fuente directamente del PURL utilizando los datos de procedencia. Creemos que este enfoque puede mejorar la confiabilidad del proceso de resolución del repositorio fuente para los paquetes.