RFD for Assertion Framework

[jayjacobs]

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.

[sei-vsarvepalli]

Some points to consider post meeting on Jan 15 1600 hrs.

1. For all dates, use RFC3339 instead of ISO 8601 as a standard for more strict/tight definition of date timestamp.
2. Consider assertions.items.value to be values as an array allowing for an assertion (or an evaluation) performed by an analyst has provided can be more than one - more like a negation where an assertions states exploitation is NOT None but can be PoC or Active for example with the SSVC example where exploitation item can have three potential values ["None", "PoC" , "Active"] - all the analyst knows is that Exploitation is not None but wants to pass on that information.
3. The assertions.definition.url should it be a required permalink and should we use this URL to dynamicallyverify the CVE submission by CVE Services. This could mean operational impact on having to dynamically verify the incoming assertions - may or may be viable. The schema is very much like embedded schema or $ref like idea in JSON allowing for some complexity in schema setup, This may also complicate test cases if they are entirely open-ended for programatic verification.
4. Related to the above, should the accepted namespace (and version) itself be an enum field cvss ssvc cisa limited to well-known providers who can follow certain test cases and they will be added to the namespace enum? to should it be entirely open-ended?
5. Will the metrics assertions data provided by the CNA support multiple languages? Related to will the namespace be restricted or verified? for example assertions[].items[].key is always expected in US English "en" or can it be in other languages? In our SSVC namespace of ssvc/jp-JP the decision point definition 攻撃の自動化可否 is an accepted field.

[darakian]

Rendered version for ease of reading:
https://github.com/jayjacobs/cve-schema/blob/3452b26dd95664a9e0c278812cd80d6df61d4658/rfds/0000-assertion-framework.md

Full disclosure before my comments; I have not yet read the FAIR Guiding Principles doc yet.

---

My comments on reading the rendered RFD:
Love the shift of the language from metrics to assertions as well as . I question if that will change the behavior in readers, but it at least starts the conversation. I think I'm going to have a few nits on the json specifics as I noodle on this. Should namespace/version be inferred from the definition url? comes to mind.

Governance is the real sticking point though. I'm not in love with the idea of a totally unrestricted approach to namespaces/definition urls. I'm also aware of the friction that can arise from trying to add a value to an enum though so..... I dunno.

---

Some comments on @sei-vsarvepalli 's comments:

1. For all dates, use RFC3339 instead of ISO 8601 as a standard for more strict/tight definition of date timestamp.

Hard disagree. The rest of the schema is using ISO 8601 and its better to conform for the sake of consistency.
This came up in the QWG today and it seems there is consensus to move to rfc3339. I would suggest we wait for that rfd before changing it here.
https://www.cve.org/Media/News/item/blog/2026/01/06/Historic-CVE-Record-Date-Time-Fields-Normalized

2. Consider assertions.items.value to be values as an array allowing for an assertion (or an evaluation) performed by an analyst has provided can be more than one - more like a negation where an assertions states exploitation is NOT None but can be PoC or Active for example with the SSVC example where exploitation item can have three potential values ["None", "PoC" , "Active"] - all the analyst knows is that Exploitation is not None but wants to pass on that information.

How does the analyst know an Exploitation is not None without knowing what the some is? Keeping assertions as positive statements keeps things simple.

3. The assertions.definition.url should it be a required permalink and should we use this URL to dynamically verify the CVE submission by CVE Services.

Requiring permalinks is not enforceable and asking for such a requirement is not reasonable. If anything CVE services could cache the content at the other end of the link. Perhaps a future improvement could be to define a structure for what's expected at the other end of that link (markdown, json, yaml, specific fields, whatever).

5. Will the metrics assertions data provided by the CNA support multiple languages? Related to will the namespace be restricted or verified?

Restrict to ISO 639 values?
https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
Specific language choices on specific records are bound to be limited by the analyst(s).

[jayjacobs]

