CL-0019: Image tags without digest pins (@sha256)¶
Severity: MEDIUM (how it is derived)
The service names a version tag, which the registry can point at different
bytes at any time. Add the image's @sha256: digest, keep the tag beside it so
update tools can find newer versions, and let a bot move the pin.
Fix¶
services:
web:
image: nginx:1.27-alpine@sha256:... # tag kept, digest added
- Get the digest. Either command prints the multi-arch index digest without pulling the image:
# Print the index digest for a tag
docker buildx imagetools inspect nginx:1.25.3 --format '{{ .Manifest.Digest }}'
# sha256:c7a6ad68be85142c7fe1089e48faa1e7c7166a194caa9180ddea66345876b9d2
# The same with crane, which runs as a container
docker run --rm gcr.io/go-containerregistry/crane digest nginx:1.25.3
docker buildx comes with Docker Desktop, and on Linux with the
docker-buildx-plugin package. Or pull first and read the digest back from
the local image:
docker pull nginx:1.25.3
docker image inspect --format '{{index .RepoDigests 0}}' nginx:1.25.3
# nginx@sha256:c7a6ad68be85142c7fe1089e48faa1e7c7166a194caa9180ddea66345876b9d2
- Put it after the tag,
name:tag@sha256:<digest>. Keep the tag: Renovate and Dependabot look up newer digests by tag, so a barename@sha256:…is never refreshed.
# Before
services:
app:
image: nginx:1.25.3
# After
services:
app:
image: nginx:1.25.3@sha256:c7a6ad68be85142c7fe1089e48faa1e7c7166a194caa9180ddea66345876b9d2
- Check you pinned the index, not one architecture (why it matters):
# An index reads ...image.index.v1+json (or ...manifest.list.v2+json)
docker buildx imagetools inspect nginx@sha256:c7a6ad68be85142c7fe1089e48faa1e7c7166a194caa9180ddea66345876b9d2 | grep -m1 MediaType
# MediaType: application/vnd.oci.image.index.v1+json
Only the first MediaType line describes the digest itself; the indented
ones below it are the per-platform manifests an index lists, which is why
-m1. A single-architecture digest's first line reads
application/vnd.oci.image.manifest.v1+json (or
...distribution.manifest.v2+json) instead.
- Let Renovate move the pin. With this
renovate.json, Renovate pins every tag in your compose files to its digest and opens a PR whenever the image behind a tag changes:
{
"extends": ["config:recommended", "docker:pinDigests"]
}
Run against nginx:1.25.3, Renovate's dry run proposes a pinDigest
update to the same sha256:c7a6ad68… the commands above print.
Dependabot can keep
digest pins current on GitHub.
- Check the finding is gone:
compose-lint -q compose.yaml | grep CL-0019 # prints nothing once fixed
Pin the index digest, not a per-arch digest¶
For multi-arch images (most official images on Docker Hub), there are two kinds of digests:
- OCI index / manifest list digest — points to a manifest that lists per-architecture manifests. This is what
docker pullresolves through. - Per-arch manifest digest — points to a single architecture (e.g.
linux/amd64).
Pin the index digest. Pinning a per-arch digest will break ARM64 (or AMD64) users who pull on the other architecture. All three commands in step 1 return the index digest (observed on Docker 29.7.2 with the containerd image store). A per-arch digest comes from places like Docker Hub's tag page, which lists one digest per platform, or the manifests list inside the index; step 3 tells the two apart.
Tested on: Docker 29.7.2 with Compose 5.5.0, on a host without AppArmor (Yama ptrace_scope 1); the Fix steps above were re-run there in October 2026. Also measured in throwaway VMs in October 2026 (Docker 29.9.1 or 29.1.3): on the classic image store (overlay2, containerd snapshotter off, Ubuntu 24.04 with AppArmor), RepoDigests gives the same index digest crane returns. Not tested: Dependabot.
What it detects¶
Services using a version tag (e.g., nginx:1.25.3) without a digest pin (@sha256:...). This rule does not overlap with CL-0004:
| Image reference | CL-0004 | CL-0019 |
|---|---|---|
nginx |
fires | — |
nginx:latest |
fires | — |
nginx:1.25.3 |
— | fires |
nginx:1.25.3@sha256:... |
— | — |
Build-only services (no image: key) are skipped.
Why it matters¶
Docker tags are mutable pointers. A registry operator, compromised CI pipeline, or supply chain attack can overwrite nginx:1.25.3 with a different image. Without a digest pin, docker compose pull will silently fetch the replacement. You have no cryptographic guarantee that the image you pull today is the same one you tested last week.
No CIS control asks for a digest. CIS Docker Benchmark 5.28 is the nearest: it asks that a stale cached image is not used, and its remediation recommends version pinning for images. It does not mention digests, so it is cited by CL-0004, the rule for an image with no version pin, and not by this rule.
ATT&CK coverage¶
Remediating this finding contributes to mitigating the following MITRE ATT&CK techniques (pinned to ATT&CK v18). compose-lint is a static analyser, so this is mitigation coverage — it detects nothing at runtime.
| Technique | Tactic |
|---|---|
| T1204.003 User Execution: Malicious Image | Execution |
| T1525 Implant Internal Image | Persistence |
See also¶
- CL-0004 — image not pinned to a tag (the weaker prerequisite to digest pinning)
- Hardening guide, step 2 — where this rule fits when hardening a whole file
Severity derivation¶
Derivation (see severity model):
- Baseline: B — the attacker can read the compose file, or influence what the image reference resolves to; no code execution anywhere yet
- Precondition: Second flaw — a tag pin is only defeated by something outside this file: a registry operator, a compromised publishing pipeline, or an account takeover overwriting the tag
- Impact: Single container — the substituted image runs as this service
- Qualifier/modifier: none
- Derived: Second flaw × Single container = MEDIUM
- Shipped: MEDIUM
- Evidence: Not runtime-observable — compose-lint does not read the registry (ADR-020). The premise is the registry API contract: a tag is a mutable pointer, and a digest is content-addressed, so a digest-pinned pull cannot silently resolve to different bytes
References: - Docker docs — pull an image by digest (immutable identifier) - OWASP Docker Security Rule #13 — general supply-chain framing; note it contains no digest-specific guidance
A reference means the rule relates to that source. It does not mean a file with no finding complies with it. The CIS, OWASP and ATT&CK mapping for every rule, and the tags SARIF output carries for it, are on Standards mapping.