- 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.