aquasecurity/vex-repo-specСпецификация репозитория VEX
Ключевые слова "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" и "OPTIONAL" в данном документе должны интерпретироваться в соответствии с RFC 2119.
При сравнении версий:
Примеры сравнения:
Файл манифеста содержит метаданные о репозитории данных VEX. Этот файл ДОЛЖЕН содержать информацию, необходимую для получения и обновления данных VEX.
https://<domain>/.well-known/vex-repository.jsonvex-repository.json ДОЛЖЕН быть размещён в корневом каталоге основной ветки.JSON-схема файла манифеста определена здесь.
{
"name": "Example Org VEX Repository",
"description": "VEX repository for Example Organization",
"versions": [
{
"spec_version": "0.1",
"locations": [
{
"url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
}
],
"update_interval": "24h",
"repository_specific": {
"location": {
"repository_type": "db",
"db_type": "bbolt",
"url": "oci://ghcr.io/example.com/vex-db:0"
}
}
},
{
"spec_version": "1.0",
"locations": [
{
"url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
},
{
"url": "https://example.com/vex-api/v1"
}
],
"update_interval": "1h"
}
]
}
| Поле | Обязательно | Описание и примечания по использованию |
|---|---|---|
| name | ✓ | Название репозитория. |
| description | ✓ | Краткое описание репозитория. |
| versions | ✓ | Массив, содержащий сведения о доступных версиях. Каждый объект в массиве представляет версию, реализующую версию Спецификации репозитория VEX. Версии ДОЛЖНЫ быть отсортированы по возрастанию, от самой старой к самой новой. См. отдельную таблицу для подполей. |
| Поле | Обязательно | Описание и примечания по использованию |
|---|---|---|
| spec_version | ✓ | Версия Спецификации репозитория VEX, которая реализована (например, "0.1"). Формат ДОЛЖЕН быть "X.Y", как определено в разделе 1. |
| locations | ✓ | Массив объектов, описывающих расположения данных VEX. ДОЛЖЕН содержать как минимум один объект расположения. См. отдельную таблицу для подполей. |
| update_interval | ✓ | Рекомендуемый интервал проверки обновлений для данных VEX этой версии. Используется формат длительности Go (например, "1h", "30m", "24h"). |
| repository_specific | - | Дополнительная информация, специфичная для данного репозитория. |
Репозиторий ДОЛЖЕН иметь следующую структуру:
vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
├── <type>/
│ ├── <namespace>/
│ │ ├── <name>/
│ │ │ └── vex.json
│ │ └── ...
│ └── ...
└── ...
Где <archive_extension> — один из поддерживаемых форматов архивов.
[optional_subdirectory/] включается, когда URL в поле locations заканчивается на //, за которым следует путь к подкаталогу.
Это обеспечивает гибкость структуры репозитория, особенно при использовании существующих макетов репозиториев, таких как в репозиториях GitHub.
Например, если URL — https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main, структура файлов будет следующей:
main.tar.gz
└──repo-main/
├── index.json
└── pkg/
└── ...
В этом случае repo-main/ является корневым каталогом репозитория VEX внутри файла tar.gz.
Файл index.json служит манифестом содержимого архивного файла. Он ДОЛЖЕН располагаться в корневом каталоге архива или в указанном подкаталоге, если таковой определён в URL. Файл ДОЛЖЕН иметь следующую структуру:
{
"updated_at": "2023-07-04T12:00:00Z",
"packages": [
{
"id": "pkg:deb/debian/curl",
"location": "pkg/deb/debian/curl/vex.json"
},
{
"id": "pkg:npm/lodash",
"location": "pkg/npm/lodash/vex.json",
"format": "csaf"
}
]
}
Описание полей:
| Поле | Обязательно | Описание |
|---|---|---|
| updated_at | ✓ | Отметка времени, указывающая, когда этот index.json был обновлён последний раз. |
| packages | ✓ | Массив объектов, каждый из которых представляет пакет в репозитории. |
| packages[].id | ✓ | Идентификатор пакета. В настоящее время принимается только Package URL (PURL). Версия, квалификаторы и подпуть ДОЛЖНЫ быть опущены, поскольку они включены в документ VEX. Для пакетов типа OCI квалификатор repository_url ДОЛЖЕН быть включён в id. |
| packages[].location | ✓ | Относительный путь к файлу VEX данного пакета внутри архива. Клиенты ДОЛЖНЫ использовать это поле для поиска файлов VEX конкретных пакетов. |
| packages[].format | - | Формат данных VEX: "openvex" или "csaf". Если поле опущено, подразумевается "openvex". |
Схема файла индекса определена здесь.
Информация VEX каждого пакета ДОЛЖНА храниться в отдельном JSON-файле в соответствии со структурой путей, определённой в файле index.json. Содержимое этих файлов ДОЛЖНО соответствовать спецификации формата VEX (OpenVEX или CSAF VEX), как указано в поле format.
Один документ VEX МОЖЕТ включать информацию для разных версий, квалификаторов и подпутей одного и того же пакета.
Примеры документов OpenVEX см. в спецификации OpenVEX.
repository_url из PURL МОЖЕТ использоваться для создания структуры каталогов. Например, пакет с PURL "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" может храниться в "pkg/oci/docker.io/library/debian/vex.json".location файла index.json, независимо от рекомендуемой структуры.При обновлении репозитория VEX:
updated_at.locations в файле манифеста (vex-repository.json).Репозиторий VEX ДОЛЖЕН распространяться в виде архивного файла, содержащего данные VEX и связанные метаданные. Этот архив ДОЛЖЕН быть указан в поле locations файла vex-repository.json и является основным средством распространения информации VEX.
Архивный файл ДОЛЖЕН быть в одном из следующих форматов:
tar.gz и tgztar.bz2 и tbz2tar.xz и txzzipgzbz2xzПри выборе версии из массива versions:
spec_version.При работе с несколькими расположениями в массиве locations:
Клиентов СЛЕДУЕТ проектировать так, чтобы они поддерживали несколько репозиториев VEX.
Для проверки обновлений клиентам СЛЕДУЕТ использовать следующий процесс:
update_interval из файла vex-repository.json.update_interval к локально сохранённой отметке времени.Для эффективной работы клиенты МОГУТ реализовать следующие стратегии:
update_interval очень короткий.