Add OPEV 0016

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