Skip to content

Latest commit

 

History

History
130 lines (109 loc) · 4.86 KB

opev-0015.md

File metadata and controls

130 lines (109 loc) · 4.86 KB
Raw

OPEV #0015: Expansion of the Vulnerability Field

During the development of the initial implementations, there have been issues raised about the need to expand the vulnerability field. While this OPEV only addresses the need to expand the vulnerability field 1) become an object and to 2) to express more names or aliases of a vulnerability, members of the community have pointed to other cases where the vulnerability entry needs to be expanded from an identifier string to a full struct.

Issues Addressed by thie OPEV:

This proposal addesses a breaking change to allow for current proposals and allow room for growth for future enhancements. Specifically, this proposal provides a fix for the following issue:

Enhancement Proposal

The current entry for a vulnerability in a VEX statement is only a string capturing the identifier string. This proposal suggests expanding the vulnerability entry to become an object and allow a list of aliases.

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
  "author": "mailto:[email protected]",,
  "timestamp": "2023-01-16T20:41:55.708329108-06:00",
  "statements": [
    {
      "vulnerability": {
        "@id": "https://nvd.nist.gov/vuln/detail/CVE-2019-17571",
        "name": "CVE-2019-17571", 
        "aliases": [
            "GHSA-2qrg-x229-3v8q",
            "openSUSE-SU-2020:0051-1",
            "SNYK-RHEL7-LOG4J-1472071",
            "DSA-4686-1",
            "USN-4495",
            "DLA-2065-1",
        ],
      },
      "timestamp": "2022-10-11T20:29:19Z",
      "products": [
        "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99"
      ],
      "subcomponents": [
        "pkg:apk/wolfi/[email protected]",
        "pkg:apk/wolfi/[email protected]"
      ],
      "status": "fixed"
    }
  ]
}

With this change, the main identifier of the vulnerability entry in the statement now becomes the @id's IRI. A new field is introduced as to capture the main vulnerability name and aditional labels identifying the vulnerability in external tracking systems can be listed under "aliases".

This change introduces a new Vulnerability context native to OpenVEX. As a linked JSON-ld document, the IRI may point to an element in an external document (for example a Vulnerability in an SPDX security document) and still complete the VEX statement:

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
  "author": "mailto:[email protected]",,
  "timestamp": "2023-01-16T20:41:55.708329108-06:00",
  "statements": [
    {
      "vulnerability": {
        "@context": {
          "spdx": "https://www.spdx.org/ontology/spdx3.jsonld"
        },
        "@id": "https://spdx.org/spdxdocs/apko/da7945a1-f44d-4d73-afd5-02b183eb65c2#CVE-2014-123456",
        "@type": "spdx:Vulnerability",
      },
      "timestamp": "2022-10-11T20:29:19Z",
      "products": [
        "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99"
      ],
      "subcomponents": [
        "pkg:apk/wolfi/[email protected]",
        "pkg:apk/wolfi/[email protected]"
      ],
      "status": "fixed"
    }
  ]
}

Full Spec and New Fields

The new vulnerability object modifies the field from its original string format. The new object defines two fields beyond the JSON-ld implicit fields: name and aliases.

name

Required field that captures the main vulnerability label or identifier string as used in external tracking systems and databases. The value of the string is determined by the tracking system (eg CVE-2019-17571, GHSA-2qrg-x229-3v8q, SNYK-RHEL7-LOG4J-1472071, etc).

It supplements the optional @id field that takes an IRI to make the vulnerability struct referenceable in the same and external documents.

The name field captures the main identifier of the vulnerability, for better matching, more named can be added in the aliases field.

aliases

The aliases field is a list of labels that identify the vulnerability in databases and tracking systems. OpenVEX does not make any asumptions on the validity of the labels. While some of them may be well known (eg CVE, RHSA, GHSA, etc) the spec also allows for labels from unknown or private tracking systems.

Just as with products and subcomponents, a VEX statement should strive for as much descriptive breadth as possible when naming vulnerabilities. The easier to match the VEX document's data with a vulnerability's entry in a database the more useful the document becomes.

The alias list can duplicate the identifier enumerated in name for completeness without it constituting an error.