Vulnerability information

A NuGet-ügyfél a 6.7-es verziótól kezdve letöltheti az ismert csomag sebezhetőségi adatait, hogy olyan helyzetekben használhassa, mint például a csomagok ellenőrzése a visszaállítási műveletek során. Bár a csomag metaadat-erőforrása ismert biztonsági résadatokat is tartalmaz, ha egy alkalmazásnak nagy számú csomagot kell ellenőriznie az ismert biztonsági résekre vonatkozóan, sokkal gyorsabban tölthet le egy ismert biztonsági réseket tartalmazó fájlt, és helyileg kereshet, nem pedig nagy számú HTTP-kérést. Ez lehetővé teszi például, hogy a NuGet Restore gyorsan ellenőrizze a visszaállított csomagokat az ismert biztonsági rések esetében, amelyek korábban soha nem töltötték le a csomag részleteit a csomag metaadat-erőforrásából.

Az API legalább két fájlból, a biztonságirés-indexből és egy vagy több sebezhetőségi lapfájlból áll. Az ismert biztonságirés-adatok több fájlba particionálhatók, a biztonságirés-index pedig hatékonyan biztosítja az ügyfelek számára a fájlok gyorsítótárazásához és a gyorsítótár hatékony frissítéséhez szükséges információkat.

Az URL-cím létrehozásához használt erőforrás a VulnerabilityInfotalálható erőforrás.

Javasolt particionálási stratégia

A biztonságirés-indexben felsorolt lapokat ideális esetben úgy kell optimalizálni, hogy maximalizálják a gyorsítótárazást, és ezáltal minimalizálják a nagyméretű fájlok frissítéseit. Ez lehetővé teszi, hogy az ügyfelek minimalizálják a frissítések letöltésének gyakoriságát.

A biztonságirés-adatok particionálásának javasolt stratégiája, hogy két oldallal base.jsonupdates.jsonés . A base.json fájl rendszeresen frissül (például havonta egyszer), és a fájl újragenerálásának időpontjában minden ismert biztonsági rést tartalmaz. A updates.json fájlnak tartalmaznia kell a legutóbbi újragenerálás óta base.json közzétett új tanácsadásokat. Ez lehetővé teszi, hogy az ügyfelek ritkán töltsék le a nagy base.json méretű fájlokat, míg a gyakran változó updates.json fájl mindig viszonylag kicsi.

A NuGet-ügyfelek összevonják a több fájlból származó adatokat, és bármilyen sorrendben betölthetik a fájlokat. Az adatfájlséma nem teszi lehetővé egy másik fájl ismert biztonsági résének módosítását vagy újbóli módosítását. Ezért ha egy kiszolgáló biztonságirés-adatforrása (például a GitHub Advisories Database) módosít egy meglévő tanácsadást, a NuGet-kiszolgálónak módosítania kell azt a lapot, amelyen a biztonságirés-információk korábban jelentek meg. Ezt a javasolt partíciós sémával úgy érheti el, hogy az összes biztonságirés-módosítást és -törlést eseményindítóként kezeli a teljes base.json fájl újragenerálásához, és üres updates.json.

Ha a nuget.org biztonságirés-adatait a saját NuGet-kiszolgáló implementációjában szeretné használni, vegye figyelembe azokat a fejlesztőket, akik nem rendelkeznek közvetlen hozzáféréssel a nuget.org. További részletekért tekintse meg a megvalósítási útmutatót.

Versioning

A rendszer a következő @type értékeket használja:

@type érték Notes
VulnerabilityInfo/6.7.0 A kezdeti kiadás

Vulnerability index

A biztonságirés-index az objektumok JSON-tömbje a következő tulajdonságokkal:

Name Típus Required Notes
@name karakterlánc yes A fájl rövid neve, amelyet gyorsítótárkulcsként használnak.
@id karakterlánc yes A biztonságirés-adatfájl teljes (abszolút) URL-címe.
@updated karakterlánc yes Egy ISO 8601 sztring, amely a fájl utolsó frissítésének dátumát és időpontját jelöli, ideális esetben az UTC időzónával.
hozzászólás karakterlánc no Választható leíró sztring.

A következő korlátozások érvényesek:

  • Az indexnek 1 és 16 elem közötti objektumtömbnek kell lennie. Ha a kiszolgáló nem rendelkezik biztonsági résadatokkal (nulla oldal), akkor el kell távolítania az erőforrást a VulnerabilityInfoServiceIndex.
  • @name az indexen belül egyedinek kell lennie, 1 és 32 karakter közötti hosszúságúnak kell lennie, és csak a karaktereket AZhasználhatja a , a a zto , 0 a 9, -vagy _a .
  • @id abszolút URL-címnek kell lennie, nem relatív URL-címnek.

Vulnerability page

A biztonságirés-lapfájlok szótárként használt JSON-objektumok. A tulajdonságkulcsok a kisbetűs csomagazonosítók, a tulajdonságértékek pedig a következő objektum tömbje, a következő tulajdonságokkal:

Name Típus Required Notes
severity egész szám yes 0 azt jelenti, alacsony, 1 közepes, 2 azt jelenti, magas, 3 azt jelenti, kritikus.
url karakterlánc yes URL-cím, ahol a felhasználók további információkat kaphatnak a biztonsági résről.
versions karakterlánc yes A sebezhető verziótartomány a NuGet verziótartomány-szintaxisával.

A csomagazonosítóknak (a gyökérobjektum kulcsainak) kisbetűvel kell rendelkeznie String.ToLowerInvariant.

A csomagok ismert biztonsági réseinek listáját a verziótartomány maximális verziójának csökkenő sorrendje szerint kell rendezni, majd a minimális verzió csökkenő verzióját, majd az URL-cím növekvő sorrendjét. A null minimális vagy a maximális (nem kötött) verziójú tartományokat a nem null értékű (határolt) verziók előtt kell rendezni.

Az üres lapnak, amely nem biztosít ismert biztonsági réseket, üres JSON-tömbnek ([]) kell lennie.

Samples

Íme egy biztonságirés-index mintája:

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

Íme egy biztonságirés-adatfájl mintája:

{
    "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)"
        }
    ]
}
  • Last updated on