英語で読む

次の方法で共有


脆弱性情報

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

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

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

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

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

脆弱性データのパーティション分割の推奨される戦略は、base.jsonupdates.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 から Za から z0 から 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)"
        }
    ]
}