Управление помощниками по внутреннему источнику

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

В этой статье

Сведения о работе помощников по внутреннему источнику и их создании см. в разделе Innersource advisories.

Необходимые условия

Помощники по внутреннему источнику могут создаваться только в предприятиях с активным GitHub Code Security или GitHub Advanced Security лицензией.

Создание помощников по внутреннему источнику

Чтобы создать рекомендации по внутреннему источнику, выполните приведенные далее действия.

  1. Создайте и установите с GitHub App разрешением enterprise_innersource_vulnerabilities .
  2. Создайте маркер, связанный с приложением, которое имеет write доступ к этому разрешению.
  3. Создайте описание уязвимости с помощью формата OSV и POST конечной точки /enterprises/{enterprise}/innersource-vulnerabilities/syncREST API.

Каждый из этих шагов подробно описан ниже.

Шаг 1. Создание GitHub App

Зарегистрируйте объект, принадлежащий GitHub App вашей организации, и предоставьте ему разрешение с read and write доступомenterprise_innersource_vulnerabilities. См . раздел AUTOTITLE.

После регистрации приложения установите его в вашей организации, чтобы он смог действовать от имени предприятия.

Шаг 2. Создание маркера доступа

Проверка подлинности в качестве GitHub App установки для создания маркера доступа к установке. Этот маркер несет enterprise_innersource_vulnerabilities разрешение и используется для проверки подлинности запросов к REST API. См . раздел AUTOTITLE.

Шаг 3. Отправка описания рекомендаций

Опишите уязвимость с помощью формата OSV, а затем POST полезные данные /enterprises/{enterprise}/innersource-vulnerabilities/syncдля проверки подлинности с помощью маркера доступа к установке. Полезные данные определяют затронутый пакет и диапазон уязвимых версий. Если исправленная версия доступна, добавьте поле с номером fixed версии, чтобы Dependabot открыть запросы на вытягивание для обновления затронутых репозиториев.

Подробные сведения о схеме рекомендаций см. в разделе Конечные точки REST API для помощников по безопасности.

Использование помощников по внутреннему источнику

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

  1. Убедитесь, что репозитории в вашей организации включены Dependabot alerts и включены обновления. Это можно применить в масштабе с помощью конфигурации безопасности. См . раздел AUTOTITLE.
  2. Просмотрите страницу зависимых репозиториев Dependabot alerts для нового оповещения о затронутом компоненте. В оповещении будет выделена отдельная метка Innersource, чтобы отличить ее от открытый код предупреждений о рекомендациях.
  3. Если полезные данные рекомендаций включали fixed поле с номером версии, который соответствует доступному пакету, Dependabot также создаст запрос на вытягивание, который обновляет файл манифеста диспетчера пакетов. См . раздел AUTOTITLE.

Вывод рекомендаций по внутреннему источнику

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

Чтобы отозвать рекомендации, используйте ту же конечную точку REST API, что и шаг создания, но настройте полезные данные, чтобы включить withdrawn ключ, значение которого — date-time поле, указывающее, когда уязвимость была снята.

Поддержка и ограничения формата OSV

GitHub принимает уязвимости в формате уязвимостей с открытым исходным кодом (OSV) через API синхронизации уязвимостей внутреннего источника. Хотя GitHub стремится к совместимости со спецификацией OSV, существуют различия между стандартной схемой OSV и тем, что GitHub требует или поддерживает.

Поддерживаемая версия схемы OSV

GitHub поддерживает версии схемы OSV, совместимые с ~> 1.0 (т. е. 1.0.0 через 1.x.x). Рекомендуется 1.4.0использовать версию схемы.

Форматирование затронутых записей

Спецификация OSV позволяет одной affected записи содержать несколько ranges и несколько versions для одного пакета. GitHub нормализует их внутренне, разделив их на отдельные записи:

