Поделиться через

Vulnerability information

Клиент 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.

Если вы планируете использовать данные об уязвимостях nuget.org в собственной реализации сервера NuGet, следует учитывать разработчиков, у которых нет прямого доступа к nuget.org. Дополнительные сведения см. в руководстве по реализации.

Versioning

Используются следующие @type значения:

Значение @type Notes
VulnerabilityInfo/6.7.0 Первоначальный выпуск

Vulnerability index

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

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

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

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

Vulnerability page

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

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

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

Список известных уязвимостей для пакета должен быть отсортирован в порядке убывания максимальной версии диапазона версий, за которой следует убывая версия минимальной версии, а затем по возрастанию URL-адреса. Диапазоны с минимальной или максимальной версией null (несвязанными) в диапазоне версий должны быть отсортированы до ненулевой (привязанной) версии.

Пустая страница, которая не предоставляет известных уязвимостей, должна быть пустым массивом JSON ([]).

Samples

Ниже приведен пример индекса уязвимости:

[
    {
        "@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)"
        }
    ]
}
  • Last updated on