閱讀英文

共用方式為


弱點資訊

從 6.7 版開始的 NuGet 用戶端可以下載已知的套件弱點資訊,以在還原作業期間檢查套件時使用。 雖然套件元數據資源也包含已知的弱點資訊,但如果應用程式需要檢查大量套件是否有已知弱點,下載已知弱點檔案並在本機查閱,而不是進行大量的 HTTP 要求,會更快。 例如,這可讓 NuGet 還原快速檢查已還原的套件是否有已知弱點,這在歷史上從未從套件元數據資源下載套件詳細數據。

API 包含至少兩個檔案、 弱點索引 和一或多個 弱點頁面檔案。 已知弱點數據可以分割成多個檔案,而弱點索引會提供用戶端快取檔案所需的資訊,並有效率地更新快取。

用來建置此 URL 的資源是VulnerabilityInfo服務索引中找到的資源。

建議的數據分割策略

最好優化弱點索引中列出的頁面,以最大化快取,因此將大型檔案的更新降到最低。 這可讓客戶端將下載更新所需的頻率降到最低。

弱點資料分割的建議策略是有兩個頁面和 base.jsonupdates.json。 檔案 base.json 會定期更新(例如每月一次),並在重新產生檔案時包含所有已知的弱點。 檔案 updates.json 應該包含自上次重新產生之後 base.json 所發佈的任何新諮詢。 這可讓用戶端不常下載大型 base.json 檔案,而經常變更 updates.json 的檔案一律相對較小。

NuGet 用戶端會加總結合多個檔案中的數據,而且可以依任何順序載入檔案。 數據文件架構不允許修改或修訂來自另一個檔案的已知弱點。 因此,如果伺服器的弱點數據源(例如 GitHub Advisories Database)修改現有的諮詢,NuGet 伺服器必須修改先前報告的弱點資訊頁面。 使用建議的數據分割配置達成此目的的其中一種方法,就是將所有弱點修改和刪除視為重新產生完整 base.json 檔案的觸發程式,以及空白 updates.json

版本控制

使用下列 @type 值:

@type 值 備註
VulnerabilityInfo/6.7.0 初始版本

弱點索引

弱點索引是具有下列屬性的物件 JSON 陣列:

名稱 類型​​ 必要 備註
@name string 作為快取索引鍵的檔案簡短名稱。
@id string 弱點數據檔的完整 (絕對) URL。
@updated string ISO 8601 字串,代表檔案上次更新的日期和時間,最好是使用 UTC 時區。
comment string 選擇性的描述性字串。

適用以下限制:

  • 索引必須是介於1到16個專案的物件陣列。 如果伺服器沒有任何弱點數據(零頁),則必須從 ServiceIndex移除VulnerabilityInfo資源。
  • @name在索引內必須是唯一的,長度必須介於 1 到 32 個字元之間,而且只能將字元A用於 、 到 Z0za 或 。9-_
  • @id 必須是絕對 URL,而非相對 URL。

弱點頁面

弱點頁面檔案是用來做為字典的 JSON 物件。 屬性索引鍵是小寫套件識別碼,而屬性值是下列對象的陣列,具有下列屬性:

名稱 類型​​ 必要 備註
severity 整數 0 表示低,1 表示中,2 表示高,3 表示關鍵。
URL string 使用者可以取得弱點詳細資訊的 URL。
versions string 使用 NuGet 版本範圍語法,易受攻擊的版本範圍。

套件識別碼(根物件的索引鍵)必須使用 小寫。String.ToLowerInvariant

套件的已知弱點列表應該以版本範圍上限版本的遞減順序排序,後面接著最小版本的遞減版本,後面接著URL的遞增順序。 版本範圍中具有 null min 或 max 版本 (unbounded) 的範圍,應該在非 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)"
        }
    ]
}