Attaching VEX Documents to Images: Attestation and Image Filesystem

- 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 VEX documents as an attestation, you can use the `docker scout attestation add` CLI command. Using attestations is the recommended option for attaching exceptions to images when using VEX. 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 <IMAGE> --push . ``` 2. Attach the exception to the image as an attestation. ```console $ docker scout attestation add \ --file <cve-id>.vex.json \ --predicate-type https://openvex.dev/ns/v0.2.0 \ <IMAGE> ``` 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 VEX documents 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 relatively 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. > [!NOTE] > VEX documents embedded in the image filesystem are not considered for images > that have attestations. If your image has **any** attestations, Docker Scout > will only look for exceptions in the attestations, and not in the image > filesystem. > > If you want to use the VEX document embedded in the image filesystem, you > must remove the attestation from the image. Note that provenance attestations > may be added automatically for images. To ensure that no attestations are > added to the image, you can explicitly disable both SBOM and provenance > attestations using the `--provenance=false` and `--sbom=false` flags when > building the image. 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.

This section details two methods for attaching VEX documents to images: using `docker scout attestation add` to add them as attestations, and embedding them directly in the image's filesystem. It provides instructions for both methods, highlighting the flexibility of attestations for updating exceptions and the immutability of embedded documents. It also notes that VEX documents embedded in the image filesystem are ignored if the image has attestations and that you have to rebuild the image to change the VEX document if you embed it in the filesystem.