脆弱性情報

[アーティクル]
12/26/2023

NuGet クライアント (バージョン 6.7 以降) では、既知のパッケージの脆弱性情報をダウンロードして、復元操作中のパッケージのチェックなどのシナリオで使用できます。パッケージメタデータリソースには既知の脆弱性情報も含まれていますが、多数のパッケージに対してアプリで既知の脆弱性がないかどうかチェックする必要がある場合は、多数の HTTP 要求を行うよりも、既知の脆弱性のファイルをダウンロードしてローカルで検索する方がはるかに高速です。たとえば、NuGet 復元で、これまでパッケージメタデータリソースからパッケージの詳細をダウンロードしなかったとしても、これを実行することにより、復元されたパッケージに既知の脆弱性がないかすばやくチェックできるようになります。

この API は、脆弱性インデックスと 1 つ以上の脆弱性ページファイルという少なくとも 2 つのファイルで構成されます。既知の脆弱性データは複数のファイルにパーティション分割でき、脆弱性インデックスは、ファイルのキャッシュとキャッシュの更新を効率的に行うために必要な情報をクライアントに提供します。

この URL の構築に使用されるリソースは、サービスインデックスにある VulnerabilityInfo リソースです。

推奨されるパーティション分割戦略

脆弱性インデックスに記載されるページは、キャッシュを最大化するように最適化され、その結果、大きなファイルへの更新が最小限に抑えられる状態になるのが理想的です。これにより、クライアントでは更新をダウンロードする頻度を最小限に抑えることができます。

脆弱性データのパーティション分割の推奨される戦略は、base.json と updates.json の 2 つのページを使用することです。 base.json ファイルは定期的に更新され (1 か月に 1 回など)、ファイルが再生成された時点での既知の脆弱性をすべて含んでいます。 updates.json ファイルには、base.json が最後に再生成されて以降に発行された新しいアドバイザリが含まれている必要があります。これにより、クライアントでは大きいサイズの base.json をダウンロードする頻度を少なくできますが、頻繁に変更される updates.json ファイルは常に比較的小さいサイズになります。

NuGet クライアントは、複数のファイルのデータを追加的に結合し、任意の順序でファイルを読み込むことができます。データファイルスキーマでは、別のファイルの既知の脆弱性を変更または編集することはできません。そのため、サーバーの脆弱性データソース (GitHub Advisories Database など) が既存のアドバイザリを変更する場合、NuGet サーバーで脆弱性情報が以前に報告されたページを変更する必要があります。推奨されるパーティション構成でこれを実現する方法の 1 つは、すべての脆弱性の変更と削除を、完全な base.json ファイルと空の updates.json を再生成するトリガーとして扱うことです。

バージョン管理

次の @type の値が使用されます。

@type 値	メモ
VulnerabilityInfo/6.7.0	初期リリース

脆弱性インデックス

脆弱性インデックスは、次のプロパティを持つオブジェクトの JSON 配列となります。

名前	タイプ	必須	メモ
@name	string	はい	キャッシュキーとして使用される、ファイルの短い名前。
@id	string	はい	脆弱性データファイルの完全な (絶対) URL。
@updated	string	はい	ファイルが最後に更新された日時 (理想的には UTC タイムゾーン) を表す ISO 8601 文字列。
comment	string	いいえ	省略可能な説明文字列。

次の制限事項が適用されます。

インデックスは、1 個から 16 個の項目を持つオブジェクトの配列である必要があります。サーバーに脆弱性データがない場合 (ページがゼロ)、ServiceIndex から VulnerabilityInfo リソースを削除する必要があります。
@name は、インデックス内で一意である必要があり、1 文字から 32 文字の長さにする必要があります。また、使用できる文字は、A から Z、a から z、0 から 9、-、または _ に限られます。
@id は、相対 URL ではなく絶対 URL である必要があります。

脆弱性ページ

脆弱性ページファイルは、ディクショナリとして使用される JSON オブジェクトです。プロパティキーは小文字のパッケージ ID であり、プロパティ値は次のプロパティを持つ次のオブジェクトの配列になります。

名前	タイプ	必須	メモ
severity	integer	はい	0 は低、1 は中、2 は高、3 はクリティカルを意味します。
URL	string	はい	ユーザーが脆弱性に関する詳細情報を取得できる URL。
versions	string	はい	NuGet のバージョン範囲構文を使用した、脆弱なバージョン範囲。

パッケージ ID (ルートオブジェクトのキー) は String.ToLowerInvariant で小文字にする必要があります。

パッケージの既知の脆弱性の一覧は、バージョン範囲の最大バージョンの降順、次に最小バージョンの降順、最後に URL の昇順で並べ替える必要があります。バージョン範囲内で null の最小バージョンまたは最大バージョン (制限なし) が含まれる範囲は、非 null (制限あり) バージョンの前に並べ替える必要があります。

空のページ、つまり既知の脆弱性を提供しないページは、空の JSON 配列 ([]) である必要があります。

サンプル

脆弱性インデックスのサンプルを次に示します。

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

脆弱性データファイルのサンプルを次に示します。

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

次の方法で共有