One thing that came up as I was thinking of a use case today is adding a qualifier option in the assertions. I think this would address @sei-vsarvepalli second point. In the case where someone wishes to set a key to value, but they wish to qualify the relationship as a negative. Adding an optional qualifier field that allows "True", "False", and "Unknown" would enable individual relationships to be expressly set as positive, negative, or unknown.

I think this is more applicable for frameworks that would allow multiple values per key, but I do think it may help the SSVC case to communicate partial knowledge or information.

For example:

    "items": [
        { "key": "exploitation", "value": "none", "qualifier": "False" },
        { "key": "exploitation", "value": "PoC", "qualifier": "Unknown" },
        { "key": "exploitation", "value": "Active", "qualifier": "Unknown" },
        { "key": "automatable", "value": "no" },
        { "key": "technicalImpact", "value": "total" }
    ]

Although, since the second and third relationships for exploitation are being qualified with "unknown," they would be treated that way if those key/value combinations were omitted completely from the record.

One specific use case where this came up is if we were trying to enumerate something like prerequisites to exploitation. For example, let's say we know for sure that we can execute code remotely, but only if there is a specific configuration and we know it's possible to exploit before authentication:

    "items": [
        { "key": "prerequisite", "value": "network_access", "qualifier": "True" },
        { "key": "prerequisite", "value": "non_default_config", "qualifier": "True" },
        { "key": "prerequisite", "value": "authentication", "qualifier": "False" }
    ]

Other points from @sei-vsarvepalli:

1. Agreed, will make the change
   3-5: I think these are all up for discussion...
   3: "The schema is very much like embedded schema or $ref like idea" - Yes, but with the caveat that it may be easier to support extending the data in the record without forcing the consumer to parse new formats and fields. I also think this is a solution to the wild west world of x_ data.
   4: This is mentioned in the "unresolved questions," I think. Whether we limit the known json schemas and namespace is a governance and implementation question, and very much up for question. But right now, anyone can add whatever gnarly, complex, useless, or helpful data they want with the x_ allowances, so we are arguably worse off in our current situation than if namespace and definition json are wide open. Under this proposal, we could at least systematically validate the ad hoc additions and ensure consumers would be able to ingest them with existing logic.
   5: Multi-lingual support would be awesome, and I don't see any obstacles to it, do you?

[ccoffin]

Jay,

I think you and i have discussed some of these already, but thought i would post my original takeaways for everyone else to see.

After reading through the Assertion Framework RFD again and discussing it with a few others, I have come away with some additional questions and thoughts. One thing that I have wrestled with multiple times in the past is whether the JSON should be considered the presentation of the CVE data. Is the CVE Record JSON our data storage and transfer mechanism, or should it be considered the presentation of the CVE Record? My current thinking is that it’s the former and NOT the latter. With that in mind, does the surface area or number of fields within the JSON schema really make a difference to the average consumers (the 80%) of CVE Records? In other words, are the average users/defenders looking directly at the CVE Record JSONs, or are they viewing the web pages on NVD/cve.org or looking at a page in their security tool that has presented the information in yet some other visual way.

Which users/personas would directly benefit from implementing this proposal? Would adjusting how metric and tag data are stored within the CVE Record make a difference in how the average CVE consumers ingest the data today, or would our time and effort be better spent implementing new fields that capture data not yet present in the schema (e.g., remediation or action items)? I know that there are some power users that work directly with the CVE JSON and may see benefit from this proposal, but my understanding is that this is a much smaller subset of consumers? Maybe a next step is to have a conversation with the CWG to determine how the JSON Records are used by the average CVE consumer and where this issue falls on their radar, if at all. Answering some of these questions would not only help with understanding value of this RFD proposal, but could help us figure out how/if to proceed with many other CVE Record Format JSON proposals.

Last, this is a fairly big change and if we did decide to implement it would definitely need to be part of a major version update. I know you mentioned it but wanted to emphasize for the comment readers.