Skip to content
Tutorials Center
My learning

Topics

Lesson 69 of 111 ยท Security

Image Security and Scanning

Keep Docker images safe: choose minimal bases, pin by digest, generate an SBOM with BuildKit, scan for vulnerabilities and verify signatures with Cosign.

Everything running in your container came from an image, and an image is a pile of other people's software: a base operating system, language runtimes, libraries, your dependencies, and your own code. Most real-world container incidents do not begin with a clever escape from the sandbox. They begin with a known vulnerability in an old package, a tag that quietly changed, or an image nobody could vouch for.

This lesson covers the practical defense: ship less software, say exactly which bits you are using, find known problems early, and prove where an image came from. The commands in the first three sections were run on a real Docker 29 and BuildKit. The scanner and signing sections are read-only examples because those tools are not part of Docker itself; they are written carefully from the tools' documented behavior.

The attack surface is everything in the image

A vulnerability can only hurt you if the vulnerable code is present. A package you never use is still scanned, still reported and still available to an attacker who gets a shell. So the single most effective rule is less is more.

Here is a rough count of installed packages and executables in some popular base images (counted with dpkg -l or apk list, plus the files in the bin folders):

Base image Installed packages Files in bin folders
alpine:3 16 320
debian:bookworm-slim 88 791
python:3.13-slim 87 693
ubuntu:24.04 92 833
gcr.io/distroless/static-debian12 no package manager, no shell almost none

(The numbers drift with every release; the proportions stay.) The disk sizes follow the same pattern: roughly 7 MB for busybox, 13 MB for alpine, around 120 MB for debian:bookworm-slim and ubuntu, and well over 150 MB for full debian:bookworm. See Choosing a Base Image for the trade-offs between them (musl versus glibc, compatibility, debugging).

A distroless image contains your application and its runtime dependencies only: no shell, no package manager, no curl. That is a real security gain, because an attacker with code execution finds nothing to work with. You can see it by trying to start a shell in one:

CONSOLE
$ docker run --rm --entrypoint sh gcr.io/distroless/static-debian12:nonroot -c 'echo hi'
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "sh": executable file not found in $PATH

The :nonroot variant also runs as a non-root user by default (UID 65532). The price is that debugging is harder; use the techniques in Debugging Containers.

Practical rules for small images

  1. Multi-stage builds. Compile in a fat builder stage and copy only the result into a slim runtime stage. Compilers and headers never reach production. (Multi-Stage Builds)
  2. Install only what you need. In Debian images use --no-install-recommends and delete the apt lists in the same RUN; in Alpine use apk add --no-cache.
  3. No tools "just in case". Leave out curl, wget, vim and ssh. If the healthcheck needs an HTTP client, use your language runtime instead.
  4. A .dockerignore keeps .git, .env and local config out of the build context (Build Context and .dockerignore).

Pinning: tags move, digests do not

A tag such as alpine:3 is a label that someone can move to a different image at any time. The maintainers do this on purpose to deliver security fixes, which is good, but it means that the same Dockerfile built on two days can contain different software. A digest is the SHA-256 hash of the image's manifest: it identifies exactly one image, forever.

Find the digest of an image you have pulled:

CONSOLE
$ docker image inspect alpine:3 --format '{{json .RepoDigests}}'
["alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a"]

(Yours will differ as alpine:3 is updated.) Use it in a Dockerfile by writing the tag, an @, and the digest:

DOCKERFILE
FROM alpine:3@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
RUN apk add --no-cache curl
USER 10001
CMD ["curl", "--version"]
CONSOLE
$ docker build -q -t demo-pinned .
sha256:cb29240224ed...
$ docker run --rm demo-pinned | head -1
curl 8.22.0 (x86_64-alpine-linux-musl) libcurl/8.22.0 OpenSSL/3.5.9 ...

When a digest is present, Docker ignores the tag for resolving the image (the tag stays as a human-readable note). If the registry returns different content, the pull fails the hash check instead of silently accepting it.

You can also see what a tag points to with buildx:

CONSOLE
$ docker buildx imagetools inspect alpine:3 | head -4
Name:      docker.io/library/alpine:3
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a

That digest belongs to the multi-platform index; each architecture has its own manifest digest inside it. Pinning the index digest keeps your Dockerfile portable.

Pinning has a cost: you stop receiving security patches automatically. A pinned digest from last year contains last year's vulnerabilities. Pin, and then update on a schedule with a bot such as Dependabot or Renovate, which opens a pull request when a new digest appears. A pinned image that nobody updates is worse than a moving tag.

