VEX Repository Specification v0.1

• VEX Repository Specification v0.1
  • 1. Versioning
  • 2. Repository Manifest
    • 2.1 Overview
    • 2.2 File Location
    • 2.3 Schema
    • 2.4 Example
    • 2.5 Field Descriptions and Usage Notes
      • Main Fields
      • Versions Subfields
      • Locations Subfields
  • 3. Repository Structure
    • 3.1 File Structure
    • 3.2 index.json
    • 3.3 VEX Documents
    • 3.4 Usage Notes
      • Directory Structure
      • VEX Document Content
    • 3.5 Updating the Repository
  • 4. Repository Distribution
    • 4.1 Overview
    • 4.2 Archive Format
  • 5. Client Implementation Guidelines
    • 5.1 Version Selection
    • 5.2 Location Selection
    • 5.3 Multiple Repository Support
      • Repository Prioritization
    • 5.4 Checking for Updates
    • 5.5 Efficiency Strategies

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Versioning

• The VEX (Vulnerability Exploitability eXchange) Repository Specification MUST use vX.Y versioning.
• For v1.0 and later:
  • X (major version) MUST be updated for breaking changes.
  • Y (minor version) MUST be updated for backwards-compatible changes.
• For v0.Y versions, breaking changes MAY occur with minor version updates.

When comparing versions:

• Versions MUST be compared numerically, not lexicographically.
• Major versions MUST be compared first:
  • If major versions differ, the version with the higher major version is considered newer.
  • If major versions are equal, proceed to compare minor versions.
• Minor versions MUST be compared only when major versions are equal:
  • The version with the higher minor version is considered newer.

Example comparisons:

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

2. Repository Manifest

2.1 Overview

The manifest file provides metadata about a VEX data repository. This file MUST contain information necessary for retrieving and updating VEX data.

2.2 File Location

• For HTTPS: The manifest file MUST be located at https://<domain>/.well-known/vex-repository.json
• For GitHub repositories: vex-repository.json MUST be placed in the root directory of the main branch.

2.3 Schema

The JSON schema for the manifest file is defined here.

2.4 Example

{
  "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 Field Descriptions and Usage Notes

Main Fields

Field	Required	Description and Usage Notes
name	✓	The name of the repository.
description	✓	A brief description of the repository.
versions	✓	An array containing details of available versions. Each object in the array represents a version implementing a VEX Repository Specification version. Versions MUST be sorted in ascending order, from oldest to newest. See separate table for subfields.

Versions Subfields

Field	Required	Description and Usage Notes
spec_version	✓	The version of the VEX Repository Specification implemented (e.g., "0.1"). Format MUST be "X.Y" as defined in section 1.
locations	✓	An array of objects describing VEX data locations. MUST contain at least one location object. See separate table for subfields.
update_interval	✓	The recommended update check interval for this version's VEX data. Uses Go duration format (e.g., "1h", "30m", "24h").
repository_specific	-	Additional repository-specific information.

Locations Subfields

Field	Required	Description and Usage Notes
url	✓	A URL for the VEX data location, starting with "https://". The content adheres to the repository structure specifications in section 3 and 4. The URL may include a subdirectory specification by appending '//' followed by the subdirectory path.

3. Repository Structure

3.1 File Structure

The repository MUST have the following structure:

vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
    ├── <type>/
    │   ├── <namespace>/
    │   │   ├── <name>/
    │   │   │   └── vex.json
    │   │   └── ...
    │   └── ...
    └── ...

Where <archive_extension> is one of supported archive formats.