aquasecurity/vex-repo-specEspecificação do Repositório VEX
As palavras-chave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" neste documento devem ser interpretadas conforme descrito na RFC 2119.
Ao comparar versões:
Exemplos de comparação:
O arquivo de manifesto fornece metadados sobre um repositório de dados VEX. Este arquivo DEVE conter informações necessárias para recuperar e atualizar dados VEX.
https://<domain>/.well-known/vex-repository.jsonvex-repository.json DEVE ser colocado no diretório raiz do branch principal.O esquema JSON para o arquivo de manifesto é definido aqui.
{
"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 | Obrigatório | Descrição e Notas de Uso |
|---|---|---|
| name | ✓ | O nome do repositório. |
| description | ✓ | Uma breve descrição do repositório. |
| versions | ✓ | Uma matriz contendo detalhes das versões disponíveis. Cada objeto na matriz representa uma versão que implementa uma versão da Especificação do Repositório VEX. As versões DEVEM ser ordenadas em ordem crescente, da mais antiga para a mais recente. Consulte a tabela separada para subcampos. |
| Campo | Obrigatório | Descrição e Notas de Uso |
|---|---|---|
| spec_version | ✓ | A versão da Especificação do Repositório VEX implementada (ex.: "0.1"). O formato DEVE ser "X.Y" conforme definido na seção 1. |
| locations | ✓ | Uma matriz de objetos que descrevem as localizações dos dados VEX. DEVE conter pelo menos um objeto de localização. Consulte a tabela separada para subcampos. |
| update_interval | ✓ | O intervalo recomendado de verificação de atualização para os dados VEX desta versão. Usa o formato de duração do Go (ex.: "1h", "30m", "24h"). |
| repository_specific | - | Informações adicionais específicas do repositório. |
| Campo | Obrigatório | Descrição e Notas de Uso |
|---|---|---|
| url | ✓ | Uma URL para a localização dos dados VEX, começando com "https://". O conteúdo está em conformidade com as especificações de estrutura do repositório na seção 3 e 4. A URL pode incluir uma especificação de subdiretório anexando '//' seguido do caminho do subdiretório. |
O repositório DEVE ter a seguinte estrutura:
vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
├── <type>/
│ ├── <namespace>/
│ │ ├── <name>/
│ │ │ └── vex.json
│ │ └── ...
│ └── ...
└── ...
Onde <archive_extension> é um dos formatos de arquivo suportados.
O [optional_subdirectory/] é incluído quando a URL no campo locations termina com // seguido de um caminho de subdiretório.
Isso permite flexibilidade na estrutura do repositório, especialmente ao usar layouts de repositório existentes, como os de repositórios GitHub.
Por exemplo, se a URL for https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main, a estrutura de arquivos seria:
main.tar.gz
└──repo-main/
├── index.json
└── pkg/
└── ...
Nesse caso, repo-main/ é o diretório raiz do repositório VEX dentro do arquivo tar.gz.
O arquivo index.json serve como um manifesto para o conteúdo do arquivo compactado. Ele DEVE ser colocado no diretório raiz do arquivo ou no subdiretório especificado, se houver um definido na URL. O arquivo DEVE ter a seguinte estrutura:
{
"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"
}
]
}
Descrições dos campos:
| Campo | Obrigatório | Descrição |
|---|---|---|
| updated_at | ✓ | Timestamp que indica quando este index.json foi atualizado pela última vez. |
| packages | ✓ | Matriz de objetos, cada um representando um pacote no repositório. |
| packages[].id | ✓ | Identificador do pacote. Atualmente, apenas Package URL (PURL) é aceito. Versão, qualificadores e subcaminho DEVEM ser omitidos, pois estão incluídos no documento VEX. Para pacotes do tipo OCI, o qualificador repository_url DEVE ser incluído no id. |
| packages[].location | ✓ | Caminho relativo para o arquivo VEX deste pacote dentro do arquivo. Os clientes DEVEM usar este campo para localizar arquivos VEX específicos de pacotes. |
| packages[].format | - | Formato dos dados VEX. Pode ser "openvex" ou "csaf". Se omitido, assume-se "openvex". |
O esquema para o arquivo de índice é definido aqui.
As informações VEX de cada pacote DEVEM ser armazenadas em um arquivo JSON separado, seguindo a estrutura de caminho definida no arquivo index.json. O conteúdo desses arquivos DEVE estar em conformidade com a especificação de formato VEX (OpenVEX ou CSAF VEX), conforme especificado no campo format.
Um único documento VEX PODE incluir informações para diferentes versões, qualificadores e subcaminhos do mesmo pacote.
Para exemplos de documentos OpenVEX, consulte a especificação OpenVEX.
repository_url do PURL PODE ser usado para criar a estrutura de diretórios. Por exemplo, um pacote com PURL "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" poderia ser armazenado em "pkg/oci/docker.io/library/debian/vex.json".location do arquivo index.json, independentemente da estrutura recomendada.Ao atualizar o repositório VEX:
updated_at.locations relevante no arquivo de manifesto (vex-repository.json), se necessário.O Repositório VEX DEVE ser distribuído como um arquivo contendo os dados VEX e metadados associados. Este arquivo DEVE ser referenciado pelo campo locations no arquivo vex-repository.json e é o principal meio de distribuição das informações VEX.
O arquivo DEVE estar em um dos seguintes formatos:
tar.gz e tgztar.bz2 e tbz2tar.xz e txzzipgzbz2xzAo selecionar uma versão da matriz versions:
spec_version.Ao lidar com múltiplas localizações na matriz locations:
Recomenda-se que os clientes sejam projetados para suportar múltiplos repositórios VEX.
Recomenda-se que os clientes usem o seguinte processo para verificar atualizações:
update_interval do arquivo vex-repository.json.update_interval ao timestamp armazenado localmente.Para uma operação eficiente, os clientes PODEM implementar as seguintes estratégias:
update_interval é muito curto.