Рекомендации по написанию рекомендаций по безопасности репозитория

Любой пользователь с разрешениями администратора на общедоступный репозиторий может создавать и изменять рекомендации по безопасности.

Note

Если вы являетесь исследователем безопасности, вы должны напрямую связаться с сотрудниками, чтобы попросить их создать советы по безопасности или выдавать cvEs от вашего имени в репозиториях, которые вы не администрируете. Однако если для репозитория включена частная отчетность об уязвимостях, вы можете самостоятельно сообщить об уязвимости. Дополнительные сведения см. в разделе Приватный отчет об уязвимости безопасности.

Сведения о рекомендациях по безопасности для репозиториев

Рекомендации по безопасности репозитория позволяют поддерживать общедоступные репозитории для частного обсуждения и устранения уязвимости безопасности в проекте. После совместной работы над исправлением разработчики репозиториев могут публиковать рекомендации по безопасности, чтобы сообщить об уязвимости системы безопасности сообществу проекта. Публикуя рекомендации по безопасности, разработчики репозитория упрощают для сообщества обновление зависимостей пакетов и ознакомление с последствиями уязвимостей системы безопасности. Дополнительные сведения см. в разделе "Сведения о помощниках по безопасности репозитория".

Мы рекомендуем использовать синтаксис, используемый в GitHub Advisory Database, особенно форматирование версий, при написании рекомендаций по безопасности репозитория или внесении вклада сообщества в глобальный совет по безопасности.

Если следовать синтаксису для GitHub Advisory Database, особенно при определении затронутых версий:

При публикации рекомендаций по репозиторию мы можем добавить рекомендации в GitHub Advisory Database в качестве рекомендаций по "GitHub-просмотре" без необходимости запрашивать дополнительные сведения.
Dependabot будет содержать сведения для точного определения затронутых репозиториев и отправки их Dependabot alerts, чтобы уведомить их.
Участники сообщества, скорее всего, предлагают изменения в рекомендациях по исправлению отсутствующих или неверных сведений.

Вы добавляете или редактируете рекомендации по репозиторию с помощью формы "Черновик рекомендаций по безопасности". Дополнительные сведения см. в разделе Создание рекомендаций по безопасности репозитория.

Вы предлагаете улучшение существующих глобальных рекомендаций с помощью формы повышения безопасности. Дополнительные сведения см. в разделе Изменение рекомендаций по безопасности в базе данных рекомендаций по GitHub.

Экосистема

Необходимо назначить рекомендации одной из поддерживаемых экосистем с помощью поля экосистемы . Дополнительные сведения о экосистемах, которые мы поддерживаем, см. в разделе "Просмотр рекомендаций по безопасности в базе данных рекомендаций по GitHub".

Снимок экрана: область "Затронутые продукты" формы рекомендаций по безопасности. Поле "Экосистема" выделено темно-оранжевым контуром.

Имя пакета

Мы рекомендуем использовать поле "Имя пакета", чтобы указать, какие пакеты затронуты, так как сведения о пакете требуются для рекомендаций "GitHub-просмотрен" в GitHub Advisory Database. Сведения о пакете являются необязательными для помощников по безопасности на уровне репозитория, но в том числе эти сведения раньше упрощают процесс проверки при публикации рекомендаций по безопасности.

Затронутые версии

Мы рекомендуем использовать поле "Затронутые версии" , чтобы указать, какие версии затронуты, так как эта информация требуется для рекомендаций "GitHub-просмотрен" в GitHub Advisory Database. Сведения о версиях необязательны для помощников по безопасности на уровне репозитория, но в том числе эти сведения раньше упрощают процесс проверки при публикации рекомендаций по безопасности.

Дополнительные сведения о GitHub Advisory Databaseсм. в статье https://github.com/github/advisory-database.

Глоссарий

Уязвимый диапазон версий (VVR): диапазон версий, уязвимых к определенной ошибке программного обеспечения.
Оператор: любой символ, указывающий границу уязвимого диапазона версий.
Формат уязвимостей с открытым исходным кодом (OSV): формат, с которыми стремится обеспечить совместимость данных GitHub Advisory Database.

Синтаксис версии

Меньшие числа являются более ранними версиями, чем более крупные числа. например, 1.0.0 является более низкой версией, чем 2.0.0
Более ранние буквы в алфавите являются более ранними версиями, чем более поздние буквы в алфавите. Например, 2.0.0-a это более ранняя версия, чем 2.0.0-b.
Все буквы, поступающие после числа, считаются частью предварительной версии, поэтому любые версии с буквами после чисел являются более ранними версиями, чем цифры без букв в номере версии. Например, 2.0.0-alphaи 2.0.0-beta``2.0.0-rc раньше, чем2.0.0.
Фиксированная версия не может быть меньше наибольшего числа в VVR. Например, выпущена уязвимая версия, и средство обслуживания рекомендует понижение уровня. Поддержка не может пометить, что более низкая версия является фиксированной или исправленной версией в Fixed поле, так как эта версия меньше уязвимой версии.

