vexhub

¡Eso es todo! VEX Hub recuperará y procesará automáticamente tus documentos VEX.

Rastreo de VEX

El VEX Hub Crawler rastrea periódicamente los documentos VEX de los paquetes registrados y los mantiene en VEX Hub. Los paquetes registrados se definen como una lista de PURLs en un archivo que cualquier persona puede actualizar mediante Pull Requests.

Para obtener información detallada sobre el registro de PURL, los ecosistemas compatibles y los requisitos específicos, consulta VEX Hub Crawler.

Identificación de repositorios fuente

El archivo de paquetes especifica únicamente el PURL del paquete que se va a rastrear, y VEX Hub Crawler identifica automáticamente el repositorio de código fuente donde se encuentra el archivo VEX. El método para identificar los repositorios fuente varía según el ecosistema. Para obtener información detallada sobre cómo se identifican y rastrean los repositorios fuente para los diferentes tipos de paquetes, consulta la documentación de vex-crawler.

Descubrimiento de documentos VEX

Después de identificar el repositorio de código fuente, VEX Hub descubre automáticamente los documentos VEX en él. El proceso de descubrimiento incluye los siguientes puntos clave:

• Los documentos VEX se buscan en el directorio .vex/ en la raíz del repositorio.
• Los formatos VEX compatibles son OpenVEX y CSAF.
• Se consideran los nombres de archivo que coinciden con patrones específicos (por ejemplo, *.vex.json, *.csaf.json).
• Se deben utilizar PURLs para los productos y subcomponentes en los documentos VEX.
• Se ignoran los documentos VEX que no coinciden con el PURL registrado.

Para obtener información detallada sobre el proceso de descubrimiento, los ecosistemas compatibles y los requisitos específicos, consulta la documentación de vex-crawler.

Estructura de directorios

VEX Hub se estructura según el Package URL (PURL), excluyendo version, qualifiers y subpath. La estructura sigue las siguientes reglas:

1. La jerarquía de directorios se deriva de los componentes del PURL: scheme, type, namespace (si está presente) y name. En el caso de oci, se utiliza en su lugar el qualifier repository_url.
2. La versión y los qualifiers se omiten en la estructura de directorios. Estos elementos se deben especificar en el campo products de los documentos VEX.
3. Se aplica codificación URL a los caracteres especiales en los componentes del PURL.

Ejemplos de formación de la estructura de directorios:

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

Ejemplo con codificación de caracteres especiales:

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

Distribución

VEX Hub cumple con la VEX Repository Specification. Los archivos vex_repository.json e index.json se pueden utilizar para acceder programáticamente a los documentos VEX en VEX Hub.

Múltiples documentos VEX por PURL

VEX Hub tiene la capacidad de almacenar múltiples documentos VEX para un único PURL, ya que copia todos los documentos VEX que coinciden del repositorio fuente. Sin embargo, la VEX Repository Specification permite solo un documento VEX por PURL. Para cumplir con esta especificación, VEX Hub implementa la siguiente estrategia de distribución:

• Cuando existen múltiples archivos VEX para un único PURL, VEX Hub selecciona el primer archivo en orden lexicográfico.
• Escribe el archivo seleccionado en index.json para su distribución.

Creación de documentos VEX para VEX Hub

Para evitar confusiones y garantizar la coherencia, no se recomienda dividir las declaraciones VEX del mismo PURL en varios archivos, ya que VEX Hub distribuye solo un archivo VEX por PURL.

Los enfoques recomendados son:

1. Consolidar las declaraciones VEX de todos los productos gestionados por el repositorio fuente en un único archivo.
2. Dividir los documentos VEX por PURL.

Escenario de ejemplo: Considera un repositorio fuente https://github.com/org/repo que mantiene dos productos: un módulo Go y una imagen OCI.

El primer enfoque es crear un único archivo VEX, vex.json, que contenga las declaraciones VEX de ambos productos.

• openvex.json: Para ambos productos, con los PURLs pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo y pkg:oci/repo?repository_url=ghcr.io/org/repo

El segundo enfoque es crear archivos VEX separados para cada producto.

• golang.vex: Para el módulo Go, con el PURL pkg:golang/github.com/org/repo
• oci.vex: Para la imagen OCI, con los PURLs pkg:oci/repo?repository_url=docker.io/org/repo y pkg:oci/repo?repository_url=ghcr.io/org/repo

La siguiente estructura no se recomienda:

• v1.vex: Para el módulo Go, con el PURL pkg:golang/github.com/org/[email protected]
• v2.vex: Para el módulo Go, con el PURL pkg:golang/github.com/org/[email protected]

En este ejemplo, se selecciona v1.vex para la distribución y se ignora v2.vex. Deberían combinarse en un único archivo VEX, golang.vex, con múltiples versiones y qualifiers.

Modelo de confianza de VEX HUB

Dado que VEX Hub (y VEX en general) potencialmente complementa los resultados del escaneo de seguridad, es razonable que examines minuciosamente la corrección de los documentos VEX que consumes. A diferencia de otros feeds de intercambio de vulnerabilidades, o feeds de avisos de seguridad preparados para VEX, VEX Hub no es la fuente de datos de las declaraciones VEX. VEX Hub solo agrega documentos VEX existentes y los organiza en un repositorio central y conveniente.

Para aparecer en VEX Hub, los documentos VEX deben ser incorporados primero al repositorio de código fuente del paquete principal. Este enfoque se basa en el hecho de que, como usuario, ya debes confiar en los paquetes que utilizas y, por tanto, en sus mantenedores, gobernanza y procesos. Cada proyecto tiene su propio sistema de gobernanza y sus propios procesos para incorporar cambios al repositorio de código fuente. Esos sistemas y procesos que hacen que el código de los paquetes sea digno de confianza ante tus ojos son los mismos sistemas y procesos que hacen que los documentos VEX sean dignos de confianza para ti. No debes confiar en VEX Hub más de lo que confías en los paquetes que eliges utilizar.

VEX Hub no tiene ninguna responsabilidad ni conocimiento sobre el contenido de los documentos VEX que aloja ni sobre los paquetes que describen. Los mantenedores de VEX Hub no revisan ni verifican el contenido de los documentos VEX, y la responsabilidad de la exactitud y corrección de la información recae en los mantenedores originales de los paquetes. Recomendamos que los usuarios realicen un triaje manual de las vulnerabilidades suprimidas, de la misma manera en que harían triaje de cualquier otra vulnerabilidad.

Solución de problemas

Si los documentos VEX del repositorio fuente de un PURL registrado no se están actualizando correctamente en VEX Hub, verifica lo siguiente:

1. Asegúrate de que los documentos VEX estén ubicados en el lugar correcto (directorio .vex/ en la raíz del repositorio).
2. Verifica que los documentos VEX utilicen una de las convenciones de nomenclatura de archivos compatibles.
3. Confirma que el PURL en el documento VEX coincida con el PURL registrado en VEX Hub.
4. Revisa la documentación de vexhub-crawler para asegurarte de que se cumplan todas las especificaciones para el rastreo.

Si los problemas persisten después de confirmar estos puntos, abre un issue en el repositorio de VEX Hub para obtener más ayuda.

Contribuciones

¡Las contribuciones para mejorar VEX Hub son bienvenidas! Ten en cuenta que la lista de paquetes y el código asociado se mantienen en el repositorio de VEX Hub Crawler. Se desaconsejan los Pull Requests que añadan documentos VEX directamente a este repositorio. Este proyecto y todos los que participan en él se rigen por el Aqua Security Code of Conduct.