Add OPEV 0016

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