Informazioni sulla vulnerabilità

Il client NuGet, a partire dalla versione 6.7, può scaricare informazioni note sulla vulnerabilità del pacchetto da usare in scenari come il controllo dei pacchetti durante le operazioni di ripristino. Sebbene la risorsa di metadati del pacchetto contenga anche informazioni sulle vulnerabilità note, se un'app deve controllare un numero elevato di pacchetti per individuare vulnerabilità note, è molto più veloce scaricare un file di vulnerabilità note e ricerca in locale, anziché effettuare un numero elevato di richieste HTTP. Ad esempio, ciò consente a NuGet Restore di controllare rapidamente i pacchetti ripristinati per individuare vulnerabilità note, che storicamente non hanno mai scaricato i dettagli del pacchetto dalla risorsa dei metadati del pacchetto.

L'API è costituita da almeno due file, l'indice di vulnerabilità e uno o più file di pagine di vulnerabilità. I dati di vulnerabilità noti possono essere partizionati in più file e l'indice di vulnerabilità fornisce ai client informazioni necessarie per memorizzare nella cache i file e aggiornare la cache in modo efficiente.

La risorsa usata per la compilazione di questo URL è la VulnerabilityInfo risorsa presente nell'indice del servizio.

Strategia di partizionamento suggerita

Le pagine elencate nell'indice di vulnerabilità devono essere idealmente ottimizzate per ottimizzare la memorizzazione nella cache e quindi ridurre al minimo gli aggiornamenti ai file di grandi dimensioni. Ciò consentirà ai client di ridurre al minimo la frequenza necessaria per scaricare gli aggiornamenti.

Una strategia consigliata per il partizionamento dei dati delle vulnerabilità consiste nell'avere due pagine e base.jsonupdates.json. Il base.json file viene aggiornato periodicamente (ad esempio una volta al mese) e contiene tutte le vulnerabilità note al momento della rigenerazione del file. Il updates.json file deve contenere eventuali nuovi avvisi pubblicati dopo base.json l'ultima rigenerazione. Ciò consentirà ai client di scaricare raramente il file di grandi dimensioni base.json , mentre il file di modifica updates.json frequente è sempre relativamente piccolo.

I client NuGet combinano i dati di più file in modo aggiuntivo e possono caricare i file in qualsiasi ordine. Lo schema del file di dati non consente la modifica o l'annullamento di vulnerabilità note da un altro file. Pertanto, se l'origine dati della vulnerabilità di un server (ad esempio il database di avvisi GitHub) modifica un avviso esistente, il server NuGet deve modificare la pagina segnalata in precedenza dalle informazioni sulla vulnerabilità. Un modo per ottenere questo risultato con lo schema di partizione suggerito consiste nel considerare tutte le modifiche ed eliminazioni delle vulnerabilità come trigger per rigenerare il file completo base.json e vuoto updates.json.

Controllo delle versioni

Vengono usati i valori seguenti @type :

Valore @type	Note
VulnerabilityInfo/6.7.0	Versione iniziale

Indice di vulnerabilità

L'indice di vulnerabilità è una matrice JSON di oggetti con le proprietà seguenti:

Nome	Digita	Obbligatorio	Note
@name	string	yes	Nome breve per il file, usato come chiave della cache.
@id	string	yes	URL completo (assoluto) di un file di dati di vulnerabilità.
@updated	string	yes	Stringa ISO 8601 che rappresenta la data e l'ora dell'ultimo aggiornamento del file, idealmente con il fuso orario UTC.
commento	string	no	Stringa descrittiva facoltativa.

Si applicano le seguenti restrizioni:

• L'indice deve essere una matrice di oggetti con una lunghezza compresa tra 1 e 16 elementi. Se nel server non sono presenti dati di vulnerabilità (zero pagine), è necessario rimuovere la VulnerabilityInfo risorsa da ServiceIndex.
• @name deve essere univoco all'interno dell'indice, deve avere una lunghezza compresa tra 1 e 32 caratteri e può usare solo i caratteri A da Z, a a z, 0 a 9, -o _.
• @id deve essere un URL assoluto, non un URL relativo.

Pagina vulnerabilità

I file di pagina della vulnerabilità sono un oggetto JSON usato come dizionario. Le chiavi delle proprietà sono l'ID pacchetto minuscolo e i valori delle proprietà sono una matrice dell'oggetto seguente con le proprietà seguenti:

Nome	Digita	Obbligatorio	Note
severity	integer	yes	0 significa basso, 1 significa medio, 2 significa alto, 3 significa critico.
URL.	string	yes	URL in cui gli utenti possono ottenere altre informazioni sulla vulnerabilità.
versions	string	yes	Intervallo di versioni vulnerabile, usando la sintassi dell'intervallo di versioni di NuGet.

Gli ID pacchetto (chiavi dell'oggetto radice) devono essere in minuscolo con String.ToLowerInvariant.

L'elenco delle vulnerabilità note per un pacchetto deve essere ordinato in ordine decrescente della versione massima dell'intervallo di versioni, seguito dalla versione decrescente della versione minima, seguita dall'ordine crescente dell'URL. Gli intervalli con versioni null min o max (senza vincoli) in un intervallo di versioni devono essere ordinati prima delle versioni non Null (delimitate).

Una pagina vuota, una che non fornisce vulnerabilità note, deve essere una matrice JSON vuota ([]).

Esempi

Di seguito è riportato un esempio di indice di vulnerabilità:

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

Di seguito è riportato un esempio di file di dati di vulnerabilità:

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