弱點資訊
從 6.7 版開始的 NuGet 用戶端可以下載已知的套件弱點資訊,以在還原作業期間檢查套件時使用。 雖然套件元數據資源也包含已知的弱點資訊,但如果應用程式需要檢查大量套件是否有已知弱點,下載已知弱點檔案並在本機查閱,而不是進行大量的 HTTP 要求,會更快。 例如,這可讓 NuGet 還原快速檢查已還原的套件是否有已知弱點,這在歷史上從未從套件元數據資源下載套件詳細數據。
API 包含至少兩個檔案、 弱點索引 和一或多個 弱點頁面檔案。 已知弱點數據可以分割成多個檔案,而弱點索引會提供用戶端快取檔案所需的資訊,並有效率地更新快取。
用來建置此 URL 的資源是VulnerabilityInfo
服務索引中找到的資源。
最好優化弱點索引中列出的頁面,以最大化快取,因此將大型檔案的更新降到最低。 這可讓客戶端將下載更新所需的頻率降到最低。
弱點資料分割的建議策略是有兩個頁面和 base.json
updates.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
用於 、 到Z
0
z
、a
或 。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)"
}
]
}