Спецификация репозитория VEX v0.1

• Спецификация репозитория VEX v0.1
  • 1. Версионирование
  • 2. Манифест репозитория
    • 2.1 Обзор
    • 2.2 Расположение файла
    • 2.3 Схема
    • 2.4 Пример
    • 2.5 Описание полей и примечания по использованию
      • Основные поля
      • Подполя versions
      • Подполя locations
  • 3. Структура репозитория
    • 3.1 Структура файлов
    • 3.2 index.json
    • 3.3 Документы VEX
    • 3.4 Примечания по использованию
      • Структура каталогов
      • Содержимое документов VEX
    • 3.5 Обновление репозитория
  • 4. Распространение репозитория
    • 4.1 Обзор
    • 4.2 Формат архива
  • 5. Рекомендации по реализации клиента
    • 5.1 Выбор версии
    • 5.2 Выбор расположения
    • 5.3 Поддержка нескольких репозиториев
      • Приоритизация репозиториев
    • 5.4 Проверка обновлений
    • 5.5 Стратегии эффективности

Ключевые слова "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" и "OPTIONAL" в данном документе должны интерпретироваться в соответствии с RFC 2119.

1. Версионирование

• Спецификация репозитория VEX (Vulnerability Exploitability eXchange) ДОЛЖНА использовать версионирование в формате vX.Y.
• Для версий v1.0 и более поздних:
  • X (мажорная версия) ДОЛЖНА обновляться при внесении несовместимых изменений (breaking changes).
  • Y (минорная версия) ДОЛЖНА обновляться при обратно совместимых изменениях.
• Для версий v0.Y несовместимые изменения МОГУТ вноситься с обновлением минорной версии.

При сравнении версий:

• Версии ДОЛЖНЫ сравниваться численно, а не лексикографически.
• Мажорные версии ДОЛЖНЫ сравниваться в первую очередь:
  • Если мажорные версии различаются, версия с большей мажорной версией считается более новой.
  • Если мажорные версии равны, переходите к сравнению минорных версий.
• Минорные версии ДОЛЖНЫ сравниваться только при равенстве мажорных версий:
  • Версия с большей минорной версией считается более новой.

Примеры сравнения:

• 1.0 < 2.0
• 1.1 < 1.2
• 1.10 > 1.2

2. Манифест репозитория

2.1 Обзор

Файл манифеста содержит метаданные о репозитории данных VEX. Этот файл ДОЛЖЕН содержать информацию, необходимую для получения и обновления данных VEX.

2.2 Расположение файла

• Для HTTPS: файл манифеста ДОЛЖЕН располагаться по адресу https://<domain>/.well-known/vex-repository.json
• Для репозиториев GitHub: vex-repository.json ДОЛЖЕН быть размещён в корневом каталоге основной ветки.

2.3 Схема

JSON-схема файла манифеста определена здесь.

2.4 Пример

{
  "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"
    }
  ]
}

2.5 Описание полей и примечания по использованию

Основные поля

Поле	Обязательно	Описание и примечания по использованию
name	✓	Название репозитория.
description	✓	Краткое описание репозитория.
versions	✓	Массив, содержащий сведения о доступных версиях. Каждый объект в массиве представляет версию, реализующую версию Спецификации репозитория VEX. Версии ДОЛЖНЫ быть отсортированы по возрастанию, от самой старой к самой новой. См. отдельную таблицу для подполей.

Подполя versions

Поле	Обязательно	Описание и примечания по использованию
spec_version	✓	Версия Спецификации репозитория VEX, которая реализована (например, "0.1"). Формат ДОЛЖЕН быть "X.Y", как определено в разделе 1.
locations	✓	Массив объектов, описывающих расположения данных VEX. ДОЛЖЕН содержать как минимум один объект расположения. См. отдельную таблицу для подполей.
update_interval	✓	Рекомендуемый интервал проверки обновлений для данных VEX этой версии. Используется формат длительности Go (например, "1h", "30m", "24h").
repository_specific	-	Дополнительная информация, специфичная для данного репозитория.

Подполя locations

Поле	Обязательно	Описание и примечания по использованию
url	✓	URL расположения данных VEX, начинающийся с "https://". Содержимое соответствует требованиям к структуре репозитория, описанным в разделе 3 и 4. URL может включать указание подкаталога путём добавления '//' с последующим путём к подкаталогу.

3. Структура репозитория

3.1 Структура файлов