Skip to content

Commit

Permalink
docs: add CSAF relationships
Browse files Browse the repository at this point in the history
Signed-off-by: knqyf263 <knqyf263@gmail.com>
  • Loading branch information
knqyf263 committed May 28, 2024
1 parent 9bedb7c commit e116cf8
Showing 1 changed file with 28 additions and 12 deletions.
40 changes: 28 additions & 12 deletions docs/docs/supply-chain/vex.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ The following steps are required:

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

```bash
$ cat <<EOF > debian11.openvex.json
Expand All @@ -167,15 +167,17 @@ $ cat <<EOF > debian11.openvex.json
EOF
```

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

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.
Let's say you want to suppress vulnerabilities within a container image.
If you specify the PURL of the container image as the product, the resulting VEX would look like this:
If you only specify the PURL of the container image as the product, the resulting VEX would look like this:

<details>
<summary>OpenVEX</summary>
<summary>OpenVEX products only</summary>

```json
"statements": [
Expand All @@ -196,7 +198,7 @@ However, this approach would suppress all instances of CVE-2024-32002 within the
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:

<details>
<summary>OpenVEX subcomponent</summary>
<summary>OpenVEX subcomponents</summary>

```json
"statements": [
Expand All @@ -218,9 +220,9 @@ If the intention is to declare that the `git` package distributed by Alpine Linu

</details>

By declaring the statement in this manner, Trivy will filter the results, considering only the `git` package within the `ghcr.io/aquasecurity/trivy` container image as not affected.
It's worth noting that omitting the version in the PURL applies the statement to all versions of the package.
More details can be found [here](#purl-matching).
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.
Omitting the version in the PURL applies the statement to all versions of the package.
More details about PURL matching can be found [here](#purl-matching).

Furthermore, the product specified in a VEX statement does not necessarily need to be the target of the scan.
It is possible to specify a component that is included in the scan target as the product.
Expand Down Expand Up @@ -251,7 +253,7 @@ In the following example, the VEX statement declares that the `github.com/docker

</details>

This VEX document can be used when scanning a container image.
This VEX document can be used when scanning a container image as well as other targets.
The VEX statement will be applied when Trivy finds the Go binary within the container image.

```bash
Expand Down Expand Up @@ -299,7 +301,10 @@ The following steps are required:
### Create the CSAF document
Create a CSAF document in JSON format as follows:

```
<details>
<summary>CSAF VEX</summary>

```bash
$ cat <<EOF > debian11.vex.csaf
{
"document": {
Expand Down Expand Up @@ -397,10 +402,20 @@ $ cat <<EOF > debian11.vex.csaf
EOF
```

</details>

Trivy also supports [CSAF relationships][csaf-relationship], reducing the risk of incorrect filtering.
It works in the same way as OpenVEX subcomponents.
At present, the specified relationship category is not taken into account and all the following categories are treated internally as "depends_on".

- default_component_of
- installed_on
- installed_with

### Scan with CSAF VEX
Provide the CSAF document when scanning your target.

```console
```bash
$ trivy image debian:11 --vex debian11.vex.csaf
...
2024-01-02T10:28:26.704+0100 INFO Filtered out the detected vulnerability {"VEX format": "CSAF", "vulnerability-id": "CVE-2019-8457", "status": "not_affected"}
Expand Down Expand Up @@ -461,4 +476,5 @@ does not match:
[purl]: https://github.com/package-url/purl-spec
[purl-matching]: https://github.com/openvex/spec/issues/27

[openvex-subcomponent]: https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#subcomponent
[openvex-subcomponent]: https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#subcomponent
[csaf-relationship]: https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#3224-product-tree-property---relationships

0 comments on commit e116cf8

Please sign in to comment.