Informations sur la vulnérabilité

Article
12/22/2023

Le client NuGet, à partir de la version 6.7, peut télécharger des informations de vulnérabilité de package connues à utiliser dans des scénarios tels que la vérification de packages pendant les opérations de restauration. Bien que la ressource de métadonnées de package contienne également des informations de vulnérabilité connues, si une application doit vérifier un grand nombre de packages pour les vulnérabilités connues, il est beaucoup plus rapide de télécharger un fichier de vulnérabilités connues et de rechercher localement, plutôt que d’effectuer un grand nombre de demandes HTTP. Par exemple, cela permet à NuGet Restore de vérifier rapidement les packages restaurés pour les vulnérabilités connues, qui n’ont jamais téléchargé les détails du package à partir de la ressource de métadonnées du package.

L’API se compose d’au moins deux fichiers, de l’index de vulnérabilité et d’un ou plusieurs fichiers de page de vulnérabilité. Les données de vulnérabilité connues peuvent être partitionnés en plusieurs fichiers, et l’index de vulnérabilité fournit aux clients des informations nécessaires pour mettre en cache les fichiers et mettre à jour le cache, efficacement.

La ressource utilisée pour générer cette URL est la ressource VulnerabilityInfo trouvée dans l’index de service.

Stratégie de partitionnement suggérée

Les pages répertoriées dans l’index de vulnérabilité doivent idéalement être optimisées pour optimiser la mise en cache, et donc réduire les mises à jour des fichiers volumineux. Cela permet aux clients de réduire la fréquence à laquelle il doit télécharger les mises à jour.

Une stratégie suggérée pour le partitionnement des données de vulnérabilité consiste à avoir deux pages, base.json et updates.json. Le fichier base.json est mis à jour régulièrement (par exemple une fois par mois) et contient toutes les vulnérabilités connues au moment où le fichier est régénéré. Le fichier updates.json doit contenir les nouveaux avertissements publiés depuis que base.json a été regénéré pour la dernière fois. Cela permet aux clients de télécharger rarement le grand base.json, tandis que le fichier fréquemment modifié updates.json est toujours relativement petit.

Les clients NuGet combinent les données de plusieurs fichiers de manière additive et peuvent charger les fichiers dans n’importe quel ordre. Le schéma du fichier de données n’autorise pas la modification ou la rédaction d’une vulnérabilité connue à partir d’un autre fichier. Par conséquent, si la source de données de vulnérabilité d’un serveur (par exemple la base de données GitHub Advisories) modifie un avertissement existant, le serveur NuGet doit modifier la page que les informations de vulnérabilité ont été signalées précédemment. Pour ce faire, le schéma de partition suggéré consiste à traiter toutes les modifications et suppressions des vulnérabilités comme un déclencheur pour régénérer le fichier complet base.json et vide updates.json.

Contrôle de version

Les valeurs @type suivantes sont utilisées :

Valeur @type	Notes
VulnerabilityInfo/6.7.0	La version initiale

Index de vulnérabilité

L’index de vulnérabilité est un tableau JSON d’objets avec les propriétés suivantes :

Nom	Type	Requise	Notes
@name	string	Oui	Nom court du fichier, utilisé comme clé de cache.
@id	string	Oui	URL complète (absolue) d’un fichier de données de vulnérabilité.
@updated	string	Oui	Chaîne ISO 8601 représentant la date et l’heure de la dernière mise à jour du fichier, idéalement avec le fuseau horaire UTC.
commentaire	string	non	Chaîne descriptive facultative.

Les restrictions suivantes s’appliquent :

L’index doit être un tableau d’objets comportant entre 1 et 16 articles. Si le serveur n’a pas de données de vulnérabilité (pages zéro), vous devez supprimer la ressource VulnerabilityInfo de ServiceIndex.
@name doit être unique dans l’index, doit être compris entre 1 et 32 caractères, et ne peut utiliser que les caractères A pour Z, a pour z, 0 vers 9, -ou _.
@id doit être une URL absolue, et non une URL relative.

Page de vulnérabilité

Les fichiers de page de vulnérabilité sont un objet JSON utilisé comme ensemble de clés. Les clés de propriété sont l’ID de package minuscule et les valeurs de propriété sont un tableau de l’objet suivant avec les propriétés suivantes :

Nom	Type	Requise	Notes
severity	entier	Oui	0 signifie faible, 1 signifie moyen, 2 signifie élevé, 3 signifie critique.
url	string	Oui	URL dans laquelle les utilisateurs peuvent obtenir plus d’informations sur la vulnérabilité.
versions	string	Oui	Plage de versions vulnérable, à l’aide de la syntaxe de la plage de versions de NuGet.

Les ID de package (clés de l’objet racine) doivent être en minuscules avec String.ToLowerInvariant.

La liste des vulnérabilités connues pour un package doit être triée dans l’ordre décroissant de la version maximale de la plage de versions, suivie de la version décroissante de la version min, suivie de l’ordre croissant de l’URL. Les plages avec des versions minimales ou maximales nulles (non liées) dans une plage de versions doivent être triées avant les versions non nulles (limitées).

Une page vide, qui ne fournit aucune vulnérabilité connue, doit être un tableau JSON vide ([]).

Exemples

Voici un exemple d’index de vulnérabilité :

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

Voici un exemple de fichier de données de vulnérabilité :

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