Поддерживаемые операторы

>= значение "больше или равно этой версии".
> значение "больше этой версии".

Warning

Хотя GitHub поддерживает использование > оператора, использование этого оператора не рекомендуется, так как оно не поддерживается форматом OSV.
= значение "равно этой версии".
<= значение "меньше или равно этой версии".
< значение "меньше этой версии".

Указание затронутых версий для GitHub

Важно четко определить затронутые версии для рекомендаций. GitHub предоставляет несколько вариантов в поле "Затронутые версии" для указания уязвимых диапазонов версий.

Примеры определения затронутых версий в некоторых существующих рекомендациях см . в примерах.

Допустимая строка затронутой версии состоит из одного из следующих элементов:
- Последовательность операторов нижней границы.
- Последовательность операторов верхнего предела.
- Последовательность операторов верхнего и нижнего границ. Нижняя граница должна прийти сначала, за которой следует запятая и одно пространство, а затем верхняя граница.
- Определенная последовательность версий с помощью оператора равенства (=).
- Каждая последовательность операторов должна быть указана как оператор, отдельное пространство, а затем версия. Дополнительные сведения о допустимых операторах см. в разделе "Поддерживаемые операторы " выше.
- Версия должна начинаться с числа, за которым следует любое число чисел, букв, точек, дефисов или символов подчеркивания (что-либо, кроме пробела или запятой). Дополнительные сведения о форматировании версий см . в приведенном выше синтаксисе версии.
Note

Затронутые строки версии не могут содержать начальные или конечные пробелы.
Операторы верхнего предела могут быть инклюзивными или эксклюзивными, т. е. <= соответственно <.
Операторы нижней границы могут быть инклюзивными или эксклюзивными, т. е. >= >соответственно. Однако если вы публикуете рекомендации по репозиторию, и мы учим рекомендации по репозиторию в глобальные рекомендации, применяется другое правило: строки с нижней границой могут быть только включающими, т. е. >= Монопольный оператор нижней границы (>) допускается только в том случае, если версия — 0например > 0.
Правильное использование пробелов
- Используйте пробел между оператором и номером версии.
- Не используйте пробел в >= или <=.
- Не используйте пробел между числом и запятыми.>= lower bound, <= upper bound
- Используйте пробел между запятыми и оператором верхней границы.
Note

Ограничение нижней границы:
- Из-за несовместимости со схемой OSV.
- Применяется только при внесении предложения по существующим рекомендациям в GitHub Advisory Database.
Нельзя указать несколько затронутых диапазонов версий в одном поле, например > 2.0, < 2.3, > 3.0, < 3.2. Чтобы указать несколько диапазонов, необходимо создать раздел "Затронутые продукты " для каждого диапазона, нажав кнопку +Добавить другой затронутый продукт .
Если затронутый диапазон версий включает только одну верхнюю или нижнюю границу:
- Неявное значение всегда имеет значение, > 0 если нижняя граница не указана явно.
- Неявное значение всегда бесконечно, если верхняя граница не указана явно.

Установка верхней границы только для VVR

Если задана только верхняя граница, используйте <= или <.
GitHub Advisory Database использует базу данных PyPA в качестве одного из его источников данных. Однако GitHub не соответствует формату PyPA VVR точно (рекомендации по безопасности PyPa часто используют >= 0, <= n или >= 0, < n ссылаются на диапазоны версий, которые имеют только верхнюю границу).
Нет необходимости включать >= 0 в диапазон, имеющий только верхнюю границу.

Установка нижней границы только для VVR

Команда консультативного курирования не рекомендует устанавливать нижние границы только для каких-либо рекомендаций, отличных от вредоносных программ. Это связано с тем, что если исправленная версия когда-либо выпущена, пользователи фиксированной версии будут продолжать получать ненужные Dependabot alerts до тех пор, пока рекомендации не будут обновлены вручную.
Использование >= 0 для всех версий
> 0 обычно не используется.

Указание только одной затронутой версии

= n для одной затронутой версии
Имейте в виду, что не = будет автоматически включать общедоступные или частные предварительные версии, только указанную версию.

Распространенные ошибки

Избегайте использования уязвимого < n диапазона версий, а затем говорю n+1 об исправлении.
- < n следует использовать только в том случае, если n он не уязвим.
- В этом случае VVR должен быть <= n или < n+1.
Избегайте использования только числа при описании фиксированных версий с официальными номерами версий с буквами. Предположим, что ваше программное обеспечение имеет две ветви и linux windows. При выпуске 2.0.0-linux и 2.0.0-windowsиспользовании < 2.0.0 в качестве уязвимой версии будет помечаться 2.0.0-linux и 2.0.0-windows как уязвимая, так как логика версии интерпретирует -linux и -windows как предустановки. Вам потребуется пометить 2.0.0-linuxнаиболее раннюю ветвь в алфавите, как первую исправленную версию, чтобы избежать 2.0.0-linux и 2.0.0-windows считаться уязвимой.