Stamp the base image name and digest into every build with the OCI annotation keys image.base.name and image.base.digest. When an advisory hits a base, you can then search for every image built on it instead of reading Dockerfiles. The keys are in the OCI image specification and are optional.
What the specification defines
The OCI image specification lists pre-defined annotation keys under the org.opencontainers.image prefix. Two matter here:
org.opencontainers.image.base.name: the image reference of the image this one is based on. It should be a fully qualified reference, without an assumed default registry.org.opencontainers.image.base.digest: the digest of the image this one is based on. It should be the immediate image sharing the first layers, such as the one in a FROM statement, and not other images used to generate contents.
The spec also notes that when the name is given, the digest should be that of the manifest the reference points to.
Why this is worth ten minutes
A Dockerfile tells you the base that was intended at write time. It does not tell you what the tag resolved to at build time. Without a record, the question "which of our images use the bad base digest" cannot be answered from the image alone.
With the annotations, the answer is a query over image metadata. That is faster than cloning repositories, and it covers images built from files nobody can find.
How to add them
- At build start, resolve the base reference to a digest. Your tooling can read the registry for the manifest digest of the tag.
- Pass the name and digest to the build as arguments or metadata.
- Apply them as annotations or labels on the output image. Your build tool's documentation says how to add annotations, and labels are an older, widely supported route.
- Check the result by inspecting the built image.
- Fail the pipeline if the annotations are missing, so coverage grows automatically.
Keep the digest value aligned with what the build used, not something typed by hand.
What to do with the data
| Question | How the annotation helps |
|---|---|
| Which images share this base digest? | Filter on base.digest |
| Which images are on an unsupported release? | Map base.name to the release, then to its support date |
| Did the last rebuild actually refresh the base? | Compare base.digest across builds |
| Which team owns the affected image? | Join with your register |
Limits to keep in mind
The annotations are claims made by whoever built the image. They are useful bookkeeping, but they are not proof. An image built outside your pipeline may have none, or wrong values. Confirm important findings with a scan of the actual contents.
Multi stage builds have a base per stage. The convention covers the immediate base of the final image, which is usually what you want for a deployed artifact.
Pair it with an SBOM
The annotations give you the base. The SBOM gives you everything installed on top of it. Together they let you say "this image contains this package, and its base is this digest".
Where Safeguard fits
Safeguard scans the contents of each image and records its operating system and packages in an SBOM, which gives you the verification that annotations alone cannot. The free scan at https://gold.safeguard.sh/scan shows the result for one image.
Quick check
Are these annotations mandatory?
No. The specification marks them as optional conventions. Their value depends on you stamping them consistently.
Is a label the same as an annotation?
They are different mechanisms. The spec notes older label conventions were superseded by annotation keys under the same prefix, and many tools read both.
Sources
Last reviewed: 19 October 2026.
