diff --git a/enhancements/opev-0016.md b/enhancements/opev-0016.md new file mode 100644 index 0000000..7874cd6 --- /dev/null +++ b/enhancements/opev-0016.md @@ -0,0 +1,152 @@ +# OPEV #0016: Addition of Vulnerability Severity 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 rating and score according to the +context of each product (severity rating/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 rating/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 `rating` will be an optional list field of the `statements` 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" + }, + "rating": { + "source": { + "name": "Acme - Security team", + "url": "https://www.example.com/cves/cve-2025-68121.html" + }, + "severities": [ + { + "type": "cvss_v3", + "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H/CR:X/IR:X/AR:X/MAV:X/MAC:X/MPR:H/MUI:X/MS:U/MC:L/MI:L/MA:L" + }, + { + "type": "cvss_v4", + "score": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H/MAC:H/MAT:P/MPR:H/MSC:L/MSI:L/MSA:L" + }, + { + "type": "owasp", + "score": "SL:6/M:0/O:7/S:6/ED:7/EE:5/A:9/ID:0/LC:2/LI:1/LAV:1/LAC:1/FD:1/RD:1/NC:2/PV:3" + }, + { + "type": "ssvc_v2", + "score": "SSVCv2/E:P/A:Y/T:P/P:M/B:M/M:L/D:T/2026-05-07T13:36:27Z/" + }, + { + "type": "sev", + "score": "medium" + } + ] + }, + "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 `rating` object extends the `statements` 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. | +| severities | x | An object containing zero or more severities of the vulnerability. | +| type | x | Specify the format used to calculate the vulnerability's severities. | +| score | ✕ | A string in one of the supported `type` used to rate the vulnerability. | + +For the severities to be valid, `type` and `score` must be provided and be valid, as +explained below. + +- The `type` specifies how to parse the `score` string and must be one of the + following: + - `cvss_v2` - for the CVSS v2.0 format. + - `cvss_v3` - for the CVSS v3.x format. + - `cvss_v4` - for the CVSS v4.x format. + - `owasp` - for the OWASP Risk Rating Methodology format. + - `ssvc_v2` - for the CISA Stakeholder-Specific Vulnerability Categorization v2.x format" + - `sev` - a string containing directly the rating/severity. +- The `score` string must be provided according to the format specified + in `type. +- The proper validation of `type` and `score` are the responsibility of the + author of the report. +- If `type` and `score` don't match, then the consumer of the report must + ignore the specific rating. +- If more than one severity is provided, it is up to the consumer of the report + to decide which severity to use, for example, the highest one or the first + one. +- 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 +`rating`, 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