Informações de vulnerabilidade

O cliente do NuGet, a partir da versão 6.7, pode baixar informações de vulnerabilidade de pacotes conhecidos para usar em cenários como a verificação de pacotes durante operações de restauração. Embora o recurso de metadados do pacote também contenha informações de vulnerabilidade conhecidas, se um aplicativo precisar verificar um grande número de pacotes em busca de vulnerabilidades conhecidas, é muito mais rápido baixar um arquivo de vulnerabilidades conhecidas e pesquisar localmente, em vez de fazer muitas solicitações HTTP. Por exemplo, isso permite que a restauração do NuGet verifique rapidamente os pacotes restaurados em busca de vulnerabilidades conhecidas, que historicamente nunca baixaram detalhes do pacote do recurso de metadados do pacote.

A API consiste em pelo menos dois arquivos, o índice de vulnerabilidade e um ou mais arquivos de página de vulnerabilidade. Os dados de vulnerabilidade conhecidos podem ser particionados em vários arquivos, e o índice de vulnerabilidade fornece aos clientes as informações necessárias para armazenar em cache os arquivos e atualizar o cache de forma eficiente.

O recurso usado para criar essa URL é o recurso VulnerabilityInfo encontrado no índice de serviço.

Estratégia de particionamento sugerida

As páginas listadas no índice de vulnerabilidade devem ser idealmente otimizadas para maximizar o cache e, portanto, minimizar as atualizações para arquivos grandes. Isso permitirá que os clientes minimizem a frequência necessária para baixar atualizações.

Uma estratégia sugerida para o particionamento de dados de vulnerabilidade é ter duas páginas, base.json e updates.json. O arquivo base.json é atualizado periodicamente (por exemplo, uma vez por mês) e contém todas as vulnerabilidades conhecidas no momento em que o arquivo é regenerado. O arquivo updates.json deve conter todos os novos avisos publicados desde a última regeneração de base.json. Isso permitirá que os clientes baixem o base.json grande com pouca frequência, enquanto o arquivo updates.json que muda com frequência é sempre relativamente pequeno.

Os clientes do NuGet combinam os dados de vários arquivos de forma aditiva e podem carregá-los em qualquer ordem. O esquema do arquivo de dados não permite a modificação ou a edição de vulnerabilidade conhecida de outro arquivo. Portanto, se a fonte de dados de vulnerabilidade de um servidor (por exemplo, o Banco de dados de avisos do GitHub) modificar um comunicado existente, o servidor do NuGet deverá modificar a página em que as informações de vulnerabilidade foram relatadas anteriormente. Uma maneira de conseguir isso com o esquema de partição sugerido é tratar todas as modificações e exclusões de vulnerabilidade como um gatilho para regenerar o arquivo base.json completo e esvaziar updates.json.

Controle de versão

Os seguintes valores de @type são usados:

@type valor	Observações
VulnerabilityInfo/6.7.0	O lançamento inicial

Índice de vulnerabilidade

O índice de vulnerabilidade é uma matriz JSON de objetos com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@name	string	sim	Um nome curto para o arquivo, usado como uma chave de cache.
@id	string	sim	A URL completa (absoluta) para um arquivo de dados de vulnerabilidade.
@updated	string	sim	Uma cadeia de caracteres ISO 8601 que representa a data e a hora em que o arquivo foi atualizado pela última vez, idealmente com o fuso horário UTC.
comment	string	não	Uma cadeia de caracteres descritiva opcional.

As restrições a seguir se aplicam:

• O índice deve ser uma matriz de objetos com entre 1 e 16 itens. Se o servidor não tiver dados de vulnerabilidade (zero páginas), remova o recurso VulnerabilityInfo do ServiceIndex.
• @name deve ser exclusivo dentro do índice, deve ter entre 1 e 32 caracteres e só pode usar os caracteres A a Z, a a z, 0 a 9, - ou _.
• @id deve ser uma URL absoluta, não uma URL relativa.

Paginação de vulnerabilidade

Os arquivos de paginação de vulnerabilidade são um objeto JSON usado como dicionário. As chaves de propriedade são a ID do pacote em letras minúsculas e os valores da propriedade são uma matriz do seguinte objeto com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
severidade	Número inteiro	sim	0 significa baixo, 1 significa médio, 2 significa alto, 3 significa crítico.
url	string	sim	URL onde os usuários podem obter mais informações sobre a vulnerabilidade.
versões	string	sim	O intervalo de versões vulnerável, usando a sintaxe de intervalo de versões do NuGet.

As IDs de pacote (as chaves do objeto raiz) devem ser em letras minúsculas com String.ToLowerInvariant.

A lista de vulnerabilidades conhecidas para um pacote deve ser classificada em ordem decrescente da versão máxima do intervalo de versões, seguida pela versão decrescente da versão mínima, seguida pela ordem crescente da URL. Intervalos com versões nulas mínimas ou máximas (não limitadas) em um intervalo de versões devem ser classificados antes de versões não nulas (limitadas).

Uma página vazia, que não forneça vulnerabilidades conhecidas, deve ser uma matriz JSON vazia ([]).

Exemplos

Aqui está uma amostra de um índice de vulnerabilidade:

[
    {
        "@name": "base",
        "@id": "https://nuget.contoso.com/v3/vulnerabilities/3bb6b300-2f74-45bc-af06-746fd21c024b.json",
        "@updated": "2023-06-01T06:14:58.4159909Z",
        "comment": "The base data for vulnerability update periodically"
    },
    {
        "@name": "update",
        "@id": "https://nuget.contoso.com/v3/vulnerabilities/ffd572cd-33f3-4372-8714-a9cab2e86b45.json",
        "@updated": "2023-06-14T11:35:30.3155764Z",
        "comment": "The patch data for the vulnerability. Contains all the vulnerabilities since base was last updated."
    }
]

Aqui está uma amostra de um arquivo de dados de vulnerabilidade:

{
    "contoso.library": [
        {
            "url": "https://cve.contoso.com/advisories/1",
            "severity": 1,
            "versions": "(, 2.0.0)"
        },
        {
            "url": "https://cve.contoso.com/advisories/2",
            "severity": 2,
            "versions": "(1.0.0, 2.0.0)"
        }
    ],
    "contoso.utilities": [
        {
            "url": "https://cve.contoso.com/advisories/3",
            "severity": 3,
            "versions": "(, 1.0.0)"
        }
    ]
}