GCVE-BCP-08 - GCVE GNA Directory File (draft)

GCVE
5

This version includes feedback from @cedric , @jgamblin, and participants of the
informal FOSDEM workshop in Brussels who are familiar with the CNA model and the
CVE Program.

Regarding the integration of CNA-related fields, no decision has yet been made
on how these should be represented in the JSON structure. The current idea is
to introduce a dedicated namespace in which the complete original CNA entry
could be embedded without modification. And a new one for GCVE to avoid some
legacy which might not be required but also future extension in GCVE.

The status field, as proposed by @jgamblin, has now been integrated, and there
is strong consensus on this aspect. The agreement on using RFC 3339 for
timestamps was also clear, and we now explicitly avoid referencing ISO standards,
as they are not open standards.

Regarding the proposed structural change to add a schema version, introducing a
new root-level element may break existing parsers. We therefore need to evaluate
alternative approaches for introducing a versioning mechanism without
disrupting current implementations.

GCVE-BCP-08 — GCVE GNA Directory File

Status of This Document

This document defines GCVE-BCP-08, which specifies the structure and semantics
of the GCVE GNA Directory File. This file enumerates known GCVE Numbering
Authorities (GNAs) and associated metadata used by the GCVE ecosystem.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.

Purpose and Applicability

This Best Current Practice (BCP) exists for implementers, parsers, and users
of the GCVE GNA Directory File.

The directory file described in this document is exclusively generated and
maintained by GCVE and serves as the official and authoritative directory
of GCVE Numbering Authorities. Third parties MUST NOT generate alternative or
competing versions of this directory while claiming GCVE authority.

The GCVE GNA Directory File MUST be published as a signed artifact by
GCVE. The digital signature establishes the authenticity and integrity of the
directory and allows consumers to verify that the file originates from GCVE and
has not been altered.

The signature format, trust model, and verification procedures are defined in
GCVE-BCP-01. Consumers of this file MUST verify the signature in
accordance with GCVE-BCP-01 prior to processing or relying on the contents of
the directory.

Consumers of the file (including tooling, aggregation platforms, vulnerability
databases, and archival systems) MUST interpret and process the file
according to this specification to ensure consistent handling of identifiers,
authority lineage, and historical data.

This BCP does not define a submission or modification mechanism for GNAs.
It strictly defines the format, semantics, authenticity requirements, and
interpretation of the file as published by GCVE.

Scope

The GCVE GNA Directory File is a JSON (ECMA 404) document containing an array of GNA
descriptors. Each entry represents a registered or reserved GNA identifier and
provides optional metadata describing publication endpoints, allocation
capabilities, lifecycle status, and usage constraints.

This directory is intended to be:

  • Machine-readable
  • Publicly distributable
  • Stable and append-only, except for metadata updates

Authority Lifecycle and Lineage

In the vulnerability management ecosystem, authorities may merge, be acquired,
change names, or cease operations. To prevent ambiguity in historical records
and to avoid orphaned identifiers, the GCVE GNA Directory MUST support
explicit lifecycle and lineage tracking.

Each GNA entry MAY include a status field indicating its current lifecycle
state. When an authority is no longer active due to renaming, merger, or
acquisition, the entry SHOULD include a superseded_by field referencing the
id of the successor GNA.

Consumers of the directory MUST treat superseded GNA IDs as historically
valid and MUST NOT reinterpret or reassign identifiers issued under a prior
authority.

Timestamp Requirements

All timestamps in the GCVE GNA Directory File MUST conform strictly to
RFC 3339 and MUST be expressed in UTC. The use of the Z suffix is
REQUIRED.

File Format

  • Format: JSON
  • Encoding: UTF-8
  • Top-level structure: Array of GNA objects
  • Timestamp format: RFC 3339 (UTC)

GNA Entry Fields

Each GNA entry MAY contain the following fields:

Field name Type Required Description
id integer YES Unique numeric GNA identifier
short_name string YES Short, human-readable identifier
full_name string YES Full legal or organizational name
status string NO Lifecycle state of the authority
superseded_by integer NO Identifier of the successor GNA
usage string NO Normative usage description or restrictions
cpe_vendor_name string NO Associated CPE vendor name
gcve_url string NO Public vulnerability disclosure page
gcve_api string NO API endpoint providing GCVE-compatible data
gcve_dump string NO Bulk data or advisory feed
gcve_allocation string NO Allocation policy or identifier issuance page
gcve_pull_api string NO Endpoint for GCVE pull-based synchronization
inserted_at string YES Entry creation timestamp (RFC 3339, UTC)
updated_at string YES Last metadata update timestamp (RFC 3339, UTC)

status field

When present, the status field MUST take one of the following values:

  • active — currently valid and operational
  • renamed — authority renamed, same operational scope
  • merged — authority merged into another entity
  • acquired — authority acquired by another entity
  • retired — authority no longer active, no successor declared
  • reserved — reserved or special-purpose identifier

If status is renamed, merged, or acquired, the superseded_by field
SHOULD be present.

Notes

  • The usage field is normative when present.
  • Presence in this directory MUST NOT be interpreted as an assertion of
    trustworthiness.
  • Consumers MUST apply their own trust, validation, and policy controls.

Reserved and Special GNA IDs

ID 0 — CVE Program

This GNA ID is used as a prefix and MUST be followed by the official CVE ID.

ID 65535 — Test GNA

This GNA ID is reserved for testing purposes. It may appear in publications
generated by instances testing the publication process; however, any content
produced using this GNA ID MUST NOT be considered valid or authoritative.

JSON Schema

The following JSON Schema formally defines the structure of the GCVE GNA
Directory File.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gcve.eu/schema/gcve-bcp-08-gna-directory.json",
  "title": "GCVE GNA Directory File (GCVE-BCP-08)",
  "type": "array",
  "items": {
    "type": "object",
    "required": ["id", "short_name", "full_name", "inserted_at", "updated_at"],
    "properties": {
      "id": {
        "type": "integer",
        "minimum": 0
      },
      "short_name": {
        "type": "string",
        "minLength": 1
      },
      "full_name": {
        "type": "string",
        "minLength": 1
      },
      "status": {
        "type": "string",
        "enum": ["active", "renamed", "merged", "acquired", "retired", "reserved"]
      },
      "superseded_by": {
        "type": "integer",
        "minimum": 0
      },
      "usage": {
        "type": "string"
      },
      "cpe_vendor_name": {
        "type": "string"
      },
      "gcve_url": {
        "type": "string",
        "format": "uri"
      },
      "gcve_api": {
        "type": "string",
        "format": "uri"
      },
      "gcve_dump": {
        "type": "string",
        "format": "uri"
      },
      "gcve_allocation": {
        "type": "string",
        "format": "uri"
      },
      "gcve_pull_api": {
        "type": "string",
        "format": "uri"
      },
      "inserted_at": {
        "type": "string",
        "format": "date-time",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
      }
    },
    "additionalProperties": false
  }
}
1 Like