aquasecurity/vex-repo-specEspecificación del Repositorio VEX
Las palabras clave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" y "OPTIONAL" en este documento deben interpretarse tal como se describe en el RFC 2119.
Al comparar versiones:
Ejemplos de comparación:
El archivo de manifiesto proporciona metadatos sobre un repositorio de datos VEX. Este archivo DEBE contener la información necesaria para recuperar y actualizar los datos VEX.
https://<domain>/.well-known/vex-repository.jsonvex-repository.json DEBE colocarse en el directorio raíz de la rama principal.El esquema JSON del archivo de manifiesto se define aquí.
{
"name": "Example Org VEX Repository",
"description": "VEX repository for Example Organization",
"versions": [
{
"spec_version": "0.1",
"locations": [
{
"url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
}
],
"update_interval": "24h",
"repository_specific": {
"location": {
"repository_type": "db",
"db_type": "bbolt",
"url": "oci://ghcr.io/example.com/vex-db:0"
}
}
},
{
"spec_version": "1.0",
"locations": [
{
"url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
},
{
"url": "https://example.com/vex-api/v1"
}
],
"update_interval": "1h"
}
]
}
| Campo | Requerido | Descripción y Notas de Uso |
|---|---|---|
| name | ✓ | El nombre del repositorio. |
| description | ✓ | Una breve descripción del repositorio. |
| versions | ✓ | Un arreglo que contiene detalles de las versiones disponibles. Cada objeto del arreglo representa una versión que implementa una versión de la Especificación del Repositorio VEX. Las versiones DEBEN ordenarse en orden ascendente, de la más antigua a la más reciente. Consulte la tabla separada para los subcampos. |
| Campo | Requerido | Descripción y Notas de Uso |
|---|---|---|
| spec_version | ✓ | La versión de la Especificación del Repositorio VEX implementada (p. ej., "0.1"). El formato DEBE ser "X.Y" según se define en la sección 1. |
| locations | ✓ | Un arreglo de objetos que describen las ubicaciones de datos VEX. DEBE contener al menos un objeto de ubicación. Consulte la tabla separada para los subcampos. |
| update_interval | ✓ | El intervalo recomendado de verificación de actualizaciones para los datos VEX de esta versión. Utiliza el formato de duración de Go (p. ej., "1h", "30m", "24h"). |
| repository_specific | - | Información adicional específica del repositorio. |
| Campo | Requerido | Descripción y Notas de Uso |
|---|---|---|
| url | ✓ | Una URL para la ubicación de los datos VEX, que comienza con "https://". El contenido se adhiere a las especificaciones de la estructura del repositorio en la sección 3 y 4. La URL puede incluir una especificación de subdirectorio añadiendo '//' seguido de la ruta del subdirectorio. |
El repositorio DEBE tener la siguiente estructura:
vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
├── <type>/
│ ├── <namespace>/
│ │ ├── <name>/
│ │ │ └── vex.json
│ │ └── ...
│ └── ...
└── ...
Donde <archive_extension> es uno de los formatos de archivo soportados.
El [optional_subdirectory/] se incluye cuando la URL en el campo locations termina con // seguido de una ruta de subdirectorio.
Esto permite flexibilidad en la estructura del repositorio, particularmente al usar diseños de repositorio existentes, como los de los repositorios de GitHub.
Por ejemplo, si la URL es https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main, la estructura de archivos sería:
main.tar.gz
└──repo-main/
├── index.json
└── pkg/
└── ...
En este caso, repo-main/ es el directorio raíz del repositorio VEX dentro del archivo tar.gz.
El archivo index.json sirve como manifiesto del contenido del archivo. DEBE colocarse en el directorio raíz del archivo o en el subdirectorio especificado si se define uno en la URL. El archivo DEBE tener la siguiente estructura:
{
"updated_at": "2023-07-04T12:00:00Z",
"packages": [
{
"id": "pkg:deb/debian/curl",
"location": "pkg/deb/debian/curl/vex.json"
},
{
"id": "pkg:npm/lodash",
"location": "pkg/npm/lodash/vex.json",
"format": "csaf"
}
]
}
Descripciones de campos:
| Campo | Requerido | Descripción |
|---|---|---|
| updated_at | ✓ | Marca de tiempo que indica cuándo se actualizó por última vez este index.json. |
| packages | ✓ | Arreglo de objetos, cada uno representa un paquete en el repositorio. |
| packages[].id | ✓ | Identificador del paquete. Actualmente, solo se acepta Package URL (PURL). La versión, los calificadores y la subruta DEBEN omitirse, ya que se incluyen en el documento VEX. Para paquetes de tipo OCI, el calificador repository_url DEBE incluirse en el id. |
| packages[].location | ✓ | Ruta relativa al archivo VEX de este paquete dentro del archivo. Los clientes DEBEN usar este campo para localizar los archivos VEX de paquetes específicos. |
| packages[].format | - | Formato de los datos VEX. Puede ser "openvex" o "csaf". Si se omite, se asume "openvex". |
El esquema para el archivo de índice se define aquí.
La información VEX de cada paquete DEBE almacenarse en un archivo JSON separado, siguiendo la estructura de rutas definida en el archivo index.json. El contenido de estos archivos DEBE adherirse a la especificación de formato VEX (OpenVEX o CSAF VEX) según se especifica en el campo format.
Un único documento VEX PUEDE incluir información para diferentes versiones, calificadores y subrutas del mismo paquete.
Para ejemplos de documentos OpenVEX, consulte la especificación de OpenVEX.
repository_url del PURL PUEDE usarse para crear la estructura de directorios. Por ejemplo, un paquete con PURL "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" podría almacenarse en "pkg/oci/docker.io/library/debian/vex.json".location del archivo index.json, independientemente de la estructura recomendada.Al actualizar el repositorio VEX:
updated_at.locations correspondiente en el archivo de manifiesto (vex-repository.json) si es necesario.El Repositorio VEX DEBE distribuirse como un archivo que contenga los datos VEX y los metadatos asociados. Este archivo DEBE ser referenciado por el campo locations en el archivo vex-repository.json y es el medio principal de distribución de información VEX.
El archivo DEBE estar en uno de los siguientes formatos:
tar.gz y tgztar.bz2 y tbz2tar.xz y txzzipgzbz2xzAl seleccionar una versión del arreglo versions:
spec_version.Al tratar con múltiples ubicaciones en el arreglo locations:
Los clientes DEBERÍAN diseñarse para soportar múltiples repositorios VEX.
Los clientes DEBERÍAN usar el siguiente proceso para verificar actualizaciones:
update_interval del archivo vex-repository.json.update_interval a la marca de tiempo almacenada localmente.Para una operación eficiente, los clientes PUEDEN implementar las siguientes estrategias:
update_interval es muy corto.