From df2e5e43e1acd9146584d54d705d6c7ffcb105f7 Mon Sep 17 00:00:00 2001 From: Guilherme Macedo Date: Thu, 19 Mar 2026 08:38:18 -0300 Subject: [PATCH] Add OPEV 0016 Signed-off-by: Guilherme Macedo --- enhancements/opev-0016.md | 144 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 enhancements/opev-0016.md diff --git a/enhancements/opev-0016.md b/enhancements/opev-0016.md new file mode 100644 index 0000000..0125df4 --- /dev/null +++ b/enhancements/opev-0016.md @@ -0,0 +1,144 @@ +# OPEV #0016: Addition of Vulnerability Rating Field + +OpenVEX fully implements the VEX specification as developed by +[NTIA][ntia-vex-spec] and [CISA][cisa-vex-spec]. Other standards like CSAF +(Common Security Advisory Framework) and CycloneDX allow enriching VEX reports, +inside their own formats, by providing extra information like vulnerability +scoring, risks and remediation. While OpenVEX was created to be a minimal and +simple VEX implementation, and we must maintain it in this way, there is space +to extend OpenVEX while retaining its core values - minimal, compliant, +interoperable, and embeddable. + +This proposal aims to extend OpenVEX by adding a rating object that allows to +provide information about a vulnerability's score according to the context of +each product (severity re-scoring). While this capability isn't covered in the +main VEX spec, CISA's [VEX Use Cases][cisa-vex-use-cases] document mentions +about vulnerabilities' score and other resources that can be added to a VEX +document: + +> Various other details, such as CVSS scores or links to other resources can be +> added to a VEX document to add value for the customer. + +By adding further context about a vulnerability's score we can complement the +benefits already provided by OpenVEX. + +## Issues Addressed by This OPEV: + +This proposal addresses the specification issues [openvex/spec#31] and +[openvex/spec#60] to allow including vulnerability's score in a non-breaking way +to extend the OpenVEX spec. + +## Enhancement Proposal + +The `vulnerability`'s `ratings` will be an optional list field of the +vulnerability data structure. + +```json +{ + "@context": "https://openvex.dev/ns/v0.2.0", + "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57", + "author": "Wolfi J Inkinson", + "role": "Document Creator", + "timestamp": "2023-01-08T18:02:03.647787998-06:00", + "version": 1, + "statements": [ + { + "vulnerability": { + "name": "CVE-2025-68121", + "ratings": [ + { + "source": { + "name": "Acme", + "url": "https://www.example.com/" + }, + "severity": "high", + "score": 7.1, + "vector": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:N" + }, + { + "source": { + "name": "Acme", + "url": "https://www.example.com/" + }, + "severity": "high", + "score": 7.6, + "vector": "CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:H/VI:H/VA:N/SC:N/SI:N/SA:N" + } + ] + }, + "products": [ + { + "@id": "pkg:golang/github.com/rancher/rke2@v1.29.15+rke2r1", + "subcomponents": [ + { + "@id": "pkg:golang/stdlib@v1.23.6" + } + ] + } + ], + "status": "affected", + "status_notes": "The severity of the vulnerability is reduced due to the high attack complexity required to exploit the issue and because additional countermeasures are implemented in the product." + } + ] +} +``` + +### Full Spec and New Fields + +The new `ratings` object extends the vulnerability data structure. + +| Field | Required | Description | +| ----- | -------- | ----------- | +| source | ✕ | An object that contains information about the entity that is providing the vulnerability's rating. | +| source.name | ✕ | The `name` of the entity providing the rating. | +| source.url | ✕ | A `url` linking to a page that further describes the vulnerability or the rating. | +| severity | ✕ | A string representing the vulnerability's rating. | +| vector | ✕ | A string in CVSS or other format for scoring the vulnerability. | +| score | ✕ | A numerical representation of the vector string. | + +Considerations about when to provide `severity`, `vector` and/or `score` fields: + +- If a `ratings` object is added to a `vulnerability`, then at least a + `severity` or a `vector` must be provided, otherwise there is no purpose in + having an empty object that contains no actionable rating for the + vulnerability. +- Strict formatting of `severity` isn't enforced, because some authors might + prefer to use the `moderate` severity instead of `medium` or `important` + instead of `high` or 3 severity levels (`low`, `medium`/`moderate` and + `high`/`important`) instead of 4 (`low`, `medium`/`moderate`, + `high`/`important` and `critical`). +- If the `vector` field is provided, then `score` must be derived from it. The + derivation is the author's responsibility. +- It is expected that authors using the `ratings` object will adhere to the CVSS + format for the `vector` and `score` representation of the rating. However, no + explicit requirement is made to enforce the existing versions of CVSS. This + allows the `ratings` object to be flexible enough for the specific purposes of + each author and its consumers, as well as to support other vector scores, like + OWASP's risk rating methodology, without having to constantly update the + OpenVEX spec. +- It is the author's responsibility to provide the above fields with values that + are usable by its consumers, be them human or vulnerability scanners. + +### Final Considerations + +When a `vulnerability` is reported with `status` `affected` and has a `ratings`, +then the statement's field `status_notes` can be used to provide further context +about how the rating was calculated for the vulnerability regarding the affected +product. + +The enhancement proposed in this OPEV empowers users to maintain their own +vulnerabilities database in a simple and minimal format with reduced effort. +Major vendors have to rely on complex vulnerability formats like CSAF (Common +Security Advisory Format), CVRF (Common Vulnerability Reporting Framework), OVAL +(Open Vulnerability and Assessment Language) and others to provide standardized +information about vulnerabilities affecting their products, besides requiring to +integrate their reports with every vulnerability scanner available. Now, authors +and vendors can maintain simple OpenVEX documents that are already integrated +with major vulnerability scanners (as soon as a security scanner adds support to +OpenVEX, all authors and vendors automatically benefit from it). + +[ntia-vex-spec]: https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf +[cisa-vex-spec]: https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf +[cisa-vex-use-cases]: https://www.cisa.gov/sites/default/files/publications/VEX_Use_Cases_Aprill2022.pdf +[openvex/spec#31]: https://github.com/openvex/spec/issues/31 +[openvex/spec#60]: https://github.com/openvex/spec/issues/60