Información de vulnerabilidades

El cliente NuGet, a partir de la versión 6.7, puede descargar información de vulnerabilidades conocidas de paquetes para usarla en escenarios como la comprobación de paquetes durante operaciones de restauración. Aunque el recurso de metadatos de paquetes también contiene información de vulnerabilidades conocidas, si una aplicación necesita comprobar un gran número de paquetes para detectar vulnerabilidades conocidas, es mucho más rápido descargar un archivo de vulnerabilidades conocidas y buscar localmente, en lugar de realizar un gran número de solicitudes HTTP. Por ejemplo, esto permite a NuGet Restore comprobar rápidamente paquetes restaurados para detectar vulnerabilidades conocidas, que históricamente nunca descargaron detalles de paquetes del recurso de metadatos de paquetes.

La API consta de al menos dos archivos, el índice de vulnerabilidades y uno o varios archivos de página de vulnerabilidades. Los datos de vulnerabilidades conocidas se pueden dividir en varios archivos y el índice de vulnerabilidades proporciona a los clientes información necesaria para almacenar en caché los archivos y actualizar la memoria caché de forma eficaz.

El recurso que se utiliza para generar esta URL es el recurso VulnerabilityInfo que se encuentra en el índice de servicio.

Estrategia de creación de particiones sugerida

Las páginas enumeradas en el índice de vulnerabilidades deben optimizarse idealmente para maximizar el almacenamiento en caché y, por lo tanto, minimizar las actualizaciones de archivos grandes. Esto permitirá a los clientes minimizar la frecuencia con la que necesita descargar actualizaciones.

Una estrategia sugerida para la creación de particiones de datos de vulnerabilidad es tener dos páginas base.json y updates.json. El archivo base.json se actualiza periódicamente (por ejemplo, una vez al mes) y contiene todas las vulnerabilidades conocidas en el momento en que se vuelve a generar el archivo. El archivo updates.json debe contener nuevos avisos publicados desde la última vez que se regeneró base.json. Esto permitirá a los clientes descargar el archivo base.json grande con poca frecuencia, mientras que el archivo updates.json que cambia con frecuencia se queda siempre con un tamaño relativamente pequeño.

Los clientes nuGet combinan los datos de varios archivos de forma aditiva y pueden cargar los archivos en cualquier orden. El esquema del archivo de datos no permite la modificación ni la redacción de vulnerabilidades conocidas de otro archivo. Por lo tanto, si el origen de datos de vulnerabilidades de un servidor (por ejemplo, la base de datos de avisos de GitHub) modifica un aviso existente, el servidor NuGet debe modificar la página en la que se publicó anteriormente la información de vulnerabilidades. Una manera de lograrlo con el esquema de partición sugerido es tratar todas las modificaciones y eliminaciones de vulnerabilidades como desencadenador para volver a generar el archivo base.json completo y vaciar updates.json.

Control de versiones

Se usan los siguientes valores @type:

Valor de @type	Notas
VulnerabilityInfo/6.7.0	La versión inicial

Índice de vulnerabilidades

El índice de vulnerabilidades es una matriz de objetos JSON que consta de las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
@name	string	sí	Nombre corto para el archivo, que se usa como clave de caché.
@id	string	sí	Dirección URL completa (absoluta) de un archivo de datos de vulnerabilidades.
@updated	string	sí	Cadena ISO 8601 que representa la fecha y hora en que se actualizó el archivo por última vez, idealmente con la zona horaria UTC.
comentario	string	no	Cadena descriptiva opcional.

Se aplican las restricciones que se indican a continuación:

• El índice debe ser una matriz de objetos con entre 1 y 16 elementos. Si el servidor no tiene ningún dato de vulnerabilidades (cero páginas), debe quitar el recurso VulnerabilityInfo de ServiceIndex.
• @name debe ser único dentro del índice, debe tener entre 1 y 32 caracteres de longitud y solo puede usar los caracteres de la A a la Z, de la a a la z, de 0 a 9, - o _.
• @id debe ser una dirección URL absoluta, no una dirección URL relativa.

Página de vulnerabilidades

Los archivos de página de vulnerabilidades son un objeto JSON que se usa como diccionario. Las claves de propiedad son el id. de paquete en minúsculas y los valores de propiedad son una matriz del objeto siguiente con las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
severity	integer	sí	0 significa bajo, 1 significa medio, 2 significa alto, 3 significa crítico.
url	string	sí	Dirección URL en la que los usuarios pueden obtener más información sobre la vulnerabilidad.
versions	string	sí	Intervalo de versiones vulnerable, usando la sintaxis del intervalo de versiones de NuGet.

Los identificadores de paquete (las claves del objeto raíz) deben estar en minúsculas con String.ToLowerInvariant.

La lista de vulnerabilidades conocidas de un paquete debe ordenarse en orden descendente desde la versión máxima del intervalo de versiones, seguida de la versión descendente de la versión mínima, seguida del orden ascendente de la dirección URL. Los intervalos con versiones mínimas o máximas nulas (sin enlazar) en un intervalo de versiones deben ordenarse antes de versiones que no sean nulas (enlazadas).

Una página vacía, una que no proporciona ninguna vulnerabilidad conocida, debe ser una matriz JSON vacía ([]).

Ejemplos

A continuación incluimos una muestra de un índice de vulnerabilidades:

[
    {
        "@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."
    }
]

A continuación incluimos una muestra de un archivo de datos de vulnerabilidades:

{
    "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)"
        }
    ]
}