| Стандарт OSV | GitHub Поведение | |---|---| | affected Одна запись может содержать несколькоranges | Accepted. Каждый диапазон обрабатывается как отдельный уязвимый диапазон версий. | | affected Одна запись может содержать несколькоversions | Accepted. Каждая версия рассматривается как точное совпадение (= x.y.z) и обрабатывается как отдельный уязвимый диапазон версий. | | affected Одна запись может смешивать ranges иversions | Accepted. Диапазоны и версии разделены на отдельные записи внутри. | | Диапазон SEMVER может содержать несколько/introduced``fixed пар | Accepted. Поддерживаются несколько разных интервалов (например, [1.0.0, 1.0.2) и [3.0.0, 3.2.5)) в одном диапазоне. |

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

Тип диапазонаПоддержка
ECOSYSTEM
Полностью поддерживается. Поддерживает introducedи fixed``last_affected события.
SEMVER
Полностью поддерживается. Поддерживает introducedи fixed``last_affected события. Событие last_affected анализируется как <= средство сравнения верхнего предела.
GIT
Не поддерживается. Диапазоны на основе фиксации Git не обрабатываются.

Примечание.

  • Для ECOSYSTEM диапазонов поддерживается только одно и одно introduced``fixed событие (или last_affected) для каждого диапазона. Если необходимо выразить несколько разрозненных диапазонов версий для одного пакета, используйте отдельные записи или отдельные affected диапазоны.

SEMVER диапазоны поддерживают несколько introduced/fixed пар в одном диапазоне (например, [1.0.0, 1.0.2) в [3.0.0, 3.2.5) одном массиве событий).

- fixed и last_affectedне может отображаться вместе в одном диапазоне. Используйте одно или другое с предпочтениями fixed.

Обязательные поля

Спецификация OSV рассматривает несколько полей как необязательные, но GitHub требуют их. Запросы, отсутствующие в этих полях, отклоняются с ошибкой 422.

| Поле | Спецификация OSV | GitHub Требование | |---|---|---| | id | Обязательный | Обязательно. Используется в качестве внешнего идентификатора уязвимости. | | массив severity | Optional | Обязательно. Должен содержать по крайней мере одну CVSS_V3 или CVSS_V4 запись с непустой score строкой (например, CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H). Запросы без допустимой записи CVSS отклоняются. | | affected[].package.ecosystem | Обязательный | Должна быть поддерживаемой экосистемой | | affected[].ranges или affected[].versions | По крайней мере один обязательный | Для сопоставления оповещений должно присутствовать по крайней мере один диапазон или версия. |

Необязательные поля с автоматическим производным

ПолеBehavior
database_specific.severityЕсли это указано, используется в качестве качественной метки серьезности (critical, , high``moderateилиlow). Если уровень серьезности отсутствует, уровень серьезности автоматически извлекается из векторной оценки CVSS.
summaryЕсли нет, вернется к id полю.
detailsЕсли нет, возвращается в summary или id.

Поддерживаемые типы серьезности

Тип серьезностиПоддержка
CVSS_V3
Поддерживается. Должен быть допустимой строкой вектора CVSS 3.1.
CVSS_V4
Поддерживается. Должен быть допустимой строкой вектора CVSS 4.0.
Другие типы
Не поддерживается. Приведет к ошибке синтаксического анализа.

Поддерживаемые ссылочные типы

Тип ссылкиПоддержка
ADVISORYПоддерживается
WEBПоддерживается
FIXПоддерживается
ARTICLEПоддерживается
REPORTПоддерживается
PACKAGEПоддерживается (сопоставлено с расположением исходного кода)
EVIDENCEПоддерживается (игнорируется во время обработки)
DETECTION
Не поддерживается. Отрезается во время обработки.

Поддержка псевдонимов

Формат псевдонимаПоддержка
CVE-YYYY-NNNNN
Поддерживается. Извлекается в качестве идентификатора CVE. Используется только первый псевдоним CVE.
Другие форматы (GHSA, PYSEC и т. д.)
Не поддерживается. Отрезается во время обработки.

Примечание.

Если поле уязвимости id начинается с GHSA-, он распознается как идентификатор GHSA. Однако записи GHSA в aliases массиве удаляются и не сохраняются.

Ограничения размера поля

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

Отправки, превышающие эти ограничения, отклоняются с описательной ошибкой 422, указывающей, какое поле превысило ограничение и фактическую длину, указанную (например, affected[0].first_patched_version is 63 characters (max 50)).

