attest-image
Check an image you built against the migrate attestation, and sign a statement about that exact image. migrate --format container and --format image write a recipe; you build the image. attest-image runs after your build: it reads the built image, grades it against what migrate promised, and when it matches writes a statement that names the image by its digest and has your cosign sign it with your key.
Whoever receives the image verifies it with cosign and your public key. They do not need vrtmv.
It needs no vrtmv account and bills nothing: it calls no vrtmv API.
vrtmv attest-image web.tar --attestation out/vrtmv-attestation.json --key cosign.key
vrtmv attest-image registry.example/shop/web:1.2 --attestation out/vrtmv-attestation.json --key cosign.key -o web.vrtmv-statement.json
vrtmv attest-image web.qcow2 --attestation out/vrtmv-attestation.json --key cosign.key
| Flag | Purpose |
|---|---|
<image> | An OCI archive file (podman save --format oci-archive), a registry reference with its registry written out (registry.example/shop/web:1.2), or a qcow2 or raw disk file. A reference names a tag or a digest, not both. |
--attestation <file> | The vrtmv-attestation.json of the migrate run the image was built from: a --format container run for an archive or a registry image, a --format image run for a disk file. |
--key <key> | What cosign --key takes: a key file or a KMS URI. Required unless --no-sign is given, and refused together with it. An empty value is refused. |
--no-sign | Write the statement and sign nothing. Not with --key or --slsa. |
--slsa | For an image file, also sign a SLSA provenance statement into a second bundle. A registry image gets that statement without the flag. |
-o, --out <file> | Where the statement file is written (default <image>.vrtmv-statement.json). Required for a registry reference. |
--attestation-digest-only | Put the migrate attestation's sha256 in the statement, not the attestation itself. See Who can read the statement. |
--plain-http-registry | The registry is on this machine's loopback address (localhost, 127.0.0.1) and speaks plain HTTP. Refused for any other registry. |
What you need
cosign2.6.5 or later on yourPATH, unless you pass--no-sign. An older one is refused before the image is read, and so is a build of 2.6.5 that is not the release (v2.6.5-rc.1,v2.6.5-dirty). vrtmv was run with 2.6.5 and with 3.1.3, and with no other 3.x.- A key cosign can sign with. vrtmv opens no key and reads no password:
--keyis handed to cosign as you typed it, and a key file's password is cosign's to ask for (COSIGN_PASSWORD, or the terminal). vrtmv generates, stores and publishes no key. The public half is yours to give to whoever verifies. skopeo, for a registry reference. The image is read through it, with the registry logins you already have.COSIGN_REPOSITORYnot set, for a registry reference that is signed. cosign would store the statements in that repository and not with the image, where the verify command below does not find them. The run is refused before cosign is run (exit 2). Unset it, or pass--no-sign.- Root, for a disk file. The file is attached read-only and its root file system mounted, as
verify --imagedoes.
No network is needed to sign an image file with a key file. A KMS key is reached the way cosign reaches it; vrtmv has not been run with one. No entry is made in a transparency log, for a file or for a registry image.
What is checked
The image is graded with the checks verify runs on a target at rest: the target release, the promised packages, and the carried config files by their sha256. For a container image, the Entrypoint in the image's configuration is compared with the attested one. For a disk, the units are read as a machine's at rest.
A statement is written only when the image matches. When it does not, the command says what differs, writes nothing, and exits 1.
Files migrate left out. migrate --format container leaves some of the source's files out of the image, secrets among them, and the attestation lists their paths. A left-out path that a COPY or ADD step of your build put into the image is a mismatch. A left-out path in the base image, or one a RUN step wrote, is reported in the statement (under checks, as paths_the_image_has) and is not a mismatch: /etc/shadow was in every base image looked at. So a secret your own RUN step writes is not caught. Which step made a layer is read from the history the build tool writes into the image. When that cannot be told for a layer that holds a left-out path, the statement says it must not be signed, and it is not. A build squashed into one layer (buildah bud without --layers, podman build --layers=false or --squash) is such a case when the squashed layer holds one. So is an attestation that records no layers of the base image: /etc/shadow is then in a layer nothing tells apart from yours.
For a disk file no left-out file is looked for, and the statement says so under not_checked.
What is written
| Image | Statement file | Signature |
|---|---|---|
| OCI archive file | <file>.vrtmv-statement.json | <file>.sigstore.json beside the file; with --slsa, also <file>.slsa.sigstore.json |
| Registry reference | where --out says | Two statements attached to the image's digest in the registry |
| qcow2 or raw disk file | <file>.vrtmv-statement.json | <file>.sigstore.json beside the file; with --slsa, also <file>.slsa.sigstore.json |
- A registry reference given by tag is resolved once. Everything after names the digest, and so does the verify command the run prints.
- The signature of a file is a file. Nothing is attached to an archive or a disk. Ship the
.sigstore.jsonbundle with the image: a copy without it has no signature, and nothing in the image says one exists. - A file is identified by its sha256. A converted or compressed copy of a disk is another file and is attested again. Two
podman saveruns of one image are two files. - A run removes what an earlier run left before it reads the image: the statement at the path this run writes to, and both bundles beside an image file. A statement an earlier run wrote to another path, with another
--out, stays where it is. A run that is refused for an argument, its key, its cosign orCOSIGN_REPOSITORY(exit 2) removes nothing. - A bundle is read before it is removed.
<file>.sigstore.jsonis also the name other tools give a signature of the file itself. A file under either bundle name is removed only when it reads as the bundle of a statement: a Sigstore bundle whose content is a DSSE envelope with the payload typeapplication/vnd.in-toto+json. The run printsRemoved <path>: it read as the bundle of an earlier statement.for each. Anything else there, a signature of the file itself among them, stops the run with exit 2 and a message that names the file, and nothing is removed. Move that file, or give the image under another name. No signature is checked for this: a bundle of your own statement under that name is removed too.
The run ends by printing the command that verifies what it signed. Hand that command, with your public key, to whoever receives the image.
Exit status
| Exit | Meaning |
|---|---|
| 0 | The image matches, the statement was written, and it was signed unless --no-sign was given. |
| 1 | The image does not match. Nothing was written. |
| 2 | The image or the attestation could not be read, an argument was refused, or cosign is missing or too old. Nothing was written. |
| 3 | The image matches and the statement was written, and a signature is missing: the statement says it must not be signed, or cosign did not sign it, or cosign signed it and did not sign the SLSA statement. The run says which. |
Exit 3 is not 0 on purpose, so that vrtmv attest-image … && podman push … does not go on with a signature missing. When it is the SLSA statement that was not signed, the first one is: its bundle is beside the file, or it is attached to the registry image, and nothing takes it out of a registry again.
Verifying an image
This part is for whoever receives the image. You need cosign 2.6.5 or later and the signer's public key. You do not need vrtmv.
Use cosign 2.6.5 or later. 2.6.1 was measured verifying a statement of this kind less strictly than these commands ask for; no other older version was measured. The commands below were run on 2.6.5 and on 3.1.3.
An image in a registry
cosign verify-attestation \
--key signer.pub \
--type https://vrtmv.com/attestation/image/v1 \
--insecure-ignore-tlog=true \
registry.example/shop/web@sha256:<digest>
Name the image by digest, not by tag: the statement is about one digest, and a tag can be moved.
Exit 0 means a statement of that type is attached to that digest and was signed by the holder of that key. cosign prints the signed envelope on standard output.
An image file
The bundle travels with the file. For web.qcow2 it is web.qcow2.sigstore.json.
sha256sum web.qcow2
cosign trusted-root create --out trusted-root.json
cosign verify-blob-attestation \
--key signer.pub \
--type https://vrtmv.com/attestation/image/v1 \
--insecure-ignore-tlog=true \
--new-bundle-format --trusted-root trusted-root.json \
--bundle web.qcow2.sigstore.json \
--digest <the sha256 the first command printed> --digestAlg sha256
Verified OK and exit 0 mean the bundle is a statement about the file whose sha256 you gave, signed by the holder of that key. Another sha256, or another key, exits 1. So one changed byte in the file exits 1, because its sha256 is another.
- Compute the sha256 yourself, from the file you received. cosign is not given the file here. It compares the sha256 you give with the one the statement names, and nothing else ties the check to your file. Never copy the sha256 from the statement, the bundle or a message from the signer: that sha256 verifies whatever file you have.
sha256sumis in GNU coreutils; on macOS,shasum -a 256 web.qcow2prints the same sha256. - Size and memory. This form takes a file of any size, and cosign does not read the file. Measured on 2.6.5 and 3.1.3, for a file of 1 GiB and one of 4 GiB alike: cosign used about 60 MiB at its peak and took under 0.1 s. Computing the sha256 reads the whole file once, in 2 MiB of memory; it took 16 to 20 s for 4 GiB on the machine measured.
trusted-root.json.cosign trusted-root createwrites a small file that names no authority. With it, cosign 2.6.5 verifies this bundle format without reaching the network. Without it, 2.6.5 on a machine with no network exits 1 with "trusted root is required when using new bundle format", and on a machine with a network it connects out and then verifies. cosign 3.1.3 does not need the file and accepts it.
With the file in place of its sha256
cosign can compute the sha256 itself when you give it the file. For a file of 128 MiB or less, this is the command attest-image prints at the end of a run, without COSIGN_MAX_ATTACHMENT_SIZE. For a larger file the run prints the form above, with the sha256, and names this one as the other way.
cosign trusted-root create --out trusted-root.json
COSIGN_MAX_ATTACHMENT_SIZE=<the file's size in bytes> \
cosign verify-blob-attestation \
--key signer.pub \
--type https://vrtmv.com/attestation/image/v1 \
--insecure-ignore-tlog=true \
--new-bundle-format --trusted-root trusted-root.json \
--bundle web.qcow2.sigstore.json \
web.qcow2
Verified OK and exit 0 mean the bundle is a statement about this exact file, signed by the holder of that key. One changed byte in the file, or another key, exits 1.
COSIGN_MAX_ATTACHMENT_SIZE. cosign reads no file over 128 MiB unless this says it may, and exits 1 with "size of layer exceeded the limit" whatever the bundle says. A VM image is larger than that as a rule. Set it to the file's size in bytes. For a smaller file, leave it out.- Memory. With the limit raised, cosign holds the file in memory. Measured on 2.6.5 and 3.1.3: 2.1 GiB at its peak for a file of 1 GiB, and 9.3 GiB for a file of 4 GiB. Larger files were not measured. Expect to need more than twice the file's size. The form above, with the sha256, does not have this cost.
What cosign prints, and what it means
| cosign prints | Meaning here |
|---|---|
--insecure-ignore-tlog=true (the flag you typed) | "Do not look for a transparency log entry." None was made: the statement was signed with a key and logged nowhere. The signature is checked against the public key you gave and against nothing else. The flag's name is cosign's. Without the flag the command exits 1. |
WARNING: Skipping tlog verification is an insecure practice … | The same thing, said by cosign on every such verification. |
Existence of the claims in the transparency log was verified offline | Printed for a registry image whose statement cosign 3.1.3 attached. No log was consulted and no entry exists. |
Flag --new-bundle-format has been deprecated … | cosign 3.1.3 says this because the format is its only one. The command works as written on 2.6.5 and on 3.1.3. |
Reading the statement
Verifying checks the signature, the digest and the type. It does not read what the statement says. Read it:
# a registry image: the envelope cosign printed
cosign verify-attestation … | jq '.payload | @base64d | fromjson | .predicate'
# an image file: the bundle
jq '.dsseEnvelope.payload | @base64d | fromjson | .predicate' web.qcow2.sigstore.json
Run the second only on a bundle that verified.
| Field | What it says |
|---|---|
verdict | Always match. No statement is written for an image that does not match. |
image | What was read: the kind, the digests, and for a disk its format and size. |
migrate_attestation | The sha256 of the migrate attestation, the attestation itself under embedded unless it was left out, and signature. |
checks | Each check with what was promised and what the image has. For a container image, the left-out paths the image has are here, as paths_the_image_has. |
left_out_rule | For a container image: the rule about left-out files, and whether it could be applied to every layer. |
base_image | For a container image: the base image the attestation names. It was not checked. |
image_target | For a disk: the VM image the attestation claims. It was not checked. |
grader_did_not_verify | What the checks of verify could not establish on this image. |
signing | may_be_signed, and the reasons when it is false. vrtmv signs only a statement that says true. cosign does not look and verifies either, so look. |
units_not_started | For a container image: the source's services the image does not start. |
not_checked | What the command did not check, in sentences. Read this list. |
migrate_attestation.signature is absent when the migrate attestation carried no signature of vrtmv's signing service. The attestation is then the signer's word for what migrate promised.
What a verified statement tells you
- The holder of the key signed a statement about this exact image, by digest.
- That statement says
vrtmv attest-imageread the image and it matched the migrate attestation the statement carries: the packages and the carried config files that attestation promises.
The signature shows who signed and which image. That vrtmv wrote the statement, and that what it says is so, rest on the key's holder.
What it does not tell you. The statement says the first three itself, under not_checked:
- How the image was built, or who built it. vrtmv wrote the recipe and checked the result. It did not build the image and did not see it built.
- Whether the recipe used was the one vrtmv wrote.
- Anything that needs the workload running. A disk image was not booted.
- Whoever holds the key can sign any statement. The signature is as good as your trust in the key.
The second statement: SLSA provenance
A registry image carries a second statement, and an image file does when the signer ran with --slsa (bundle <file>.slsa.sigstore.json). Verify it with the same command and --type slsaprovenance1; for a file, give that bundle to --bundle as well.
It is of type https://slsa.dev/provenance/v1. It names the migrate attestation by its sha256, says the build was the operator's and was not observed, and claims no SLSA level. The verdict is in the first statement, not in this one.
Who can read the statement
By default the statement carries the whole migrate attestation. Anyone who can pull the image from the registry, or who has the bundle, can read it. Among what is in it: the package list, the paths of the carried config files, the paths (not the contents) of the files left out as secrets, the source and the target, the units, and what migrate recorded of the firewall, services, accounts, cron, mounts and SELinux. This list is not complete. Read your vrtmv-attestation.json before you publish a statement: every field of it is in the statement.
--attestation-digest-only puts the attestation's sha256 in the statement instead; the attestation file then travels by another route. The statement still carries what attest-image found: each check with what was promised and what the image has, the left-out paths the image has, the names of the units not started, and each layer's line of the build history.
New to vrtmv? Sign up free for 10 migrations, or get a free assessment: run it on one hard host and we review the parity report with you.