Vulnerability information

O cliente 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 um grande número de solicitações HTTP. Por exemplo, isso permite que o NuGet Restore 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 arquivos em cache 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, idealmente, ser 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 base.json arquivo é atualizado periodicamente (por exemplo, uma vez por mês) e contém todas as vulnerabilidades conhecidas no momento em que o arquivo é regenerado. O updates.json ficheiro deve conter quaisquer novos avisos publicados desde a base.json última regeneração. Isso permitirá que os clientes baixem o arquivo grande base.json com pouca frequência, enquanto o arquivo que muda updates.json com frequência é sempre relativamente pequeno.

Os clientes NuGet combinam os dados de vários arquivos aditivamente e podem carregar os arquivos em qualquer ordem. O esquema do arquivo de dados não permite a modificação ou a eliminação de vulnerabilidades conhecidas 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 aviso existente, o servidor NuGet deverá modificar a página em que as informações sobre a 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 completo base.json e esvaziar updates.json.

Se você pretende usar os dados de vulnerabilidade do nuget.org em sua própria implementação de servidor NuGet, você deve levar em consideração os desenvolvedores que não têm acesso direto ao nuget.org. Consulte o nosso guia de implementação para obter mais detalhes.

Versioning

São utilizados os seguintes valores @type:

Vulnerability index

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

Aplicam-se as seguintes restrições:

• 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), deverá remover o VulnerabilityInfo recurso do ServiceIndex.
• @namedeve ser exclusivo dentro do índice, deve ter entre 1 e 32 caracteres e só pode usar os caracteres para , para , para , 0-ou 9_.zaZA
• @id deve ser um URL absoluto, não um URL relativo.

Vulnerability page

Os arquivos de página de vulnerabilidade são um objeto JSON usado como dicionário. As chaves de propriedade são a id do pacote minúscula e os valores de propriedade são uma matriz do seguinte objeto com as seguintes propriedades:

As IDs de pacote (as chaves do objeto raiz) devem ser reduzidas 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 min, seguida pela ordem crescente da URL. Os intervalos com versões nulas min ou max (não limitadas) em um intervalo de versões devem ser classificados para antes de versões não nulas (limitadas).

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

Samples

Aqui está um exemplo 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á um exemplo 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)"
        }
    ]
}