Vulnerability information

O cliente NuGet, a partir da versão 6.7, pode baixar informações conhecidas de vulnerabilidade do pacote para usar em cenários como verificar 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 para vulnerabilidades conhecidas, é muito mais rápido baixar um arquivo de vulnerabilidades conhecidas e pesquisa localmente, em vez de fazer um grande número de 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. Dados de vulnerabilidade conhecidos podem ser particionados em vários arquivos e o índice de vulnerabilidade fornece aos clientes informações necessárias para armazenar arquivos em cache e atualizar o cache com eficiência.

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

Estratégia de particionamento sugerida

As páginas listadas no índice de vulnerabilidade devem ser otimizadas idealmente 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 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 arquivo deve conter novos avisos publicados desde base.json a última regeneração. Isso permitirá que os clientes baixem o grande base.json com pouca frequência, enquanto o arquivo de alteração updates.json frequente é sempre relativamente pequeno.

Os clientes NuGet combinam os dados de vários arquivos de forma aditiva e podem carregar os arquivos em qualquer ordem. O esquema de arquivo de dados não permite modificação ou redaçã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 aviso existente, o servidor NuGet deverá modificar a página em que as informações de vulnerabilidade foram relatadas anteriormente. Uma maneira de fazer 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 vazio updates.json.

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

Versioning

Os seguintes valores de @type são usados:

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.
• @name deve ser exclusivo dentro do índice, deve ter entre 1 e 32 caracteres e só pode usar os caracteres A para Z, a para z, 0 para 9, -ou _.
• @id deve ser uma URL absoluta, não uma URL relativa.

Vulnerability page

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 de minúsculas e os valores de propriedade são uma matriz do seguinte objeto com as seguintes propriedades:

As IDs do pacote (as chaves do objeto raiz) devem ser reduzidas com String.ToLowerInvariant.

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

Uma página vazia, que não fornece nenhuma vulnerabilidade conhecida, 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)"
        }
    ]
}