Vulnerability information

NuGet-klienten, från version 6.7, kan ladda ned känd information om paketsårbarhet som ska användas i scenarier som att kontrollera paket under återställningsåtgärder. Paketmetadataresursen innehåller också känd sårbarhetsinformation, men om en app behöver kontrollera ett stort antal paket för kända sårbarheter är det mycket snabbare att ladda ned en fil med kända sårbarheter och uppslag lokalt i stället för att göra ett stort antal HTTP-begäranden. Detta gör det till exempel möjligt för NuGet-återställning att snabbt kontrollera återställda paket efter kända säkerhetsrisker, som tidigare aldrig laddade ned paketinformation från paketmetadataresursen.

API:et består av minst två filer, sårbarhetsindexet och en eller flera säkerhetssidefiler. Kända sårbarhetsdata kan partitioneras i flera filer, och sårbarhetsindexet ger klienter information som behövs för att cachelagrar filer och uppdaterar cachen effektivt.

Resursen som används för att skapa den här URL:en är den VulnerabilityInfo resurs som finns i -tjänstindexet.

Föreslagen partitioneringsstrategi

Sidorna som anges i sårbarhetsindexet bör helst optimeras för att maximera cachelagringen och därför minimera uppdateringar av stora filer. Detta gör det möjligt för klienter att minimera den frekvens som krävs för att ladda ned uppdateringar.

En föreslagen strategi för partitionering av sårbarhetsdata är att ha två sidor base.json och updates.json. Filen base.json uppdateras regelbundet (till exempel en gång i månaden) och innehåller alla kända säkerhetsrisker när filen återskapas. Filen updates.json bör innehålla alla nya rekommendationer som publicerats sedan base.json den senast återskapades. Detta gör det möjligt för klienter att ladda ned det stora base.json sällan, medan den ofta föränderliga updates.json filen alltid är relativt liten.

NuGet-klienter kombinerar data från flera filer additivt och kan läsa in filerna i valfri ordning. Datafilschemat tillåter inte ändring eller redigering av kända säkerhetsrisker från en annan fil. Om en servers sårbarhetsdatakälla (till exempel GitHub Advisories Database) ändrar en befintlig rekommendation, måste NuGet-servern därför ändra den sida som sårbarhetsinformationen tidigare rapporterades på. Ett sätt att uppnå detta med det föreslagna partitionsschemat är att behandla alla sårbarhetsändringar och borttagningar som en utlösare för att återskapa den fullständiga base.json filen och tömma updates.json.

Om du tänker använda nuget.org:s sårbarhetsdata i din egen NuGet-serverimplementering bör du ta hänsyn till utvecklare som inte har direkt åtkomst till nuget.org. Mer information finns i vår implementeringsguide.

Versioning

Följande @type värden används:

@type värde	Notes
VulnerabilityInfo/6.7.0	Den första versionen

Vulnerability index

Sårbarhetsindexet är en JSON-matris med objekt med följande egenskaper:

Name	Type	Required	Notes
@name	string	yes	Ett kort namn för filen, som används som en cachenyckel.
@id	string	yes	Den fullständiga (absoluta) URL:en till en sårbarhetsdatafil.
@updated	string	yes	En ISO 8601-sträng som representerar datum och tid då filen senast uppdaterades, helst med UTC-tidszonen.
comment	string	no	En valfri beskrivande sträng.

Följande begränsningar gäller:

• Indexet måste vara en matris med objekt med mellan 1 och 16 objekt. Om servern inte har några sårbarhetsdata (noll sidor) måste du ta bort resursen VulnerabilityInfoServiceIndexfrån .
• @name måste vara unikt i indexet, måste vara mellan 1 och 32 tecken långt och kan bara använda tecknen A till Z, a till z, 0 till 9, -eller _.
• @id måste vara en absolut URL, inte en relativ URL.

Vulnerability page

Filer för sårbarhetssidor är ett JSON-objekt som används som en ordlista. Egenskapsnycklar är det gemena paket-ID:t och egenskapsvärden är en matris med följande objekt med följande egenskaper:

Name	Type	Required	Notes
severity	integer	yes	0 betyder låg, 1 betyder medel, 2 betyder hög, 3 betyder kritisk.
url	string	yes	URL där användarna kan få mer information om säkerhetsrisken.
versions	string	yes	Det versionsintervall som är sårbart med hjälp av NuGets syntax för versionsintervall.

Paket-ID:t (rotobjektets nycklar) måste vara nedsänkta med String.ToLowerInvariant.

Listan över kända säkerhetsrisker för ett paket ska sorteras i fallande ordning efter den högsta versionen av versionsintervallet, följt av fallande version av min-versionen, följt av url:ens stigande ordning. Intervall med null min- eller maxversioner (obundna) i ett versionsintervall ska sorteras till före icke-null-versioner (avgränsade).

En tom sida, en sida som inte ger några kända säkerhetsrisker, måste vara en tom JSON-matris ([]).

Samples

Här är ett exempel på ett sårbarhetsindex:

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

Här är ett exempel på en säkerhetsriskdatafil:

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