使用英语阅读

通过


漏洞信息

NuGet 客户端(从版本 6.7 开始)可下载已知包漏洞信息,以便在还原操作期间检查包等场景中进行使用。 虽然包元数据资源还包含已知漏洞信息,但如果应用需针对已知漏洞检查大量包,则在本地下载已知漏洞和查找文件的速度要快得多,而不是发出大量 HTTP 请求。 例如,这可让 NuGet 还原针对已知漏洞快速检查已还原的包,而这些包过去从未从包元数据资源下载包详细信息。

API 包含至少两个文件,即漏洞索引以及一个或多个漏洞页文件。 已知漏洞数据可分区到多个文件中,而漏洞索引则可为客户端提供缓存文件所需的信息,并有效更新缓存。

用于生成此 URL 的资源是在服务索引中找到的 VulnerabilityInfo 资源。

建议的分区策略

最好优化漏洞索引中列出的页面以尽可能利用缓存功能,从而最大程度地减少对大型文件的更新。 这将允许客户端最大程度地减少必须下载更新的频率。

针对漏洞数据分区的建议策略是使用两个页面,即 base.jsonupdates.jsonbase.json 文件会定期更新(例如每月更新一次),且包含文件重新生成时的所有已知漏洞。 updates.json 文件应包含自上次重新生成 base.json 以来发布的所有新公告。 这将允许客户端较少下载大型 base.json,而频繁更改的 updates.json 的文件却始终相对较小。

NuGet 客户端可累加合并来自多个文件的数据,并可按任意顺序加载这些文件。 数据文件架构不允许修改或编辑来自其他文件的已知漏洞。 因此,如果服务器的漏洞数据源(例如 GitHub 公告数据库)修改现有公告,NuGet 服务器则须修改先前报告相关漏洞信息的页面。 使用建议的分区方案来实现此目的的其中一种方法是:将所有漏洞修改和删除视为重新生成完整的 base.json 文件和空的 updates.json

版本控制

使用了以下 @type 值:

值@type 说明
VulnerabilityInfo/6.7.0 初始版本

漏洞索引

漏洞索引是一个 JSON 数组,其中包含具有以下属性的对象:

名称 类型​​ 必须 注释
@name string 文件的短名称(用作缓存键)。
@id string 漏洞数据文件的完整(绝对)URL。
@updated string 一个 ISO 8601 字符串,表示文件的上次更新日期和时间(最好采用 UTC 时区)。
评论 string 可选描述性字符串。

存在以下限制:

  • 索引必须是包含 1 到 16 个项目的对象的数组。 如果服务器没有任何漏洞数据(零页面),则须从 ServiceIndex 删除 VulnerabilityInfo 资源。
  • @name 在索引中必须唯一,且长度必须介于 1 到 32 个字符之间,同时只能使用以下字符:AZaz09-_
  • @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)"
        }
    ]
}