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 Component
that lets us introduce new data fields needed today by
the community while letting us more easily add other data in the future.
This enhancement proposal addresses the following issues pointed out by the community:
- Adding the capability to add hashes to the product
- Supporting other software identifiers and and making their type more explicit
- Better tying the subcomponent and product together
- Better ability to refer back to SBOMs describing the product
- Subcomponents cannot be tied back to products (and to suppliers)
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:[email protected]",
"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/[email protected]",
"pkg:apk/wolfi/[email protected]"
],
"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:[email protected]",
"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/[email protected]" },
{ "@id": "pkg:apk/wolfi/[email protected]" }
]
}
]
}
]
}
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.
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/[email protected]" },
{ "@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.
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 Component
s. In its
minimal form, the component is still compact enough to just use the identifiers:
"subcomponents": [
{ "@id": "pkg:apk/wolfi/[email protected]" }
]
Expanded, it can specify the full elements of the Component context.
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.
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:*:*:*:*:*:*:*...."
}
]