Сведения об уязвимостях
Клиент NuGet, начиная с версии 6.7, может скачать известные сведения об уязвимостях пакета для использования в таких сценариях, как проверка пакеты во время операций восстановления. Хотя ресурс метаданных пакета также содержит известные сведения об уязвимостях, если приложению необходимо проверка большое количество пакетов для известных уязвимостей, то гораздо быстрее скачать файл известных уязвимостей и подстановки локально, а не сделать большое количество HTTP-запросов. Например, это позволяет NuGet Restore быстро проверка восстановленные пакеты для известных уязвимостей, которые исторически никогда не скачали сведения о пакете из ресурса метаданных пакета.
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 | Примечания. |
---|---|
Уязвимость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
,a
0
вz
9
,-
или_
.@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)"
}
]
}