Skip to content

Commit a447f6b

Browse files
knqyf263knqyf263
authored
feat(vex): improve relationship support in CSAF VEX (#6735)
Signed-off-by: knqyf263 <[email protected]>
1 parent e66dbb9 commit a447f6b

File tree

7 files changed

+318
-272
lines changed

7 files changed

+318
-272
lines changed

‎docs/docs/supply-chain/vex.md

+120-18
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,6 @@ Currently, Trivy supports the following three formats:
1111
- [OpenVEX](https://github.com/openvex/spec)
1212
- [CSAF](https://oasis-open.github.io/csaf-documentation/specification.html)
1313

14-
This is still an experimental implementation, with only minimal functionality added.
15-
1614
## CycloneDX
1715
| Target | Supported |
1816
|:---------------:|:---------:|
@@ -40,7 +38,7 @@ The following steps are required:
4038
### Generate the SBOM
4139
You can generate a CycloneDX SBOM with Trivy as follows:
4240

43-
```shell
41+
```bash
4442
$ trivy image --format cyclonedx --output debian11.sbom.cdx debian:11
4543
```
4644

@@ -49,7 +47,7 @@ Next, create a VEX based on the generated SBOM.
4947
Multiple vulnerability statuses can be defined under `vulnerabilities`.
5048
Take a look at the example below.
5149

52-
```
50+
```bash
5351
$ cat <<EOF > trivy.vex.cdx
5452
{
5553
"bomFormat": "CycloneDX",
@@ -105,7 +103,7 @@ For more details on CycloneDX VEX and BOM-Link, please refer to the following li
105103
### Scan SBOM with VEX
106104
Provide the VEX when scanning the CycloneDX SBOM.
107105

108-
```
106+
```bash
109107
$ trivy sbom trivy.sbom.cdx --vex trivy.vex.cdx
110108
...
111109
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"}
@@ -145,10 +143,10 @@ The following steps are required:
145143

146144
### Create the VEX document
147145
Please see also [the example](https://github.com/openvex/examples).
148-
In Trivy, [the Package URL (PURL)][purl] is used as the product identifier.
146+
Trivy requires [the Package URL (PURL)][purl] as the product identifier.
149147

150-
```
151-
$ cat <<EOF > debian11.openvex
148+
```bash
149+
$ cat <<EOF > debian11.openvex.json
152150
{
153151
"@context": "https://openvex.dev/ns/v0.2.0",
154152
"@id": "https://openvex.dev/docs/public/vex-2e67563e128250cbcb3e98930df948dd053e43271d70dc50cfa22d57e03fe96f",
@@ -169,19 +167,107 @@ $ cat <<EOF > debian11.openvex
169167
EOF
170168
```
171169

172-
In the above example, PURLs, located in `packages.externalRefs.referenceLocator` in SPDX are used for the product identifier.
170+
In the above example, PURLs, `pkg:deb/debian/[email protected]+dfsg1-0.8` are used for the product identifier.
171+
You can find PURLs in the JSON report generated by Trivy.
172+
This VEX statement is applied if the PURL specified in the VEX matches the PURL found during the scan.
173+
See [here](#purl-matching) for more details of PURL matching.
173174

174-
!!! note
175-
If a qualifier is specified in the PURL used as the product id in the VEX, the qualifier is compared.
176-
Other qualifiers are ignored in the comparison.
177-
`pkg:deb/debian/[email protected]` in OpenVEX matches `pkg:deb/debian/[email protected]?arch=i386`,
178-
while `pkg:deb/debian/[email protected]?arch=amd64` does not match `pkg:deb/debian/[email protected]?arch=i386`.
175+
Trivy also supports [OpenVEX subcomponents][openvex-subcomponent], which allow for more precise specification of the scope of a VEX statement, reducing the risk of incorrect filtering.
176+
Let's say you want to suppress vulnerabilities within a container image.
177+
If you only specify the PURL of the container image as the product, the resulting VEX would look like this:
178+
179+
<details>
180+
<summary>OpenVEX products only</summary>
181+
182+
```json
183+
"statements": [
184+
{
185+
"vulnerability": {"name": "CVE-2024-32002"},
186+
"products": [
187+
{"@id": "pkg:oci/trivy?repository_url=ghcr.io%2Faquasecurity%2Ftrivy"}
188+
],
189+
"status": "not_affected",
190+
"justification": "vulnerable_code_not_in_execute_path"
191+
}
192+
]
193+
```
194+
195+
</details>
196+
197+
However, this approach would suppress all instances of CVE-2024-32002 within the container image.
198+
If the intention is to declare that the `git` package distributed by Alpine Linux within this image is not affected, subcomponents can be utilized as follows:
199+
200+
<details>
201+
<summary>OpenVEX subcomponents</summary>
202+
203+
```json
204+
"statements": [
205+
{
206+
"vulnerability": {"name": "CVE-2024-32002"},
207+
"products": [
208+
{
209+
"@id": "pkg:oci/trivy?repository_url=ghcr.io%2Faquasecurity%2Ftrivy",
210+
"subcomponents": [
211+
{"@id": "pkg:apk/alpine/git"}
212+
]
213+
}
214+
],
215+
"status": "not_affected",
216+
"justification": "vulnerable_code_not_in_execute_path"
217+
}
218+
]
219+
```
220+
221+
</details>
222+
223+
By declaring the subcomponent in this manner, Trivy will filter the results, considering only the `git` package within the `ghcr.io/aquasecurity/trivy` container image as not affected.
224+
Omitting the version in the PURL applies the statement to all versions of the package.
225+
More details about PURL matching can be found [here](#purl-matching).
226+
227+
Furthermore, the product specified in a VEX statement does not necessarily need to be the target of the scan.
228+
It is possible to specify a component that is included in the scan target as the product.
229+
For example, you can designate a specific Go project as the product and its dependent modules as subcomponents.
230+
231+
In the following example, the VEX statement declares that the `github.com/docker/docker` module, which is a dependency of the `github.com/aquasecurity/trivy` Go project, is not affected by CVE-2024-29018.
232+
233+
<details>
234+
<summary>OpenVEX intermediate components</summary>
235+
236+
```json
237+
"statements": [
238+
{
239+
"vulnerability": {"name": "CVE-2024-29018"},
240+
"products": [
241+
{
242+
"@id": "pkg:golang/github.com/aquasecurity/trivy",
243+
"subcomponents": [
244+
{ "@id": "pkg:golang/github.com/docker/docker" }
245+
]
246+
}
247+
],
248+
"status": "not_affected",
249+
"justification": "vulnerable_code_not_in_execute_path"
250+
}
251+
]
252+
```
253+
254+
</details>
255+
256+
This VEX document can be used when scanning a container image as well as other targets.
257+
The VEX statement will be applied when Trivy finds the Go binary within the container image.
258+
259+
```bash
260+
$ trivy image ghcr.io/aquasecurity/trivy:0.50.0 --vex trivy.openvex.json
261+
```
262+
263+
VEX documents can indeed be reused across different container images, eliminating the need to issue separate VEX documents for each image.
264+
This is particularly useful when there is a common component or library that is used across multiple projects or container images.
179265

180266
### Scan with VEX
181267
Provide the VEX when scanning your target.
182268

183-
```
184-
$ trivy image debian:11 --vex debian11.openvex
269+
```bash
270+
$ trivy image debian:11 --vex debian11.openvex.json
185271
...
186272
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"}
187273

@@ -215,7 +301,10 @@ The following steps are required:
215301
### Create the CSAF document
216302
Create a CSAF document in JSON format as follows:
217303

218-
```
304+
<details>
305+
<summary>CSAF VEX</summary>
306+
307+
```bash
219308
$ cat <<EOF > debian11.vex.csaf
220309
{
221310
"document": {
@@ -313,10 +402,20 @@ $ cat <<EOF > debian11.vex.csaf
313402
EOF
314403
```
315404

405+
</details>
406+
407+
Trivy also supports [CSAF relationships][csaf-relationship], reducing the risk of incorrect filtering.
408+
It works in the same way as OpenVEX subcomponents.
409+
At present, the specified relationship category is not taken into account and all the following categories are treated internally as "depends_on".
410+
411+
- default_component_of
412+
- installed_on
413+
- installed_with
414+
316415
### Scan with CSAF VEX
317416
Provide the CSAF document when scanning your target.
318417

319-
```console
418+
```bash
320419
$ trivy image debian:11 --vex debian11.vex.csaf
321420
...
322421
2024-01-02T10:28:26.704+0100 INFO Filtered out the detected vulnerability {"VEX format": "CSAF", "vulnerability-id": "CVE-2019-8457", "status": "not_affected"}
@@ -376,3 +475,6 @@ does not match:
376475
[openvex]: https://github.com/openvex/spec
377476
[purl]: https://github.com/package-url/purl-spec
378477
[purl-matching]: https://github.com/openvex/spec/issues/27
478+
479+
[openvex-subcomponent]: https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#subcomponent
480+
[csaf-relationship]: https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#3224-product-tree-property---relationships

0 commit comments

Comments
 (0)