From e116cf8ff5caa56492510efa0982d5fdc1f43aae Mon Sep 17 00:00:00 2001 From: knqyf263 Date: Tue, 28 May 2024 12:48:16 +0400 Subject: [PATCH] docs: add CSAF relationships Signed-off-by: knqyf263 --- docs/docs/supply-chain/vex.md | 40 ++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/docs/supply-chain/vex.md b/docs/docs/supply-chain/vex.md index 8b4359118c59..6dc02b6d088b 100644 --- a/docs/docs/supply-chain/vex.md +++ b/docs/docs/supply-chain/vex.md @@ -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 < debian11.openvex.json @@ -167,15 +167,17 @@ $ cat < 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:
-OpenVEX +OpenVEX products only ```json "statements": [ @@ -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:
-OpenVEX subcomponent +OpenVEX subcomponents ```json "statements": [ @@ -218,9 +220,9 @@ If the intention is to declare that the `git` package distributed by Alpine Linu
-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. @@ -251,7 +253,7 @@ In the following example, the VEX statement declares that the `github.com/docker
-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 @@ -299,7 +301,10 @@ The following steps are required: ### Create the CSAF document Create a CSAF document in JSON format as follows: -``` +
+CSAF VEX + +```bash $ cat < debian11.vex.csaf { "document": { @@ -397,10 +402,20 @@ $ cat < debian11.vex.csaf EOF ``` +
+ +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"} @@ -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 \ No newline at end of file +[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 \ No newline at end of file