A reasonable policy: pin by digest in production Dockerfiles and Compose files, use a version tag (postgres:17-alpine, never latest) during development, and rebuild regularly. Version tags and latest are discussed in Tags and Registries and Tagging and Versioning Strategies.

Know what is inside: SBOMs

An SBOM (software bill of materials) is a machine-readable list of every package in an image. When the next big vulnerability is announced, an SBOM lets you answer "are we affected?" in seconds instead of days.

BuildKit can create one for you during the build, using the Syft scanner. Ask for it with --sbom=true. Here we export the result to an OCI archive so we can look inside:

CONSOLE
$ docker buildx build --sbom=true --provenance=mode=max -t demo-sbom -o type=oci,dest=out.tar .
...
#9 exporting attestation manifest sha256:71ffe96a62441e...
#9 exporting manifest list sha256:dc73bc6cb8e755...
#9 sending tarball
#9 DONE 1.6s

The archive now contains the image and two attestations attached to it: the SBOM (in SPDX format) and build provenance (how and where the image was built). Reading the SPDX document from the archive shows the packages. For the little image above:

TEXT
26 package entries (the image itself plus 25 packages)
busybox     1.37.0-r31
curl        8.22.0-r0
libcrypto3  3.5.9-r0
libcurl     8.22.0-r0
libssl3     3.5.9-r0
musl        1.2.6-r3
...

You normally do not unpack archives by hand. When you push the image to a registry that supports attestations, tools read them directly. A read-only example with a pushed image:

Terminal
# read-only example: attach SBOM and provenance while pushing
docker buildx build --sbom=true --provenance=mode=max \
  -t registry.example.com/team/app:1.4.0 --push .

# read-only example: view the SBOM later
docker buildx imagetools inspect registry.example.com/team/app:1.4.0 \
  --format '{{ json .SBOM }}'

Docker's default image store on Linux servers (the classic overlay2 store) cannot hold attestations next to the image, which is why we exported to an OCI archive. With the containerd image store (the default in recent Docker Desktop) and with registries, attestations travel with the image.

Finding vulnerabilities: scanners

A scanner compares the package list in an image (the SBOM, or its own detection) against databases of known vulnerabilities (CVEs). Popular options are Trivy, Grype and Docker Scout. They are separate programs, so the next examples are read-only: install the tool of your choice and run it on your own images.

Terminal
# read-only example: Trivy, scanning a local image for serious problems
trivy image --severity HIGH,CRITICAL --ignore-unfixed myapp:1.4.0

# read-only example: Docker Scout, quick summary of an image
docker scout quickview myapp:1.4.0

# read-only example: Grype
grype myapp:1.4.0

The output is a table that lists, for each finding, the package, the installed version, the CVE identifier, its severity and (when one exists) the version that fixes it. Learn to read it with three questions:

  1. Is it fixed? --ignore-unfixed hides issues with no patch yet; there is nothing you can do about those besides monitoring.
  2. Is it reachable? A vulnerability in a library function your program never calls, or in a build tool that is not in the runtime image, matters much less than one in your web server. Multi-stage builds make whole categories vanish.
  3. What is the fix? Usually "rebuild with a newer base image" or "bump this dependency".

Do not aim for zero findings. Aim for no known high or critical issues that are fixable and reachable, and for a process that notices new ones.

Looking inside layers, and watching at run time

Scanners tell you what is vulnerable. Two other kinds of tools cover the rest:

  • Layer explorers such as dive open an image layer by layer and show which files each layer adds, changes or removes, plus an estimate of wasted space (a file created in one layer and deleted in the next still costs bytes). They help you find out why an image is large and spot files that should not be there, such as a .git folder or an .env file. Read-only example: dive myapp:1.4.0. docker history gives a rougher view without extra installs.
  • Runtime security tools such as Falco watch the system calls of running containers and raise alerts for behavior no image scan can see: a shell started inside a web-server container, a write under /etc, an outbound connection to an unexpected address. Commercial platforms (Aqua, Sysdig Secure, Twistlock/Prisma Cloud) combine scanning, policy and run-time detection. Treat them as a second line of defense; a hardened image with non-root users and dropped capabilities comes first.

Where scanning belongs

  • On every pull request / build, failing the pipeline on new critical, fixable vulnerabilities (see Docker in CI).
  • On a schedule against what is already deployed. Vulnerabilities are discovered after you ship, so an image that was clean last month can be vulnerable today without any change.
  • In your registry, if it scans on push (Docker Hub, GHCR, ECR and others offer this).

