漏洞信息

项目
12/19/2023

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

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

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

建议的分区策略

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

针对漏洞数据分区的建议策略是使用两个页面，即 base.json 和 updates.json。 base.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 个字符之间，同时只能使用以下字符：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)"
        }
    ]
}

漏洞信息

建议的分区策略

版本控制

漏洞索引

漏洞页

示例

反馈

反馈

其他资源