Skip to content

0000-assertion-framework.md

Latest commit

 

History

History
453 lines (364 loc) · 27.6 KB

0000-assertion-framework.md

File metadata and controls

453 lines (364 loc) · 27.6 KB

RFD-0000: Extensible Assertion Framework for CVE Records

  • Status: Draft
  • Authors: Jay Jacobs
  • Created: 2026-01-08
  • Updated: 2026-01-08
  • Target: CVE Record Format v6.x (or later)
  • Related: SSVC RFD (PR #460)
  • Affected Section: Tags, Metrics

Summary

This RFD proposes a new section in the CVE record called “assertions” to replace both the “metrics” and “tag” sections. This change will:

  • Support the addition of new frameworks (like SSVC) and new framework versions (like CVSS 4.0) without requiring the core CVE schema to be updated. All assertion instances will follow a standardized json structure with atomic key/value items.
  • Reduce schema surface area and downstream processing burden across the CVSS versions (CVSS data is spread across over 80 data elements, while the next largest section, the “affected” section currently is spread across 29 data elements).
  • Support good data stewardship by focusing on data that is machine-usable and not just machine-readable. This is done through Assertion Definitions that strive to implement the FAIR data principles (no relation to FAIR CRQ, see The FAIR Guiding Principles for scientific data management and stewardship).
  • Remove ambiguity of existing tagging by clarifying the difference between “no” and “unknown” (e.g. if a CVE does not have the “unsupported when assigned” tag, users are unsure if there is product support or the CNA just didn’t bother to set the optional tag)
  • Shift the framing of “metrics”. By relabeling framework outputs from “metrics” to “assertions” we will reduce reification by making clear these values are publisher claims produced by a method (e.g., CVSS/SSVC), not universal facts. This should improve machine-usable provenance, comparability across sources, and safer downstream reuse. As example, Vulnrichment currently does not add CVSS vectors when the CNA has them, but Vulnrichment probably uses a repeatable process, defined sources and methods that offer a consistency not found across the disparate CNA sources.
  • Enable CNAs and ADPs to put forth their own custom assertions in a way that will not expand the schema or require schema updates thus not breaking downstream parsers. Because of the reliance on the assertion definitions, custom assertions will be forced to define and document the data elements being put forth that will make it easier for other CNAs and ADPs to also assign the assertion and make it much more likely that the data will be machine-usable right away.

Note: We could minimize overall impact to the schema and just support this for SSVC adoption and later expand into CVSS and tags.

Proposed Solution

This RFD introduces a definition-driven Assertion Framework to make CVE data more machine-usable while reducing schema churn and downstream consumer processing burden. The framework adds a new, optional “assertions” field to the CNA (and ADP) container. Each assertion group is a small, regular, schema-validated structure whose keys and value constraints are governed by a referenced, versioned Assertion Definition Document.

Record format changes

Add “assertions” section to CNA (and ADP) containers

Add an optional assertions array to each container that currently follows the CNA/ADP schema surface (e.g., container.cna and each container.adp).

Define Assertion group structure

Each entry in assertions[] is an Assertion Group. An Assertion Group represents a set of atomic key/value assertions, optionally grouped under a single, timestamped definition reference. The grouping enables a single assertion to contain multiple dimensions (e.g. CVSS vector and base score)

Assertion Group fields

  • definition (required): reference to an Assertion Definition Document:
    • url (required): URI to a resolvable definition document
    • namespace (required): logical namespace for the definition, matches namespace in the definition document (e.g., “ssvc”, “cvss”, “tag”)
    • version (required): version identifier for the definition document
  • assertedAt (required): ISO 8601 date-time applying to the group
  • items (required): array of key/value assertion items (see next section)
  • references (optional): array of URIs (group-level references)
  • notes (optional): free text (group-level)

Assertion Item fields (“items” array from Assertion Group)

  • key (required): string, MUST match a key declared in the referenced definition document
  • value (required): any JSON type, including null; MUST conform to the key’s declared valueSchema in the assertion definition document
  • evidence (optional): array of URIs providing evidence for this item
  • notes (optional): free text for human context and understanding

Machine-usable constraints (schema-level)

  • Assertion Groups and Assertion Items MUST be closed objects (“additionalProperties” set ot false in the schema) to prevent uncontrolled growth and to explicitly disallow x_* escape hatches within the mechanism.
  • items[].value is intentionally type-agnostic at the record-schema level; typing is enforced via the definition document (see validation rules below).
  • The meaning of a missing assertion (or key within a grouped assertion) is explicitly undefined:
    • If an assertion group is absent, the record makes no claim under that assertion definition.
    • If a key is absent from items[], that key is undefined for that group (nothing should be inferred, absence is not a negative).
    • If “Unknown/not evaluated” is a valid value, it should be represented explicitly by the value domain defined for that key (e.g., allowing null, or including an "unknown" enum value). This is required to avoid relying on absence as an epistemic signal.

Deprecate the “metrics” and “tags” sections.

The new assertion framework will replace the “metrics” and “tags” sections. Those two sections can be removed from the schema definitions.

Assertion Definition Documents (external, versioned)

An Assertion Definition Document is a JSON document referenced by definition.url. It enumerates:

  • The metadata for each assertion including the namespace, version, human-readable title and description and optional URL(s) for more information about the assertion.
  • the allowed set of keys for a definition family, and
  • the value constraints for each key via a JSON Schema fragment

This enables machine-usable data by ensuring that every asserted key is defined and every asserted value has a known, validated shape.

Minimal required fields for a definition document

  • namespace (required): string, short text that matches the namespace defined in the assertions, one assertion document may contain more than one namespace.
  • version (required): string, version of this assertion definition, matches the namespace defined in the assertions.
  • title (required): string, brief, human-readable title of this assertion namespace
  • description (required): string, human-readable text describing the purpose and goals of the assertion.
  • author (required): string, the author(s) (and a contact method?)
  • reference (optional): array, one or more URLs for more information about this assertion defintion
  • keys (required) array, where the key/value pairs are defined.
    • title (required): the human-readable title (or prompt) for this object (e.g. “CVSS Vector String”, “Attack Vector” or “Privileges Required”)
    • description (required): string, the human-readable description of the item (e.g. “A textual representation of the metric values used to score the vulnerability”, “the context by which vulnerability exploitation is possible” or “the level of privileges an attacker must possess before successfully exploiting the vulnerability”)
    • key (required): string, the machine-usable key for this object, must be unique in the namespace (e.g. “vector”, “av” or “pr” for CVSS 3.1). The key consists only of letters, numbers and underline characters and must always start with a letter (“2be” and “_identifier” are not valid key names).
    • valueSchema (required), object, the JSON Schema fragment to enforce the values.

All keys declared in keys[] are optional for publishers to provide. The definition document specifies what keys may be asserted; it does not require that all keys be present.

Validation rules (normative)

Because JSON Schema cannot enforce remote lookups, this RFD defines a two-layer validation model.

Schema validation (local)

A submitted record MUST validate against the CVE Record Format schema, including the structure of the “assertions” field and the closed-object constraints described above.

Definition-driven validation (CVE Services / ingestion logic)

For each Assertion Group:

  • CVE Services (or any conforming ingestion system) MUST retrieve definition.url (or retrieve a cached copy maintained by the service).
  • The retrieved document MUST validate against the Assertion Definition Document schema.
  • For each Assertion Item:
    • key MUST exist in the definition document’s keys[].key.
    • value MUST validate against the matched key’s valueSchema.
    • If evidence is present, each entry MUST be a valid URI.

If retrieval fails, the definition document is invalid, a key is not declared, or a value fails validation, validation MUST fail.

Examples

Examples below are illustrative. All URLs are placeholders.

Example 1: SSVC decision points (single assertion group)

{
  "assertions": [
    {
      "definition": {
        "url": "https://example.org/definitions/ssvc/deployer/2.0.0.json",
        "namespace": "ssvc",
        "version": "2.0.0"
      },
      "assertedAt": "2026-01-09T12:00:00Z",
      "items": [
        {
          "key": "exploitation",
          "value": "active",
          "evidence": ["https://example.org/evidence/exploit-observed"]
        },
        { "key": "automatable", "value": "no" },
        { "key": "technicalImpact", "value": "total" }
      ]
    }
  ]
}

Example 2: Multiple CVSS versions in the same record (two assertion groups)

{
  "assertions": [
    {
      "definition": {
        "url": "https://example.org/definitions/cvss/3.1/1.0.0.json",
        "namespace": "cvss",
        "version": "1.0.0"
      },
      "assertedAt": "2026-01-09T12:00:00Z",
      "items": [
        { "key": "cvssVersion", "value": "3.1" },
        {
          "key": "vectorString",
          "value": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
        },
        { "key": "baseScore", "value": 9.8 }
      ]
    },
    {
      "definition": {
        "url": "https://example.org/definitions/cvss/4.0/1.0.0.json",
        "namespace": "cvss",
        "version": "1.0.0"
      },
      "assertedAt": "2026-01-09T12:00:00Z",
      "items": [
        { "key": "cvssVersion", "value": "4.0" },
        { "key": "vectorString", "value": "CVSS:4.0/..." },
        { "key": "baseScore", "value": 9.3 }
      ]
    }
  ]
}

Example 3: Tag-like assertion expressed as an explicit value

{
  "assertions": [
    {
      "definition": {
        "url": "https://example.org/definitions/tag/product_lifecycle/1.0.0.json",
        "namespace": "tag",
        "version": "1.0.0"
      },
      "assertedAt": "2026-01-09T12:00:00Z",
      "items": [
        {
          "key": "product_unsupported",
          "value": true,
          "evidence": ["https://vendor.example/support-lifecycle"]
        },
        { "key": "open_source_library", "value": false },
      ]
    }
  ]
}

Impact Assessment

Note: We could minimize overall impact to the schema and just support this for SSVC adoption and later expand into CVSS and tags.

Benefits

  • Improved machine-usability: Every asserted key is defined, and every value is validated against a declared schema, enabling reliable parsing, comparison, and downstream reuse.
  • Reduced schema churn: New frameworks and new ADP enrichments can be supported by publishing new definition documents rather than requesting new record schema fields.
  • Lower consumer processing burden over time: Consumers can implement a single generic assertion parser and then interpret assertion families via definition documents, rather than hardcoding new framework structures into record parsing logic.
  • Controlled extensibility: Closed objects and “no undefined keys” reduce the risk of uncontrolled growth and improve interoperability compared to ad hoc use of “other” section.
  • Supports the eventual separation of data storage from data presentation: Because the data is machine-usable we can offer versions of the data that match existing formats, (e.g. integrate the titles from the assertion definitions) or actually applies logic to defined fields (e.g. breaking out CVSS vectors into the individual JSON fields present in the JSON 5.x definitions)

Risks / Tradeoffs

  • Definition fragmentation: If many near-duplicate definitions emerge, consumers may still need crosswalks between similar assertion families. This mechanism enables interoperability but does not guarantee ecosystem convergence.
  • Operational dependency on definition retrieval: CVE Services must retrieve (or cache) definition documents and perform cross-document validation; this introduces availability and operational dependencies.
  • Schema vs application logic: Cross-document validation cannot be enforced purely in JSON Schema and therefore requires explicit CVE Services validation logic in software to ensure each assertion in a record are within the allowed values for the stated key.

Compatibility and Migration

This change is expected to be a rather big change. It adds an entirely new section, new data elements and schema as well as additional logic to validate assertions to an external definition. It also could potentially change the way CVSS is encoded. The “metrics” section could be deprecated along with the “tags” section. Although, we could minimize overall impact to the schema and just support this for SSVC adoption and later expand into CVSS and tags.

Migration expectations

  • CNAs / ADPs: Will need to update tooling to encode CVSS and/or SSVC and tags into the new assertion framework.
  • CVE Services: Must accept the new section and implement the ingestion-time validation logic described in this RFD (including definition retrieval/caching and key/value validation).
  • Consumers: Consumers that want the added value of assertions must implement parsing of the new section and (optionally) retrieval/caching of definition documents to validate and interpret values. Consumers will no longer need to support parsing of multiple sections for CVSS.

Rollout considerations (non-normative)

  • Communicate the new field and validation behavior in advance of enabling strict validation in production.
  • Provide a testing environment where CNAs/ADPs can submit assertion-bearing records and receive actionable validation errors.

Success Metrics

Timeline

TBD

Quantitative metrics (unambiguous)

TBD

Rollback criteria and path

TBD

Supporting Data or Research

This proposal is motivated by:

  • the RFD to directly support SSVC in specialized fields, requiring data pipeline updates and yet another framework that will add only marginal value from the new data elements
  • A personal frustration with the complexity of parsing the existing metrics section and the four different CVSS versions.
  • The growing landscape of alternative vulnerability databases, by making “assertions” flexible and machine-usable we encourage other databases to adopt the same format that they can then extend and expand the corpus of assertion definitions.
  • A personal goal to reduce the overall complexity of CVE records and the burden being pushed to consumers. - see Appendex.

Evidence supporting the need includes:

  • the large and growing number of distinct fields in metrics (including multiple concurrent CVSS versions), and
  • the emergence of structured framework content under flexible extension points (e.g., SSVC-like structures under other).

Related Issues or Proposals

  • SSVC integration proposals (including SSVC-focused RFD(s)).
  • Existing and future proposals regarding tag semantics, “other” usage, and reduction of ad hoc extensions.
  • Any related proposals addressing metric normalization or multi-version representation.

Recommended Priority

High. This RFD targets a core deficiency affecting machine-usability and ecosystem processing cost: repeated schema churn to support new frameworks and ADP enrichments, and inconsistent encoding of similar claims across tags/metrics/other. A generic assertion mechanism addresses these issues while enabling immediate SSVC support and future-proof extensibility.

Unresolved Questions

  1. Assertion Definition Governance: Should the CVE program manage and host all of the assertion definitions, or should we allow anyone to publish their own assertion definition at any URL and reference it?
  2. Assertion Definition caching/hosting policy: If the definitions are not centralized, the CVE program may want to consider caching the assertion definitions to plan for link rot of the definitions. This may also happen if there are many versions of assertions where older versions may be removed from its hosting location.
  3. Convergence mechanisms: We may want to offer some guidance to promote good assertion definitions that promote computation convergence (different analysts arriving at the same value given the same information). This may include things like naming conventions, common definitions of terms and concepts, good practices for key/value requirements and so on.
  4. Baseline definition set: Can we do all of the basic assertion definitions up front or do we need to prioritize which definition documents should be published first (SSVC, CVSS bundles, common tag-like assertions) to maximize early utility?

Future Possibilities

  • Assertions in other areas of the CVE record: If the assertions are used and useful, they could be scattered in other areas, for example they could be used in the “affected” section to add assertions about different affected products.
  • Tag deprecation guidance: As structured assertions gain adoption, deprecate specific tags in favor of explicit assertion values where appropriate.
  • Easy expansion of tags: Adding in other tags (such as “on cisa kev”) could easily be added without schema updates and the “assertedAt” fields enable point-in-time assertions.
  • Definition snapshotting: If reproducibility becomes a concern (e.g., definition changes or link rot), introduce optional mirroring or snapshot identifiers for definition documents without requiring full cryptographic pinning in v1.
  • Extended provenance: Add optional structured provenance elements (e.g., method/tool identifiers) if needed for machine-usable auditability of assertion production workflows.

Appendix A: List of Fields in Metrics

This data is pulled from the Github repository as of 2026-01-10 12:21:46 CST. It identifies the distinct json fields in either the CNA and ADP container(s) and will record which CVE has one or more of those fields independent of which container it appeared in.

  section             cves fields  
1 metrics.other     128071     43  
2 metrics.cvssV3_1  118310     30  
3 metrics.cvssV4_0   16463     27  
4 metrics.cvssV3_0   25377     17  
5 metrics.cvssV2_0   11073      9

Other Metrics

key cves
1 metrics.other.type 128071
2 metrics.other.content.version 127619
3 metrics.other.content.timestamp 127601
4 metrics.other.content.id 127601
5 metrics.other.content.options.Exploitation 127601
6 metrics.other.content.options.Automatable 127601
7 metrics.other.content.options.Technical Impact 127601
8 metrics.other.content.role 127601
9 metrics.other.content.dateAdded 1481
10 metrics.other.content.reference 1481
11 metrics.other.content.value 1027
12 metrics.other.content.namespace 983
13 metrics.other.content.text 697
14 metrics.other.content.other 195
15 metrics.other.content.vectorString 89
16 metrics.other.content.description.description_data.lang 88
17 metrics.other.content.description.description_data.value 88
18 metrics.other.content.lang 44
19 metrics.other.content.url 44
20 metrics.other.content.attackComplexity 38
21 metrics.other.content.attackVector 38
22 metrics.other.content.availabilityImpact 38
23 metrics.other.content.baseSeverity 38
24 metrics.other.content.confidentialityImpact 38
25 metrics.other.content.integrityImpact 38
26 metrics.other.content.privilegesRequired 38
27 metrics.other.content.scope 38
28 metrics.other.content.userInteraction 38
29 metrics.other.content.baseScore 36
30 metrics.other.content.Automatable 5
31 metrics.other.content.Exploitation 5
32 metrics.other.content.Technical Impact 5
33 metrics.other.content.selections.namespace 5
34 metrics.other.content.selections.version 5
35 metrics.other.content.selections.name 5
36 metrics.other.content.schemaVersion 4
37 metrics.other.content.Value Density 3
38 metrics.other.content.selections.values.key 3
39 metrics.other.content.selections.values.name 3
40 metrics.other.content.selections.definition 3
41 metrics.other.content.selections.key 3
42 metrics.other.content.selections.values 2
43 metrics.other.content.ssvc 1

CVSS 2.0 Metrics

key cves
1 metrics.cvssV2_0.version 11073
2 metrics.cvssV2_0.baseScore 11073
3 metrics.cvssV2_0.vectorString 11073
4 metrics.cvssV2_0.accessComplexity 159
5 metrics.cvssV2_0.accessVector 159
6 metrics.cvssV2_0.authentication 159
7 metrics.cvssV2_0.availabilityImpact 159
8 metrics.cvssV2_0.confidentialityImpact 159
9 metrics.cvssV2_0.integrityImpact 159

CVSS 3.0 Metrics

key cves
1 metrics.cvssV3_0.version 25377
2 metrics.cvssV3_0.baseScore 25377
3 metrics.cvssV3_0.vectorString 25377
4 metrics.cvssV3_0.baseSeverity 25377
5 metrics.cvssV3_0.attackComplexity 11895
6 metrics.cvssV3_0.attackVector 11895
7 metrics.cvssV3_0.availabilityImpact 11895
8 metrics.cvssV3_0.confidentialityImpact 11895
9 metrics.cvssV3_0.integrityImpact 11895
10 metrics.cvssV3_0.privilegesRequired 11895
11 metrics.cvssV3_0.scope 11895
12 metrics.cvssV3_0.userInteraction 11895
13 metrics.cvssV3_0.exploitCodeMaturity 2313
14 metrics.cvssV3_0.remediationLevel 2313
15 metrics.cvssV3_0.reportConfidence 2313
16 metrics.cvssV3_0.temporalScore 2313
17 metrics.cvssV3_0.temporalSeverity 2313

CVSS 3.1 Metrics

key cves
1 metrics.cvssV3_1.version 118310
2 metrics.cvssV3_1.baseScore 118310
3 metrics.cvssV3_1.baseSeverity 118310
4 metrics.cvssV3_1.vectorString 118310
5 metrics.cvssV3_1.scope 91179
6 metrics.cvssV3_1.attackVector 91179
7 metrics.cvssV3_1.integrityImpact 91179
8 metrics.cvssV3_1.userInteraction 91179
9 metrics.cvssV3_1.attackComplexity 91179
10 metrics.cvssV3_1.privilegesRequired 91179
11 metrics.cvssV3_1.confidentialityImpact 91179
12 metrics.cvssV3_1.availabilityImpact 91175
13 metrics.cvssV3_1.exploitCodeMaturity 2607
14 metrics.cvssV3_1.temporalScore 2600
15 metrics.cvssV3_1.temporalSeverity 2600
16 metrics.cvssV3_1.remediationLevel 2561
17 metrics.cvssV3_1.reportConfidence 2561
18 metrics.cvssV3_1.environmentalScore 2083
19 metrics.cvssV3_1.environmentalSeverity 2083
20 metrics.cvssV3_1.availabilityRequirement 2044
21 metrics.cvssV3_1.confidentialityRequirement 2044
22 metrics.cvssV3_1.integrityRequirement 2044
23 metrics.cvssV3_1.modifiedAttackComplexity 2044
24 metrics.cvssV3_1.modifiedAttackVector 2044
25 metrics.cvssV3_1.modifiedAvailabilityImpact 2044
26 metrics.cvssV3_1.modifiedConfidentialityImpact 2044
27 metrics.cvssV3_1.modifiedIntegrityImpact 2044
28 metrics.cvssV3_1.modifiedPrivilegesRequired 2044
29 metrics.cvssV3_1.modifiedScope 2044
30 metrics.cvssV3_1.modifiedUserInteraction 2044

CVSS 4.0 Metrics

key cves
1 metrics.cvssV4_0.version 16463
2 metrics.cvssV4_0.baseScore 16463
3 metrics.cvssV4_0.vectorString 16463
4 metrics.cvssV4_0.baseSeverity 16463
5 metrics.cvssV4_0.attackComplexity 7805
6 metrics.cvssV4_0.attackRequirements 7805
7 metrics.cvssV4_0.attackVector 7805
8 metrics.cvssV4_0.privilegesRequired 7805
9 metrics.cvssV4_0.subAvailabilityImpact 7805
10 metrics.cvssV4_0.subConfidentialityImpact 7805
11 metrics.cvssV4_0.subIntegrityImpact 7805
12 metrics.cvssV4_0.userInteraction 7805
13 metrics.cvssV4_0.vulnAvailabilityImpact 7805
14 metrics.cvssV4_0.vulnConfidentialityImpact 7805
15 metrics.cvssV4_0.vulnIntegrityImpact 7805
16 metrics.cvssV4_0.providerUrgency 5642
17 metrics.cvssV4_0.valueDensity 5642
18 metrics.cvssV4_0.vulnerabilityResponseEffort 5642
19 metrics.cvssV4_0.Recovery 5631
20 metrics.cvssV4_0.Safety 5631
21 metrics.cvssV4_0.Automatable 5630
22 metrics.cvssV4_0.exploitMaturity 1467
23 metrics.cvssV4_0.modifiedAttackVector 1
24 metrics.cvssV4_0.modifiedPrivilegesRequired 1
25 metrics.cvssV4_0.modifiedSubIntegrityImpact 1
26 metrics.cvssV4_0.modifiedSubAvailabilityImpact 1
27 metrics.cvssV4_0.modifiedSubConfidentialityImpact 1