Specifica del Repository VEX v0.1

• Specifica del Repository VEX v0.1
  • 1. Versionamento
  • 2. Manifest del Repository
    • 2.1 Panoramica
    • 2.2 Posizione del File
    • 2.3 Schema
    • 2.4 Esempio
    • 2.5 Descrizioni dei Campi e Note d'Uso
      • Campi Principali
      • Sotto-campi delle Versioni
      • Sotto-campi delle Posizioni
  • 3. Struttura del Repository
    • 3.1 Struttura dei File
    • 3.2 index.json
    • 3.3 Documenti VEX
    • 3.4 Note d'Uso
      • Struttura delle Directory
      • Contenuto dei Documenti VEX
    • 3.5 Aggiornamento del Repository
  • 4. Distribuzione del Repository
    • 4.1 Panoramica
    • 4.2 Formato dell'Archivio
  • 5. Linee Guida per l'Implementazione del Client
    • 5.1 Selezione della Versione
    • 5.2 Selezione della Posizione
    • 5.3 Supporto a Più Repository
      • Prioritizzazione dei Repository
    • 5.4 Verifica degli Aggiornamenti
    • 5.5 Strategie di Efficienza

Le parole chiave "DEVE", "NON DEVE", "RICHIESTO", "DOVRÀ", "NON DOVRÀ", "DOVREBBE", "NON DOVREBBE", "RACCOMANDATO", "PUÒ" e "OPZIONALE" in questo documento devono essere interpretate come descritto nella RFC 2119.

1. Versionamento

• La specifica del Repository VEX (Vulnerability Exploitability eXchange) DEVE utilizzare il versionamento vX.Y.
• Per la v1.0 e successive:
  • X (versione maggiore) DEVE essere aggiornata per modifiche incompatibili (breaking changes).
  • Y (versione minore) DEVE essere aggiornata per modifiche retrocompatibili.
• Per le versioni v0.Y, modifiche incompatibili POSSONO verificarsi con aggiornamenti della versione minore.

Quando si confrontano le versioni:

• Le versioni DEVONO essere confrontate numericamente, non lessicograficamente.
• Le versioni maggiori DEVONO essere confrontate per prime:
  • Se le versioni maggiori differiscono, la versione con la versione maggiore più alta è considerata più recente.
  • Se le versioni maggiori sono uguali, si procede al confronto delle versioni minori.
• Le versioni minori DEVONO essere confrontate solo quando le versioni maggiori sono uguali:
  • La versione con la versione minore più alta è considerata più recente.

Esempi di confronto:

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

2. Manifest del Repository

2.1 Panoramica

Il file manifest fornisce metadati su un repository di dati VEX. Questo file DEVE contenere le informazioni necessarie per recuperare e aggiornare i dati VEX.

2.2 Posizione del File

• Per HTTPS: il file manifest DEVE trovarsi in https://<domain>/.well-known/vex-repository.json
• Per repository GitHub: vex-repository.json DEVE essere collocato nella directory principale del branch principale.

2.3 Schema

Lo schema JSON per il file manifest è definito qui.

2.4 Esempio

{
  "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 Descrizioni dei Campi e Note d'Uso

Campi Principali

Campo	Obbligatorio	Descrizione e Note d'Uso
name	✓	Il nome del repository.
description	✓	Una breve descrizione del repository.
versions	✓	Un array contenente i dettagli delle versioni disponibili. Ogni oggetto nell'array rappresenta una versione che implementa una versione della Specifica del Repository VEX. Le versioni DEVONO essere ordinate in ordine crescente, dalla più vecchia alla più recente. Vedere la tabella separata per i sotto-campi.

Sotto-campi delle Versioni

Campo	Obbligatorio	Descrizione e Note d'Uso
spec_version	✓	La versione della Specifica del Repository VEX implementata (ad es. "0.1"). Il formato DEVE essere "X.Y" come definito nella sezione 1.
locations	✓	Un array di oggetti che descrivono le posizioni dei dati VEX. DEVE contenere almeno un oggetto posizione. Vedere la tabella separata per i sotto-campi.
update_interval	✓	L'intervallo consigliato per la verifica degli aggiornamenti dei dati VEX di questa versione. Utilizza il formato di durata di Go (ad es. "1h", "30m", "24h").
repository_specific	-	Informazioni aggiuntive specifiche del repository.

Sotto-campi delle Posizioni