vexhub

VEX Hub — это централизованный репозиторий, который собирает и управляет документами Vulnerability Exploitability eXchange (VEX) из различных проектов с открытым исходным кодом. Он служит комплексным ресурсом информации об уязвимостях, помогая пользователям и инструментам безопасности эффективно получать доступ к данным VEX и использовать их в нескольких проектах и экосистемах.

VEX Hub автоматически получает документы VEX из исходных репозиториев зарегистрированных проектов. Определяя исходный репозиторий по зарегистрированному Package URL (PURL), VEX Hub копирует и систематизирует документы VEX, делая их легко доступными для широкого сообщества.

Быстрый старт: добавление документов VEX в VEX Hub

1. Создайте ваш файл VEX
   1. VEX Hub поддерживает форматы OpenVEX или CSAF.
   2. Храните ваши файлы VEX в репозитории исходного кода в каталоге .vex/ в корне вашего репозитория. Подробнее здесь.
   3. Дополнительные рекомендации по созданию документов VEX для VEX Hub см. здесь.
2. Зарегистрируйте ваш пакет в VEX Hub
   1. Отправьте Pull Request, который добавляет PURL вашего пакета в файл crawled packages.

Вот и всё! VEX Hub автоматически получит и обработает ваши документы VEX.

Обход VEX

VEX Hub Crawler периодически обходит документы VEX зарегистрированных пакетов и поддерживает их в VEX Hub. Зарегистрированные пакеты определяются как список PURL в файле, который любой желающий может обновить через Pull Requests.

Подробную информацию о регистрации PURL, поддерживаемых экосистемах и конкретных требованиях см. в VEX Hub Crawler.

Определение исходных репозиториев

В файле пакетов указывается только PURL пакета для обхода, а VEX Hub Crawler автоматически определяет репозиторий исходного кода, в котором находится файл VEX. Метод определения исходных репозиториев различается в зависимости от экосистемы. Подробную информацию о том, как определяются и обходятся исходные репозитории для различных типов пакетов, см. в документации vex-crawler.

Обнаружение документов VEX

После определения репозитория исходного кода VEX Hub автоматически обнаруживает в нём документы VEX. Процесс обнаружения включает следующие ключевые моменты:

• Документы VEX ищутся в каталоге .vex/ в корне репозитория.
• Поддерживаемые форматы VEX: OpenVEX и CSAF.
• Учитываются имена файлов, соответствующие определённым шаблонам (например, *.vex.json, *.csaf.json).
• Для продуктов и подкомпонентов в документах VEX должны использоваться PURL.
• Документы VEX, не соответствующие зарегистрированному PURL, игнорируются.

Подробную информацию о процессе обнаружения, поддерживаемых экосистемах и конкретных требованиях см. в документации vex-crawler.

Структура каталогов

VEX Hub структурирован на основе Package URL (PURL), за исключением version, qualifiers и subpath. Структура соответствует следующим правилам:

1. Иерархия каталогов формируется из компонентов PURL: scheme, type, namespace (если присутствует) и name. В случае oci вместо них используется квалификатор repository_url.
2. Версия и квалификаторы не включаются в структуру каталогов. Эти элементы должны быть указаны в поле products документов VEX.
3. К специальным символам в компонентах PURL применяется URL-кодирование.

Примеры формирования структуры каталогов:

• pkg:npm/express → /npm/express/
• pkg:golang/github.com/gorilla/mux → /golang/github.com/gorilla/mux/
• pkg:maven/org.apache.xmlgraphics/batik-anim → /maven/org.apache.xmlgraphics/batik-anim/
• pkg:oci/trivy?repository_url=ghcr.io/aquasecurity/trivy → /oci/ghcr.io/aquasecurity/trivy/

Пример с кодированием специальных символов:

• pkg:npm/@angular/core → /npm/%40angular/core/

Распространение

VEX Hub соответствует спецификации репозитория VEX. Файлы vex_repository.json и index.json можно использовать для программного доступа к документам VEX в VEX Hub.

Несколько документов VEX на один PURL

VEX Hub может хранить несколько документов VEX для одного PURL, поскольку копирует все соответствующие документы VEX из исходного репозитория. Однако спецификация репозитория VEX допускает только один документ VEX на PURL. Чтобы соответствовать этой спецификации, VEX Hub реализует следующую стратегию распространения:

