Сведения об уязвимостях

Статья
10/23/2023

Клиент NuGet, начиная с версии 6.7, может скачать известные сведения об уязвимостях пакета для использования в таких сценариях, как проверка пакеты во время операций восстановления. Хотя ресурс метаданных пакета также содержит известные сведения об уязвимостях, если приложению необходимо проверка большое количество пакетов для известных уязвимостей, то гораздо быстрее скачать файл известных уязвимостей и подстановки локально, а не сделать большое количество HTTP-запросов. Например, это позволяет NuGet Restore быстро проверка восстановленные пакеты для известных уязвимостей, которые исторически никогда не скачали сведения о пакете из ресурса метаданных пакета.

API состоит по крайней мере из двух файлов, индекса уязвимостей и одного или нескольких файлов страниц уязвимостей. Известные данные уязвимостей можно разделить на несколько файлов, а индекс уязвимостей предоставляет клиентам информацию, необходимую для кэширования файлов, и эффективно обновлять кэш.

Ресурс, используемый для создания этого URL-адреса, является ресурсомVulnerabilityInfo, найденным в индексе службы.

Рекомендуемая стратегия секционирования

Страницы, перечисленные в индексе уязвимостей, в идеале должны быть оптимизированы для максимальной оптимизации кэширования и, следовательно, свести к минимуму обновления больших файлов. Это позволит клиентам свести к минимуму частоту загрузки обновлений.

Рекомендуемая стратегия секционирования данных уязвимостей заключается в наличии двух страниц и base.jsonupdates.json. Файл base.json периодически обновляется (например, один раз в месяц) и содержит все известные уязвимости во время повторного создания файла. Файл updates.json должен содержать все новые рекомендации, опубликованные с момента base.json последнего повторного создания. Это позволит клиентам скачивать большой base.json редко, в то время как часто изменяющийся updates.json файл всегда относительно мал.

Клиенты NuGet объединяют данные из нескольких файлов и могут загружать файлы в любом порядке. Схема файла данных не разрешает изменение или изменение известной уязвимости из другого файла. Таким образом, если источник данных уязвимостей сервера (например, база данных Помощников по GitHub) изменяет существующие рекомендации, сервер NuGet должен изменить страницу, в которую ранее сообщались сведения об уязвимостях. Один из способов добиться этого с помощью предлагаемой схемы секционирования — рассматривать все изменения уязвимостей и удаления в качестве триггера для повторного создания полного base.json файла и пустого updates.json.

Управление версиями

Допустимы следующие значения @type:

Значение @type	Примечания.
УязвимостьInfo/6.7.0	Начальный выпуск

Индекс уязвимостей

Индекс уязвимости — это массив объектов JSON со следующими свойствами:

Имя.	Type	Обязательное поле	Примечания.
@name	строка	yes	Короткое имя файла, используемое в качестве ключа кэша.
@id	строка	yes	Полный (абсолютный) URL-адрес файла данных уязвимости.
@updated	строка	yes	Строка ISO 8601, представляющая дату и время последнего обновления файла, в идеале с часовым поясом UTC.
Комментарий	строка	no	Необязательная описательная строка.

Применяются следующие ограничения:

Индекс должен быть массивом объектов в диапазоне от 1 до 16 элементов. Если у сервера нет данных об уязвимостях (ноль страниц), необходимо удалить VulnerabilityInfo ресурс из него ServiceIndex.
@nameдолжен быть уникальным в индексе, должен иметь длину от 1 до 32 символов, и может использовать только символы A для , для Z, a0 в z9, -или _.
@id должен быть абсолютным URL-адресом, а не относительным URL-адресом.

Страница уязвимостей

Файлы страниц уязвимости — это объект JSON, используемый в качестве словаря. Ключи свойств — это идентификатор пакета нижнего регистра и значения свойств — это массив следующего объекта со следующими свойствами:

Имя.	Type	Обязательное поле	Примечания.
severity	integer	yes	0 означает низкий, 1 означает средний, 2 означает высокий, 3 означает критические.
URL-адрес	строка	yes	URL-адрес, где пользователи могут получить дополнительные сведения об уязвимости.
версии	строка	yes	Диапазон версий, который уязвим, используя синтаксис диапазона версий NuGet.

Идентификаторы пакетов (ключи корневого объекта) должны быть строчными буквами String.ToLowerInvariant.

Список известных уязвимостей для пакета должен быть отсортирован в порядке убывания максимальной версии диапазона версий, за которой следует убывая версия минимальной версии, а затем по возрастанию URL-адреса. Диапазоны с минимальной или максимальной версией 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)"
        }
    ]
}