Vulnerability information

Klient NuGet, počínaje verzí 6.7, si může stáhnout známé informace o ohrožení zabezpečení balíčku, které se mají použít ve scénářích, jako je kontrola balíčků během operací obnovení. I když prostředek metadat balíčku obsahuje také známé informace o ohrožení zabezpečení, pokud aplikace potřebuje zkontrolovat velký počet balíčků známých ohrožení zabezpečení, je mnohem rychlejší stáhnout soubor známých ohrožení zabezpečení a vyhledávání místně, a ne vytvářet velký počet požadavků HTTP. To například umožňuje obnovení NuGet rychle zkontrolovat obnovené balíčky kvůli známým chybám zabezpečení, které se historicky nikdy nestáhnou z prostředku metadat balíčku.

Rozhraní API se skládá z nejméně dvou souborů, indexu ohrožení zabezpečení a jednoho nebo více souborů stránky ohrožení zabezpečení. Známá data ohrožení zabezpečení je možné rozdělit do několika souborů a index ohrožení zabezpečení poskytuje klientům informace potřebné k ukládání souborů do mezipaměti a efektivní aktualizaci mezipaměti.

Prostředek použitý k sestavení této adresy URL je prostředek VulnerabilityInfo nalezený v indexu služby.

Navržená strategie dělení

Stránky uvedené v indexu ohrožení zabezpečení by měly být v ideálním případě optimalizovány tak, aby maximalizovaly ukládání do mezipaměti, a proto minimalizovaly aktualizace velkých souborů. To umožní klientům minimalizovat frekvenci stahování aktualizací.

Navržená strategie dělení dat z hlediska ohrožení zabezpečení je mít dvě stránky a base.jsonupdates.json. Soubor base.json se pravidelně aktualizuje (například jednou za měsíc) a obsahuje všechna známá ohrožení zabezpečení v době opětovného vygenerování souboru. Soubor updates.json by měl obsahovat všechny nové poradce publikované od base.json posledního opětovného generování. To umožní klientům stahovat velké base.json zřídka, zatímco často se měnící updates.json soubor je vždy relativně malý.

Klienti NuGet kombinují data z více souborů a mohou načítat soubory v libovolném pořadí. Schéma datového souboru neumožňuje úpravy ani redakci známé chyby zabezpečení z jiného souboru. Proto pokud zdroj dat ohrožení zabezpečení serveru (například databáze GitHub Advisories) upraví existující poradce, server NuGet musí upravit stránku, na které byly dříve nahlášeny informace o ohrožení zabezpečení. Jedním ze způsobů, jak toho dosáhnout pomocí navrhovaného schématu oddílů, je zacházet se všemi úpravami a odstraněními ohrožení zabezpečení jako s triggerem pro opětovné vygenerování celého base.json souboru a prázdné updates.json.

Pokud máte v úmyslu použít data ohrožení zabezpečení nuget.org ve vlastní implementaci serveru NuGet, měli byste vzít v úvahu vývojáře, kteří nemají přímý přístup k nuget.org. Další podrobnosti najdete v našem průvodci implementací.

Versioning

Používají se následující @type hodnoty:

@type hodnota	Notes
VulnerabilityInfo/6.7.0	Počáteční verze

Vulnerability index

Index ohrožení zabezpečení je pole objektů JSON s následujícími vlastnostmi:

Name	Typ	Required	Notes
@name	řetězec	yes	Krátký název souboru, který se používá jako klíč mezipaměti.
@id	řetězec	yes	Úplná (absolutní) adresa URL datového souboru ohrožení zabezpečení.
@updated	řetězec	yes	Řetězec ISO 8601 představující datum a čas poslední aktualizace souboru, ideálně s časovým pásmem UTC.
komentář	řetězec	no	Volitelný popisný řetězec.

Platí následující omezení:

• Index musí být pole objektů s 1 až 16 položkami. Pokud server neobsahuje žádná data o ohrožení zabezpečení (nula stránek), je nutné prostředek z prostředku ServiceIndexodebrat VulnerabilityInfo .
• @namemusí být jedinečný v rámci indexu, musí mít délku 1 až 32 znaků a může používat pouze znaky A k Z, a do z0 , do 9, -nebo _.
• @id musí být absolutní adresa URL, nikoli relativní adresa URL.

Vulnerability page

Soubory stránek ohrožení zabezpečení jsou objekt JSON používaný jako slovník. Klíče vlastností jsou ID balíčku s menším písmenem a hodnoty vlastností jsou pole následujícího objektu s následujícími vlastnostmi:

Name	Typ	Required	Notes
severity	integer	yes	0 znamená nízké, 1 znamená střední, 2 znamená vysoké, 3 znamená kritické.
url	řetězec	yes	Adresa URL, kde můžou uživatelé získat další informace o ohrožení zabezpečení
versions	řetězec	yes	Rozsah verzí, který je ohrožený, pomocí syntaxe rozsahu verzí NuGetu.

ID balíčků (klíče kořenového objektu) musí být s nižšími písmeny String.ToLowerInvariant.

Seznam známých ohrožení zabezpečení balíčku by se měl seřadit sestupně podle maximální verze rozsahu verzí, po kterém následuje sestupná verze minimální verze následovaná vzestupným pořadím adresy URL. Rozsahy s minimálními nebo maximálními verzemi null (nevázanými) v rozsahu verzí by se měly řadit před nenulovými (ohraničenými) verzemi.

Prázdná stránka, která neposkytuje žádná známá ohrožení zabezpečení, musí být prázdné pole JSON ([]).

Samples

Tady je ukázka indexu ohrožení zabezpečení:

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

Tady je ukázka datového souboru ohrožení zabezpečení:

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