• Если для одного PURL существует несколько файлов VEX, VEX Hub выбирает первый файл в лексикографическом порядке.
• Выбранный файл записывается в index.json для распространения.

Создание документов VEX для VEX Hub

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

Рекомендуемые подходы:

1. Объединить операторы VEX для всех продуктов, управляемых исходным репозиторием, в один файл.
2. Разделить документы VEX по PURL.

Пример сценария: Рассмотрим исходный репозиторий https://github.com/org/repo, в котором поддерживаются два продукта: модуль Go и образ OCI.

Первый подход — создать один файл VEX, vex.json, содержащий операторы VEX для обоих продуктов.

• openvex.json: для обоих продуктов, с PURL pkg:golang/github.com/org/repo, pkg:oci/repo?repository_url=docker.io/org/repo и pkg:oci/repo?repository_url=ghcr.io/org/repo

Второй подход — создать отдельные файлы VEX для каждого продукта.

• golang.vex: для модуля Go, с PURL pkg:golang/github.com/org/repo
• oci.vex: для образа OCI, с PURL pkg:oci/repo?repository_url=docker.io/org/repo и pkg:oci/repo?repository_url=ghcr.io/org/repo

Следующая структура не рекомендуется:

• v1.vex: для модуля Go, с PURL pkg:golang/github.com/org/[email protected]
• v2.vex: для модуля Go, с PURL pkg:golang/github.com/org/[email protected]

В этом примере для распространения выбирается v1.vex, а v2.vex игнорируется. Их следует объединить в один файл VEX, golang.vex, с несколькими версиями и квалификаторами.

Модель доверия VEX Hub

Поскольку VEX Hub (и VEX в целом) потенциально дополняет результаты сканирования безопасности, вы вправе тщательно проверять корректность потребляемых документов VEX. В отличие от других каналов обмена уязвимостями или каналов уведомлений о безопасности, поддерживающих VEX, VEX Hub не является источником данных операторов VEX. VEX Hub лишь агрегирует существующие документы VEX и систематизирует их в центральном удобном репозитории.

Чтобы попасть в VEX Hub, документы VEX сначала должны быть добавлены в репозиторий исходного кода основного пакета. Этот подход основан на том факте, что как пользователь вы уже должны доверять пакетам, которые используете, а значит, и мейнтейнерам, их системе управления и процессам. У каждого проекта есть своя система управления и свои процессы добавления изменений в репозиторий исходного кода. Те же системы и процессы, которые делают код пакета заслуживающим доверия в ваших глазах, делают для вас заслуживающими доверия и документы VEX. Вам не следует доверять VEX Hub больше, чем пакетам, которые вы решаете использовать.

VEX Hub не несёт ответственности и не обладает информацией о содержимом хранящихся в нём документов VEX или описываемых ими пакетах. Мейнтейнеры VEX Hub не проверяют и не верифицируют содержимое документов VEX; ответственность за точность и корректность информации лежит на мейнтейнерах исходных пакетов. Мы рекомендуем пользователям вручную проводить триаж подавленных уязвимостей так же, как они проводили бы триаж любой другой уязвимости.

Устранение неполадок

Если документы VEX в исходном репозитории зарегистрированного PURL не обновляются должным образом в VEX Hub, проверьте следующее:

1. Убедитесь, что документы VEX размещены в правильном месте (каталог .vex/ в корне репозитория).
2. Проверьте, что в документах VEX используется одно из поддерживаемых соглашений об именах файлов.
3. Подтвердите, что PURL в документе VEX соответствует зарегистрированному PURL в VEX Hub.
4. Просмотрите документацию vexhub-crawler, чтобы убедиться, что все требования к обходу соблюдены.

Если после проверки этих пунктов проблемы сохраняются, откройте issue в репозитории VEX Hub для дальнейшей помощи.

Вклад

Вклад в улучшение VEX Hub приветствуется! Обратите внимание, что список пакетов и связанный код поддерживаются в репозитории VEX Hub Crawler. Pull Requests, напрямую добавляющие документы VEX в этот репозиторий, не рекомендуются. Этот проект и все его участники регулируются Кодексом поведения Aqua Security.