Vulnerability Exploitability Exchange (VEX)
EXPERIMENTAL
This feature might change without preserving backwards compatibility.
Trivy supports filtering detected vulnerabilities using the Vulnerability Exploitability Exchange (VEX), a standardized format for sharing and exchanging information about vulnerabilities. By providing VEX alongside the Software Bill of Materials (SBOM) during scanning, it is possible to filter vulnerabilities based on their status. Currently, Trivy supports the following two formats:
This is still an experimental implementation, with only minimal functionality added.
CycloneDX
There are two VEX formats for CycloneDX:
- Independent BOM and VEX BOM
- BOM With Embedded VEX
Trivy only supports the Independent BOM and VEX BOM format, so you need to provide a separate VEX file alongside the SBOM. The input SBOM format must be in CycloneDX format.
The following steps are required:
- Generate a CycloneDX SBOM
- Create a VEX based on the SBOM generated in step 1
- Provide the VEX when scanning the CycloneDX SBOM
Generating the SBOM
You can generate a CycloneDX SBOM with Trivy as follows:
$ trivy image --format cyclonedx --output debian11.sbom.cdx debian:11
Create the VEX
Next, create a VEX based on the generated SBOM.
Multiple vulnerability statuses can be defined under vulnerabilities
.
Take a look at the example below.
$ cat <<EOF > trivy.vex.cdx
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"vulnerabilities": [
{
"id": "CVE-2020-8911",
"analysis": {
"state": "not_affected",
"justification": "code_not_reachable",
"response": ["will_not_fix", "update"],
"detail": "The vulnerable function is not called"
},
"affects": [
{
"ref": "urn:cdx:3e671687-395b-41f5-a30f-a58921a69b79/1#pkg:golang/github.com/aws/aws-sdk-go@1.44.234"
}
]
}
]
}
EOF
This is a VEX document in the CycloneDX format.
The vulnerability ID, such as a CVE-ID or GHSA-ID, should be placed in vulnerabilities.id
.
When the analysis.state
is set to not_affected
, Trivy will not detect the vulnerability.
BOM-Links must be placed in affects.ref
.
The BOM-Link has the following syntax and consists of three elements:
urn:cdx:serialNumber/version#bom-ref
- serialNumber
- version
- bom-ref
These values must be obtained from the CycloneDX SBOM.
Please note that while the serialNumber starts with urn:uuid:
, the BOM-Link starts with urn:cdx:
.
The bom-ref
must contain the BOM-Ref of the package affected by the vulnerability.
In the example above, since the Go package github.com/aws/aws-sdk-go
is affected by CVE-2020-8911, it was necessary to specify the SBOM's BOM-Ref, pkg:golang/github.com/aws/aws-sdk-go@1.44.234
.
For more details on CycloneDX VEX and BOM-Link, please refer to the following links:
Scan SBOM with VEX
Provide the VEX when scanning the CycloneDX SBOM.
$ trivy sbom trivy.sbom.cdx --vex trivy.vex.cdx
...
2023-04-13T12:55:44.838+0300 INFO Filtered out the detected vulnerability {"VEX format": "CycloneDX", "vulnerability-id": "CVE-2020-8911", "status": "not_affected", "justification": "code_not_reachable"}
go.mod (gomod)
==============
Total: 1 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 0, CRITICAL: 0)
┌───────────────────────────┬───────────────┬──────────┬───────────────────┬───────────────┬────────────────────────────────────────────────────────────┐
│ Library │ Vulnerability │ Severity │ Installed Version │ Fixed Version │ Title │
├───────────────────────────┼───────────────┼──────────┼───────────────────┼───────────────┼────────────────────────────────────────────────────────────┤
│ github.com/aws/aws-sdk-go │ CVE-2020-8912 │ LOW │ 1.44.234 │ │ aws-sdk-go: In-band key negotiation issue in AWS S3 Crypto │
│ │ │ │ │ │ SDK for golang... │
│ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2020-8912 │
└───────────────────────────┴───────────────┴──────────┴───────────────────┴───────────────┴────────────────────────────────────────────────────────────┘
CVE-2020-8911 is no longer shown as it is filtered out according to the given CycloneDX VEX document.
OpenVEX
Trivy also supports OpenVEX that is designed to be minimal, compliant, interoperable, and embeddable. Since OpenVEX aims to be SBOM format agnostic, both CycloneDX and SPDX formats are available for use as input SBOMs in Trivy.
The following steps are required:
- Generate a SBOM (CycloneDX or SPDX)
- Create a VEX based on the SBOM generated in step 1
- Provide the VEX when scanning the SBOM
Generating the SBOM
You can generate a CycloneDX or SPDX SBOM with Trivy as follows:
$ trivy image --format spdx-json --output debian11.spdx.json debian:11
Create the VEX
Please see also the example. The product identifiers differ depending on the SBOM format the VEX references.
- SPDX: Package URL (PURL)
- CycloneDX: BOM-Link
$ cat <<EOF > trivy.openvex
{
"@context": "https://openvex.dev/ns",
"@id": "https://openvex.dev/docs/public/vex-2e67563e128250cbcb3e98930df948dd053e43271d70dc50cfa22d57e03fe96f",
"author": "Aqua Security",
"timestamp": "2023-01-16T19:07:16.853479631-06:00",
"version": "1",
"statements": [
{
"vulnerability": "CVE-2019-8457",
"products": [
"pkg:deb/debian/libdb5.3@5.3.28+dfsg1-0.8?arch=arm64\u0026distro=debian-11.6"
],
"status": "not_affected",
"justification": "vulnerable_code_not_in_execute_path"
}
]
}
EOF
In the above example, PURLs, located in packages.externalRefs.referenceLocator
are used since the input SBOM format is SPDX.
As for CycloneDX BOM-Link, please reference the CycloneDX section.
Scan SBOM with VEX
Provide the VEX when scanning the SBOM.
$ trivy sbom debian11.spdx.json --vex trivy.openvex
...
2023-04-26T17:56:05.358+0300 INFO Filtered out the detected vulnerability {"VEX format": "OpenVEX", "vulnerability-id": "CVE-2019-8457", "status": "not_affected", "justification": "vulnerable_code_not_in_execute_path"}
debian11.spdx.json (debian 11.6)
================================
Total: 80 (UNKNOWN: 0, LOW: 58, MEDIUM: 6, HIGH: 16, CRITICAL: 0)
CVE-2019-8457 is no longer shown as it is filtered out according to the given OpenVEX document.