A pipeline step usually looks like this (read-only example):

YAML
# read-only example: GitHub Actions step
- name: Scan image
  run: trivy image --exit-code 1 --severity CRITICAL --ignore-unfixed myapp:${{ github.sha }}

--exit-code 1 makes the step fail when something is found, so a vulnerable image never gets pushed.

Trusting the source

Scanners tell you whether software is known to be bad. They cannot tell you whether an image is really from who it claims. Three habits cover most of the risk:

  • Prefer official and verified publisher images (the "Docker Official Image" and "Verified Publisher" badges on Docker Hub) and read their Dockerfiles. Be suspicious of images with a name that is one letter off from a popular one (typosquatting) or with few pulls and no source repository.
  • Keep your own base images in your own registry. Rebuild them on a schedule and let your teams build FROM those, so you can patch in one place.
  • Sign your images so that deployment systems can verify them.

Signing with Cosign (read-only example)

Cosign (part of the Sigstore project) attaches a cryptographic signature to an image in the registry. Anyone with your public key can check that the image has not been modified since you signed it. Signing by digest is important: you sign exactly one image, not a tag that can move.

Terminal
# read-only example: create a key pair (you are asked for a password)
cosign generate-key-pair

# read-only example: sign an image by digest
cosign sign --key cosign.key registry.example.com/team/app@sha256:<digest>

# read-only example: verify before deploying
cosign verify --key cosign.pub registry.example.com/team/app@sha256:<digest>

On success, verify prints the signature details as JSON; on failure it exits non-zero and says no matching signatures were found. Many teams use Cosign's keyless mode instead, where CI proves its identity through an OpenID Connect token and no long-lived private key exists. Enforcement happens in the platform that deploys: for example, an admission controller in Kubernetes can refuse to run unsigned images. Docker alone does not enforce signatures when you run docker run.

Never put the private key (cosign.key) or its password in an image, a repository or a build log. Store it in your CI system's secret store. See Managing Secrets.

Do not leak secrets into layers

A security bug that scanners rarely catch is a secret baked into an image. Every instruction's effect is stored in a layer, and anyone who can pull the image can read them:

DOCKERFILE
# NEVER do this
ENV API_TOKEN=abc123
COPY .env /app/.env

Even if a later RUN rm /app/.env removes the file, it stays in the earlier layer. The lessons ENV and ARG and Managing Secrets show the safe alternatives, such as BuildKit secret mounts.

A hardening routine for images

Combine what you learned in this lesson into one routine:

  1. Start from a small, maintained base (slim, alpine or distroless) and a specific version tag.
  2. Build in stages; copy only runtime files into the last stage.
  3. Run as a non-root user (Non-Root Users and Capabilities).
  4. Generate an SBOM and provenance at build time.
  5. Scan in CI and on a schedule; patch by rebuilding.
  6. Pin base images by digest, and let a bot propose updates.
  7. Push to a registry you control and sign by digest.

Clean up

CONSOLE
$ docker rmi demo-pinned

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is alpine:3@sha256:... safer for reproducible builds than alpine:3?

    Tags are mutable labels. A digest is a hash of the manifest, so it cannot point to different content. The downside is that you must update it yourself to receive patches.
  2. 2. What is the main security benefit of a distroless image?

    Less software means a smaller attack surface. The trade-off is harder debugging, because there is no shell to exec into.
  3. 3. What does an SBOM give you?

    An SBOM is an inventory, not a fix and not a signature. BuildKit can generate one with --sbom=true.
  4. 4. An image passed a scan last month. Why should you scan again today?

    Scans compare against the vulnerability databases as they are today. Scan on a schedule as well as in CI.
  5. 5. You added RUN rm /app/.env after COPY .env /app/.env. Is the secret gone from the image?

    Layers are immutable. Deleting a file in a later layer only hides it in the final view; the data is still stored in the earlier layer.

Summary

  • Ship less: small bases, multi-stage builds and no extra tools shrink the attack surface and the scanner report.
  • Tags move; digests do not. Pin production images by digest and update them regularly with a bot, or you freeze old vulnerabilities in place.
  • docker buildx build --sbom=true --provenance=mode=max records what is in an image and how it was built.
  • Scan with Trivy, Grype or Docker Scout in CI and on a schedule; focus on fixable, reachable high and critical findings.
  • Prefer official and verified images, keep your own base images, and sign by digest with Cosign so deployment can verify them.
  • Never bake secrets into layers: deleting them later does not remove them.

Next: Managing Secrets