vexhub

O VEX Hub é um repositório centralizado que coleta e gerencia documentos Vulnerability Exploitability eXchange (VEX) de vários projetos de software de código aberto. Ele serve como um recurso abrangente para informações de vulnerabilidades, ajudando usuários e ferramentas de segurança a acessar e utilizar dados VEX com eficiência em vários projetos e ecossistemas.

O VEX Hub recupera automaticamente documentos VEX dos repositórios de origem dos projetos registrados. Ao identificar o repositório de origem a partir do Package URL (PURL) registrado, o VEX Hub copia e organiza os documentos VEX, tornando-os facilmente acessíveis para a comunidade em geral.

Início Rápido: Adicionando Documentos VEX ao VEX Hub

1. Crie seu arquivo VEX
   1. O VEX Hub suporta os formatos OpenVEX ou CSAF.
   2. Armazene seus arquivos VEX no repositório de código-fonte no diretório .vex/ na raiz do seu repositório. Mais informações aqui.
   3. Para orientações adicionais sobre a Criação de Documentos VEX para o VEX Hub, veja aqui.
2. Registre seu pacote no VEX Hub
   1. Faça um Pull Request que adicione o PURL do seu pacote ao arquivo de pacotes rastreados.

E pronto! O VEX Hub recuperará e processará automaticamente seus documentos VEX.

Rastreamento VEX

O VEX Hub Crawler rastreia periodicamente os documentos VEX dos pacotes registrados e os mantém no VEX Hub. Os pacotes registrados são definidos como uma lista de PURLs em um arquivo que pode ser atualizado por qualquer pessoa por meio de Pull Requests.

Para informações detalhadas sobre registro de PURL, ecossistemas suportados e requisitos específicos, consulte o VEX Hub Crawler.

Identificando Repositórios de Origem

O arquivo de pacotes especifica apenas o PURL do pacote a ser rastreado, e o VEX Hub Crawler identifica automaticamente o repositório de código-fonte onde o arquivo VEX está localizado. O método para identificar repositórios de origem varia conforme o ecossistema. Para informações detalhadas sobre como repositórios de origem são identificados e rastreados para diferentes tipos de pacotes, consulte a documentação do vex-crawler.

Descoberta de Documentos VEX

Após identificar o repositório de código-fonte, o VEX Hub descobre automaticamente os documentos VEX nele. O processo de descoberta envolve os seguintes pontos-chave:

• Os documentos VEX são procurados no diretório .vex/ na raiz do repositório.
• Os formatos VEX suportados são OpenVEX e CSAF.
• Nomes de arquivo que correspondem a padrões específicos (por exemplo, *.vex.json, *.csaf.json) são considerados.
• PURLs devem ser usados para produtos e subcomponentes nos documentos VEX.
• Documentos VEX que não correspondem ao PURL registrado são ignorados.

Para informações detalhadas sobre o processo de descoberta, ecossistemas suportados e requisitos específicos, consulte a documentação do vex-crawler.

Estrutura de Diretórios

O VEX Hub é estruturado com base no Package URL (PURL), excluindo version, qualifiers e subpath. A estrutura segue as seguintes regras:

1. A hierarquia de diretórios é derivada do esquema, tipo, namespace (se presente) e componentes de nome do PURL. No caso de oci, o qualificador repository_url é usado em seu lugar.
2. Versão e qualificadores são omitidos da estrutura de diretórios. Esses elementos devem ser especificados no campo products dos documentos VEX.
3. A codificação de URL é aplicada a caracteres especiais nos componentes do PURL.

Exemplos de formação da estrutura de diretórios:

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

Exemplo com codificação de caracteres especiais:

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

Distribuição

O VEX Hub está em conformidade com a Especificação do Repositório VEX. Os arquivos vex_repository.json e index.json podem ser usados para acessar programaticamente os documentos VEX no VEX Hub.

Múltiplos Documentos VEX por PURL

O VEX Hub tem a capacidade de armazenar múltiplos documentos VEX para um único PURL, pois copia todos os documentos VEX correspondentes do repositório de origem. No entanto, a Especificação do Repositório VEX permite apenas um documento VEX por PURL. Para estar em conformidade com essa especificação, o VEX Hub implementa a seguinte estratégia de distribuição:

