Skip to content

Latest commit

 

History

History
207 lines (180 loc) · 7.61 KB

opev-0014.md

File metadata and controls

207 lines (180 loc) · 7.61 KB
Raw

OPEV #0014: Expansion of the VEX Product Field

Six months after the introduction of OpenVEX, the initial integrations and community feedback of the initial spec has pointed out several areas where the product field can be improves to more accurately model the initial use cases of OpenVEX.

This OPEV proposes reworking the VEX product to become a full object with a new context called Componentthat lets us introduce new data fields needed today by the community while letting us more easily add other data in the future.

Issues Addressed by this OPEV:

This enhancement proposal addresses the following issues pointed out by the community:

Enhancement Proposal

The current lists of products and subcomponents are two lists of strings intended to hold the identifiers of those components. We recomend the use purl but any identifier can be used:

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
  "author": "mailto:john@doe.com",
  "role": "",
  "timestamp": "2023-01-16T20:41:55.708329108-06:00",
  "statements": [
    {
      "vulnerability": "CVE-2022-39046",
      "timestamp": "2022-10-11T20:29:19Z",
      "products": [
        "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux"
      ],
      "subcomponents": [
        "pkg:apk/wolfi/glibc@2.36-r4",
        "pkg:apk/wolfi/glibc-locale-posix@2.36-r4"
      ],
      "status": "fixed"
    }
  ]
}

The product field will now be typed to a Component context. In a minimal form, an OpenVEX document could simply capture data defined external by identifying the components to external IRIs, such as package URLs (purls):

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
  "author": "mailto:john@doe.com",
  "timestamp": "2023-01-16T20:41:55.708329108-06:00",
  "statements": [
    {
      "@id": "https://openvex.dev/docs/public/statements/st-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
      "vulnerability": "CVE-2022-39046",
      "timestamp": "2022-10-11T20:29:19Z",
      "status": "fixed",
      "products": [
        {
          "@id": "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux",
          "subcomponents": [
            { "@id": "pkg:apk/wolfi/glibc@2.36-r4" }, 
            { "@id": "pkg:apk/wolfi/glibc-locale-posix@2.36-r4" }
          ]
        }
      ]
    }
  ]
}

As seen here, the main change when using the minimal form is that instead of a string, the ID previously used as the product has now been moved to the @id field of the new product struct. This allows the spec to still use the ID to point to external contexts such as an SBOM or use a purl while, at the same time, the expanded struct lets us add more data that the community has deemed important to have.

Full Spec and New Fields

When fully expanded, the new product object has three data fields: subcomponents, hashes and identifiers. We'll go into each but here is an expanded example:

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271",
  "author": "",
  "role": "",
  "timestamp": "2023-01-16T20:41:55.708329108-06:00",
  "statements": [
    {
      "@id": "https://openvex.dev/docs/public/vex-6e8cc8c4d0c38e9e9a60949e5dc0279684d8ad5f6711d9a12bb52247b6cc7271#statement1",
      "vulnerability": "CVE-2022-39046",
      "timestamp": "2022-10-11T20:29:19Z",
      "status": "fixed",
      "products": [
        {
          "@id:": "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux",
          "subcomponents": [
            { "@id": "pkg:apk/wolfi/glibc@2.36-r4" }, 
            { "@id": "https://spdx.org/spdxdocs/apko/4fa164f9-90ca-42a8-bafe-5ab9d3cc4af9#packageref" },
            { "@id": "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#componentA" }
            {
              "identifiers": {
                "cpe23": "cpe:2.3:a:gnu:glibc:2.36.2:*:*:*:*:*:*:*"
              }
            },
            {
              "hashes": [ "sha-256": "329c82bb9157b5fa51d67dddd91df0c6881f76dcad7cbe19e683800d371bb142" ]
            },
            {
              "identifiers": {
                "containerFile": "/path/to/file.txt"
              }
            },
          ],
          "hashes": [
            {
              "algorithm": "sha-256",
              "value": "329c82bb9157b5fa51d67dddd91df0c6881f76dcad7cbe19e683800d371bb142"
            }
          ],
          "identifiers": [
            {
              "type": "purl",
              "locator": "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux"
            },
            {
              "type": "cpe23",
              "locator": "cpe:2.3:a:*:*:*:*:*:*:*...."
            }
          ]
        }
      ]
    }
  ]
}

With the new product object, this proposal adds the following fields to the OpenVEX context. Note that all of these would be optional.

subcomponents

The subcomponents field is a list of the subcomponents. These have been moved from a string list at the statement level to be a list of Components. In its minimal form, the component is still compact enough to just use the identifiers:

"subcomponents": [
  { "@id": "pkg:apk/wolfi/glibc@2.36-r4" }
]

Expanded, it can specify the full elements of the Component context.

Hashes

Feedback from the community has indicated that components should be able to have hashes associated with them. There are several reasons why we want that, but integrity, identification and disambiguation are reasons that come to mind. The new hashes field adds hash data to the component context (product and subcomponents):

"hashes": [
  {
    "algorithm": "sha-256",
    "value": "329c82bb9157b5fa51d67dddd91df0c6881f76dcad7cbe19e683800d371bb142"
  }
]

The values in the algorithm field must follow the list and pattern in the Hash Function Textual Names list from IANA. The OpenVEX tooling will provide constant values adhering to the naming pattern in the document.

Software Identifiers

The new Component context expands the product to allow for more software identifiers. It is a list of fields indicating the type and the value:

"identifiers": [
  {
    "type": "purl",
    "identifier": "pkg:oci/miniprow@sha256:74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux"
  },
  {
    "type": "cpe23",
    "identifier": "cpe:2.3:a:*:*:*:*:*:*:*...."
  }
]