| Поле OSV | Карты с | Ограничение стандарта OSV | GitHub Предел | Единица измерения | |---|---|---|---|---| | summary | vulnerabilities.summary | Нет ограничения (рекомендуется ≤120 chars) | 1,024 | байт | | id | vulnerabilities.external_id | Без ограничений | 2,048 | символы | | aliases[] (запись CVE) | vulnerabilities.cve_id | Без ограничений | 20 | символы | | severity[].score (CVSS версии 3) | vulnerabilities.cvss_v3 | Без ограничений | 255 | байт | | severity[].score (CVSS версии 4) | vulnerabilities.cvss_v4 | Без ограничений | 255 | символы | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | Без ограничений | 20 | символы | | affected[].package.name | vulnerable_version_ranges.affects | Без ограничений | 255 | символы | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | Без ограничений | 50 | символы | | Вычисляемый уязвимый диапазон версий | vulnerable_version_ranges.requirements | Без ограничений | 65,535 | байт |

Примечание.

  • Ограничение fixed_in (первая исправленная версия) в 50 символов является наиболее часто встречающимся ограничением. Некоторые экосистемы используют длинные строки версий предварительной версии (например, 1.0.0-alpha.gamma.delta.epsilon.zeta.eta.theta), превышающие это ограничение.

varchar столбцы проверяются числом символов; varbinary и text столбцы проверяются по размеру байтов (релевантных для многобайтовых символов UTF-8).

  • Эти ограничения ограничены GitHub Enterprise Server совместимостью схем. Расширение столбцов GitHub без сопоставления изменений GHES приведет к сбоям синхронизации рекомендаций между средами.

Сопоставление экосистем

GitHub сопоставляет имена экосистем OSV с идентификаторами внутренних экосистем. Поддерживаются следующие экосистемы:

| Экосистема OSV | GitHub экосистема | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Maven | | NuGet | NuGet | | Packagist | Композитор | | Go | Вперед | | crates.io | Rust | | Hex | Erlang | | Pub | Кабак | | SwiftURL | Swift | | GitHub Actions | GitHub Actions |

Пример: минимальная полезные данные OSV для создания оповещений

Ниже приведены минимальные полезные данные OSV, содержащие все обязательные поля для GitHub создания Dependabot оповещения:

{
  "schema_version": "1.4.0",
  "id": "EXAMPLE-2024-001",
  "modified": "2024-01-15T10:00:00Z",
  "summary": "Example vulnerability in example-package",
  "details": "A detailed description of the vulnerability.",
  "aliases": ["CVE-2024-12345"],
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    }
  ],
  "affected": [
    {
      "package": {
        "ecosystem": "npm",
        "name": "example-package"
      },
      "ranges": [
        {
          "type": "ECOSYSTEM",
          "events": [
            { "introduced": "0" },
            { "fixed": "1.2.3" }
          ]
        }
      ]
    }
  ],
  "database_specific": {
    "severity": "Critical"
  },
  "references": [
    { "type": "ADVISORY", "url": "https://example.com/advisory" }
  ],
  "published": "2024-01-15T10:00:00Z"
}

Известные ограничения

  • Максимум 100 уязвимостей на запрос. API синхронизации принимает не более 100 уязвимостей в одном запросе.
  • Нет GIT типа диапазона. Диапазоны версий на основе фиксации Git не поддерживаются.
  • Отдельные типы событий в диапазоне ЭКОСИСТЕМ. Каждый ECOSYSTEM диапазон поддерживает одно и одно introduced событие верхнего предела (fixed или last_affected). Несколько introduced/fixed пар в одном ECOSYSTEM диапазоне не поддерживаются— используйте отдельные диапазоны или отдельные affected записи. (Это ограничение не применяется к SEMVER диапазонам, которые поддерживают несколько пар событий.)
  • fixed и last_affected являются взаимоисключающими. Один диапазон не может содержать как события, так fixed и last_affected события. Используйте один или другой.
  • Совместимость синхронизации GHES. Ограничения размера поля (например fixed_in , в 50 символов) ограничены GitHub Enterprise Server требованиями совместимости схемы.