• Quando múltiplos arquivos VEX existem para um único PURL, o VEX Hub seleciona o primeiro arquivo em ordem lexicográfica.
• Escreve o arquivo selecionado em index.json para distribuição.

Criação de Documentos VEX para o VEX Hub

Para evitar confusão e garantir consistência, dividir declarações VEX para o mesmo PURL em múltiplos arquivos não é recomendado, pois o VEX Hub distribui apenas um arquivo VEX por PURL.

As abordagens recomendadas são:

1. Consolidar as declarações VEX de todos os produtos gerenciados pelo repositório de origem em um único arquivo.
2. Dividir os documentos VEX por PURL.

Exemplo de cenário: Considere um repositório de origem https://github.com/org/repo que mantém dois produtos: um módulo Go e uma imagem OCi.

A primeira abordagem é criar um único arquivo VEX, vex.json, contendo declarações VEX para ambos os produtos.

• openvex.json: Para ambos os produtos, com os PURLs pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo e pkg:oci/repo?repository_url=ghcr.io/org/repo

A segunda abordagem é criar arquivos VEX separados para cada produto.

• golang.vex: Para o módulo Go, com o PURL pkg:golang/github.com/org/repo
• oci.vex: Para a imagem OCI, com os PURLs pkg:oci/repo?repository_url=docker.io/org/repo e pkg:oci/repo?repository_url=ghcr.io/org/repo

A seguinte estrutura não é recomendada:

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

Neste exemplo, v1.vex é selecionado para distribuição, e v2.vex é ignorado. Eles devem ser combinados em um único arquivo VEX, golang.vex, com múltiplas versões e qualificadores.

Modelo de Confiança do VEX HUB

Como o VEX Hub (e o VEX em geral) potencialmente complementa os resultados de varredura de segurança, você tem todo o direito de examinar a exatidão dos documentos VEX que consome. Diferente de outros feeds de Vulnerability Exchange, ou feeds de avisos de segurança prontos para VEX, o VEX Hub não é a fonte de dados das declarações VEX. O VEX Hub apenas agrega documentos VEX existentes e os organiza em um repositório central e conveniente.

Para aparecer no VEX Hub, os documentos VEX precisam ser commitados no repositório de código-fonte do pacote principal primeiro. Essa abordagem se baseia no fato de que, como usuário, você já deve confiar nos pacotes que usa e, portanto, nos mantenedores, na governança e nos processos que eles empregam. Cada projeto tem seu próprio sistema de governança e seus próprios processos para commit no repositório de código-fonte. Esses sistemas e processos que tornam o código do pacote confiável aos seus olhos são os mesmos sistemas e processos que tornam os documentos VEX confiáveis para você. Você não deve confiar no VEX Hub mais do que confia nos pacotes que escolhe usar.

O VEX Hub não tem responsabilidade nem conhecimento sobre o conteúdo dos documentos VEX que armazena ou dos pacotes que eles descrevem. Os mantenedores do VEX Hub não revisam nem verificam o conteúdo dos documentos VEX, e a responsabilidade pela precisão e exatidão das informações recai sobre os mantenedores do pacote de origem. Recomendamos que os usuários façam triagem manual das vulnerabilidades suprimidas, da mesma forma que fariam a triagem de qualquer outra vulnerabilidade.

Solução de Problemas

Se os documentos VEX no repositório de origem de um PURL registrado não estiverem sendo atualizados corretamente no VEX Hub, verifique o seguinte:

1. Garanta que os documentos VEX estejam no local correto (diretório .vex/ na raiz do repositório).
2. Verifique se os documentos VEX usam uma das convenções de nomenclatura de arquivo suportadas.
3. Confirme se o PURL no documento VEX corresponde ao PURL registrado no VEX Hub.
4. Revise a documentação do vexhub-crawler para garantir que todas as especificações de rastreamento sejam atendidas.

Se os problemas persistirem após confirmar esses pontos, abra uma issue no repositório do VEX Hub para obter mais assistência.

Como Contribuir

Contribuições para melhorar o VEX Hub são bem-vindas! Observe que a lista de pacotes e o código associado são mantidos no repositório do VEX Hub Crawler. Pull Requests que adicionem documentos VEX diretamente a este repositório são desencorajados. Este projeto e todos que participam dele são regidos pelo Código de Conduta da Aqua Security.