diff --git a/content/scout/explore/exceptions.md b/content/scout/explore/exceptions.md new file mode 100644 index 0000000000..8eada1fd0c --- /dev/null +++ b/content/scout/explore/exceptions.md @@ -0,0 +1,299 @@ +--- +title: Manage vulnerability exceptions +description: | + Exceptions let you provide additional context and documentation for how + vulnerabilities affect your artifacts, and provides the ability to + suppress non-applicable vulnerabilities +keywords: scout, cves, suppress, vex, exceptions +--- + +Vulnerabilities found in container images sometimes need additional context. +Just because an image contains a vulnerable package, it doesn't mean that the +vulnerability is exploitable. **Exceptions** in Docker Scout lets you address +false positives in image analysis using Vulnerability Exploitability +eXchange (VEX) documents. + +By negating non-applicable vulnerabilities, you can make it easier for yourself +and downstream consumers of your images to understand the security implications +of a vulnerability in the context of an image. + +In Docker Scout, exceptions are automatically factored into the results. +If an image contains an exception that flags a CVE as non-applicable, +then that CVE is excluded from analysis results. + +## Create an exception + +To add an exception to an image, you need a VEX document. VEX is a standard +format for documenting vulnerabilities in the context of a software package or +product. + +There are multiple implementations and formats of VEX. Docker Scout supports +the [OpenVex](https://github.com/openvex/spec) implementation. To create an +OpenVEX document, use the [`vexctl`](https://github.com/openvex/vexctl) command +line tool. + +The following example command creates a VEX document stating that: + +- The software product described by this VEX document is the Docker image + `example/app:v1` +- The image contains the npm package `express@4.17.1` +- The npm package is affected by a known vulnerability: `CVE-2022-24999` +- The image is unaffected by the CVE, because the vulnerable code is never + executed in containers that run this image + +```console +$ vexctl create \ + --author="author@example.com" \ + --product="pkg:docker/example/app@v1" \ + --subcomponents="pkg:npm/express@4.17.1" \ + --vuln="CVE-2022-24999" \ + --status="not_affected" \ + --justification="vulnerable_code_not_in_execute_path" \ + --file="CVE-2022-24999.vex.json" +``` + +Here's a description of the options in this example: + +`--author` +: The email of the author of the VEX document. + +`--product` +: Package URL (PURL) of the Docker image. A PURL is an identifier + for the image in a standardized format, defined in the PURL + [specification](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#docker). + + Docker image PURL strings begin with a `pkg:docker` type prefix, followed by + the image repository and version (the image tag or SHA256 digest). Unlike + image tags, where the version is specified like `example/app:v1`, in PURL the + image repository and version are separated by an `@`. + +`--subcomponents` +: PURL of the vulnerable package in the image. In this example, the + vulnerability exists in an npm package, so the `--subcomponents` PURL is the + identifier for the npm package name and version (`pkg:npm/express@4.17.1`). + + If the same vulnerability exists in multiple packages, `vexctl` lets you + specify the `--subcomponents` flag multiple times for a single `create` + command. + +`--vuln` +: ID of the CVE that the VEX statement addresses. + +`--status` +: This is the status label of the vulnerability. This describes the + relationship between the software (`--product`) and the CVE (`--vuln`). + The possible values for the status label in OpenVEX are: + + - `not_affected` + - `affected` + - `fixed` + - `under_investigation` + + In this example, the VEX statement asserts that the Docker image is + `not_affected` by the vulnerability. The `not_affected` status is the only + status that results in CVE suppression, where the CVE is filtered out of the + analysis results. The other statuses are useful for documentation purposes, + but they do not work for creating exceptions. For more information about all + the possible status labels, see [Status Labels](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-labels) + in the OpenVEX specification. + +`--justification` +: Justifies the `not_affected` status label, informing why the product is not + affected by the vulnerability. In this case, the justification given is + `vulnerable_code_not_in_execute_path`, signalling that the vulnerability + can't be executed as used by the product. + + In OpenVEX, status justifications can have one of the five possible values: + + - `component_not_present` + - `vulnerable_code_not_present` + - `vulnerable_code_not_in_execute_path` + - `vulnerable_code_cannot_be_controlled_by_adversary` + - `inline_mitigations_already_exist` + + For more information about these values and their definitions, see + [Status Justifications](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-justifications) + in the OpenVEX specification. + +`--file` +: Filename of the VEX document output + +Here's the OpenVEX JSON generated by this command: + +```json +{ + "@context": "https://openvex.dev/ns/v0.2.0", + "@id": "https://openvex.dev/docs/public/vex-749f79b50f5f2f0f07747c2de9f1239b37c2bda663579f87a35e5f0fdfc13de5", + "author": "author@example.com", + "timestamp": "2024-05-27T13:20:22.395824+02:00", + "version": 1, + "statements": [ + { + "vulnerability": { + "name": "CVE-2022-24999" + }, + "timestamp": "2024-05-27T13:20:22.395829+02:00", + "products": [ + { + "@id": "pkg:docker/example/app@v1", + "subcomponents": [ + { + "@id": "pkg:npm/express@4.17.1" + } + ] + } + ], + "status": "not_affected", + "justification": "vulnerable_code_not_in_execute_path" + } + ] +} +``` + +Understanding how VEX documents are supposed to be structured can be a bit of a +mouthful. The [OpenVEX specification](https://github.com/openvex/spec) +describes the format and all the possible properties of documents and +statements. For the full details, refer to the specification to learn more +about the available fields and how to create a well-formed OpenVEX document. + +To learn more about the available flags and syntax of the `vexctl` CLI tool and +how to install it, refer to the [`vexctl` GitHub repository](https://github.com/openvex/vexctl). + +For an introduction to VEX, you may also want to check out this use-case guide: +[Suppress image vulnerabilities with VEX](/scout/guides/vex.md). + +## Verifying VEX documents + +To test whether the VEX documents you create are well-formed and produce the +expected results, use the `docker scout cves` command with the `--vex-location` +flag to apply a VEX document to a local image analysis using the CLI. + +The following command invokes a local image analysis that incorporates all VEX +documents in the specified location, using the `--vex-location` flag. In this +example, the CLI is instructed to look for VEX documents in the current working +directory. + +```console +$ docker scout cves --vex-location . +``` + +The output of the `docker scout cves` command displays the results with any VEX +statements found in under the `--vex-location` location factored into the +results. For example, CVEs assigned a status of `not_affected` are filtered out +from the results. If the output doesn't seem to take the VEX statements into +account, that's an indication that the VEX documents might be invalid in some +way. + +Things to look out for include: + +- The PURL of a Docker image must begin with `pkg:docker/` followed by the image name. +- In a Docker image PURL, the image name and version is separated by `@`. + An image named `example/myapp:1.0` has the following PURL: `pkg:docker/example/myapp@1.0`. +- Remember to specify an `author` (it's a mandatory field in OpenVEX) +- The [OpenVEX specification](https://github.com/openvex/spec) describes how + and when to use `justification`, `impact_statement`, and other fields in the + VEX documents. Specifying these in an incorrect way results in an invalid + document. Make sure your VEX documents comply with the OpenVEX specification. + +## Attach exceptions to images + +When you've created an exception, +you can attach it to your image in the following ways: + +- Attach the document as an [attestation](#attestation) +- Embed the document in the [image filesystem](#image-filesystem) + +You can't remove a VEX document from an image once it's been added. For +documents attached as attestations, you can create a new VEX document and +attach it to the image again. Doing so will overwrite the previous VEX document +(but it won't remove the attestation). For images where the VEX document has +been embedded in the image's filesystem, you need to rebuild the image to +change the VEX document. + +### Attestation + +To attach exceptions as an attestation, you can use the `docker scout +attestation add` CLI command. Using attestations is the recommended option for attaching exceptions to +images. + +You can attach attestations to images that have already been pushed to a +registry. You don't need to build or push the image again. Additionally, having +the exceptions attached to the image as attestations means consumers can +inspect the exceptions for an image, directly from the registry. + +To attach an attestation to an image: + +1. Build the image and push it to a registry. + + ```console + $ docker build --provenance=true --sbom=true --tag --push . + ``` + +2. Attach the exception to the image as an attestation. + + ```console + $ docker scout attestation add \ + --file .vex.json \ + --predicate-type https://openvex.dev/ns/v0.2.0 \ + + ``` + + The options for this command are: + + - `--file`: the location and filename of the VEX document + - `--predicate-type`: the in-toto `predicateType` for OpenVEX + +### Image filesystem + +Embedding exceptions directly on the image filesystem is a good option if you +know the exceptions ahead of time, before you build the image. And it's easy; +just `COPY` the VEX document to the image in your Dockerfile. + +The downside with this approach is that you can't change or update the +exception later. Image layers are immutable, so anything you put in the image's +filesystem is there forever. Attaching the document as an +[attestation](#attestation) provides better flexibility. + +To embed a VEX document on the image filesystem, `COPY` the file into the image +as part of the image build. The following example shows how to copy all VEX +documents under `.vex/` in the build context, to `/var/lib/db` in the image. + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM alpine +COPY .vex/* /var/lib/db/ +``` + +The filename of the VEX document must match the `*.vex.json` glob pattern. +It doesn't matter where on the image's filesystem you store the file. + +Note that the copied files must be part of the filesystem of the final image, +For multi-stage builds, the documents must persist in the final stage. + +## View exceptions + +The **Exceptions** page on the [Docker Scout Dashboard](https://scout.docker.com/) +lists the exceptions for all images in your organization. Selecting a row in +the list opens the exception side panel, which displays more information about +the exception and where it comes from. + +To view all exceptions for a specific image tag: + +{{< tabs >}} +{{< tab name="Docker Scout Dashboard" >}} + +1. Go to the [Images page](https://scout.docker.com/reports/images). +2. Select the tag that you want to inspect. +3. Open the **Image attestations** tab. + +{{< /tab >}} +{{< tab name="Docker Desktop" >}} + +1. Open the **Images** view in Docker Desktop. +2. Open the **Hub** tab. +3. Select the tag you want to inspect. +4. Open the **Image attestations** tab. + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/scout/guides/vex.md b/content/scout/guides/vex.md index 703837583e..4cdb8fdde8 100644 --- a/content/scout/guides/vex.md +++ b/content/scout/guides/vex.md @@ -297,3 +297,4 @@ For more information about VEX: - [VEX Status Justifications (CISA)](https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf) - [VEX Use Cases (CISA)](https://www.cisa.gov/sites/default/files/publications/VEX_Use_Cases_Document_508c.pdf) - [OpenVEX specification](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md) +- [Manage vulnerability exceptions](/scout/explore/exceptions.md) diff --git a/content/scout/release-notes/platform.md b/content/scout/release-notes/platform.md index 9bb2825af0..2447316f9d 100644 --- a/content/scout/release-notes/platform.md +++ b/content/scout/release-notes/platform.md @@ -19,6 +19,24 @@ for what's coming next. New features and enhancements released in the second quarter of 2024. +### 2024-05-0x + +This release introduces initial support for **Exceptions** in the Docker Scout +Dashboard. Exceptions let you suppress vulnerabilities found in your images +(false positives), using VEX documents. Attach VEX documents to images as +attestations, or embed them on image filesystems, and Docker Scout will +automatically detect and incorporate the VEX statements into the image analysis +results. + +The new [Exceptions page](https://scout.docker.com/reports/vex/) lists all +exceptions affecting images in your organization. You can also go to the image +view in the Docker Scout Dashboard to see all exceptions that apply to a given +image. + +For more information, see [Manage vulnerability exceptions](/scout/explore/exceptions.md). +If you're new to VEX, check out this use-case guide: +[Suppress image vulnerabilities with VEX](/scout/guides/vex.md). + ### 2024-05-06 New HTTP endpoint that lets you scrape data from Docker Scout with Prometheus, diff --git a/data/redirects.yml b/data/redirects.yml index cfaa61ccc0..b1d21112f8 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -654,6 +654,8 @@ - "/go/scout-slack/" "/scout/policy/scores/": - /go/scout-scores/ +"/scout/exceptions/": + - "/go/scout-exceptions/" # Build links (internal) "/build/bake/reference/": diff --git a/data/toc.yaml b/data/toc.yaml index 6b6c515f2a..6455a90ed0 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1432,6 +1432,8 @@ Manuals: title: Dashboard - path: /scout/explore/image-details-view/ title: Image details view + - path: /scout/explore/exceptions/ + title: Exceptions {{< badge color=violet text=New >}} - path: /scout/explore/metrics-exporter/ title: Metrics exporter - sectiontitle: How-tos