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 operationalrenamed — authority renamed, same operational scopemerged — authority merged into another entityacquired — authority acquired by another entityretired — authority no longer active, no successor declaredreserved — 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
}
}