From df2e5e43e1acd9146584d54d705d6c7ffcb105f7 Mon Sep 17 00:00:00 2001 From: Guilherme Macedo Date: Thu, 19 Mar 2026 08:38:18 -0300 Subject: [PATCH 1/3] 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 From a779336392f2451351cd33a79d50d3a98a6b45bd Mon Sep 17 00:00:00 2001 From: Guilherme Macedo Date: Thu, 7 May 2026 11:00:08 -0300 Subject: [PATCH 2/3] Address feedback from pr and sig meeting Signed-off-by: Guilherme Macedo --- enhancements/opev-0016.md | 121 ++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 57 deletions(-) diff --git a/enhancements/opev-0016.md b/enhancements/opev-0016.md index 0125df4..1c55044 100644 --- a/enhancements/opev-0016.md +++ b/enhancements/opev-0016.md @@ -1,4 +1,4 @@ -# OPEV #0016: Addition of Vulnerability Rating Field +# 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 @@ -9,12 +9,12 @@ 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 +This proposal aims to extend OpenVEX by adding a severity 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: +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. @@ -30,8 +30,8 @@ to extend the OpenVEX spec. ## Enhancement Proposal -The `vulnerability`'s `ratings` will be an optional list field of the -vulnerability data structure. +The `severity` will be an optional list field of the `statements` data +structure. ```json { @@ -44,26 +44,34 @@ vulnerability data structure. "statements": [ { "vulnerability": { - "name": "CVE-2025-68121", - "ratings": [ + "name": "CVE-2025-68121" + }, + "severity": { + "source": { + "name": "Acme - Security team", + "url": "https://www.example.com/cves/cve-2025-68121.html" + }, + "rating": [ + { + "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" + }, { - "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" + "type": "ssvc_v2", + "score": "SSVCv2/E:P/A:Y/T:P/P:M/B:M/M:L/D:T/2026-05-07T13:36:27Z/" }, { - "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" - } + "type": "sev", + "score": "medium" + } ] }, "products": [ @@ -85,46 +93,45 @@ vulnerability data structure. ### Full Spec and New Fields -The new `ratings` object extends the vulnerability data structure. +The new `severity` 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. | -| 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. +| source | ✕ | An object that contains information about the entity that is providing the vulnerability's severity. | +| source.name | ✕ | The `name` of the entity providing the severity. | +| source.url | ✕ | A `url` linking to a page that further describes the vulnerability or the severity. | +| rating | x | An object containing zero or more ratings of the vulnerability. | +| type | x | Specify the format used to calculate the vulnerability's rating. | +| score | ✕ | A string in one of the supported `type` used to rate the vulnerability. | + +For the rating 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 rating is provided, it is up to the consumer of the report to + decide which rating 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 `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. +When a `vulnerability` is reported with `status` `affected` and has a +`severity`, 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. From 1f797fd6995729ae1413129cbc7f7015ea5b4e60 Mon Sep 17 00:00:00 2001 From: Guilherme Macedo Date: Mon, 11 May 2026 14:26:36 -0300 Subject: [PATCH 3/3] Address feedback from pr Signed-off-by: Guilherme Macedo --- enhancements/opev-0016.md | 43 ++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/enhancements/opev-0016.md b/enhancements/opev-0016.md index 1c55044..7874cd6 100644 --- a/enhancements/opev-0016.md +++ b/enhancements/opev-0016.md @@ -9,18 +9,18 @@ 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 severity object that allows to -provide information about a vulnerability's 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: +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 score we can complement the -benefits already provided by OpenVEX. +By adding further context about a vulnerability's rating/score we can complement +the benefits already provided by OpenVEX. ## Issues Addressed by This OPEV: @@ -30,7 +30,7 @@ to extend the OpenVEX spec. ## Enhancement Proposal -The `severity` will be an optional list field of the `statements` data +The `rating` will be an optional list field of the `statements` data structure. ```json @@ -46,12 +46,12 @@ structure. "vulnerability": { "name": "CVE-2025-68121" }, - "severity": { + "rating": { "source": { "name": "Acme - Security team", "url": "https://www.example.com/cves/cve-2025-68121.html" }, - "rating": [ + "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" @@ -93,18 +93,18 @@ structure. ### Full Spec and New Fields -The new `severity` object extends the `statements` data structure. +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 severity. | -| source.name | ✕ | The `name` of the entity providing the severity. | -| source.url | ✕ | A `url` linking to a page that further describes the vulnerability or the severity. | -| rating | x | An object containing zero or more ratings of the vulnerability. | -| type | x | Specify the format used to calculate the vulnerability's rating. | +| 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 rating to be valid, `type` and `score` must be provided and be valid, as +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 @@ -121,15 +121,16 @@ explained below. 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 rating is provided, it is up to the consumer of the report to - decide which rating to use, for example, the highest one or the first one. +- 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 -`severity`, then the statement's field `status_notes` can be used to provide +`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.