Protego field desk
Supply Chain and Image Security · Supply chain

L16. Minimal Base Images: Distroless, Scratch and Chainguard

Course outlineLesson 16 of 18

Every package in your container image is attack surface. Learn how to reduce image size and vulnerability count by using distroless, scratch, and Chainguard base images.

Choose a Runtime, Not Just a Smaller Image

A minimal image removes tools and libraries the application does not need. This reduces unnecessary attack surface, but the application, runtime, and copied dependencies can still contain vulnerabilities. Compare images using a current scan of a specific digest; package counts, CVE counts, and sizes change with releases and scanner databases.

Distroless Images

The distroless project publishes language-specific runtimes without a production shell or package manager. Its debug variants include a shell. Use exec-form commands because shell-form commands require a shell that is absent from the production image.

For a Python application using only the standard library, save this as main.py:

import platform
print(platform.python_version())

Then build with:

FROM gcr.io/distroless/python3-debian13:nonroot
WORKDIR /app
COPY main.py /app/main.py
CMD ["main.py"]
docker build -t protego-python-demo .
docker run --rm protego-python-demo

The expected output is the runtime's Python version. This example deliberately needs no pip dependencies. For applications that need packages, use a compatible builder and copy the installed dependencies or virtual environment into the runtime. Copying only the application folder after a global pip install loses the installed packages. Match Python versions, native extensions, and system libraries across stages.

Removing a shell makes common post-exploitation workflows harder. It does not prevent an attacker from using the application runtime to read files, make network requests, or execute malicious code.

Scratch Images

scratch starts with an empty filesystem layer. Copy in a binary with no unresolved runtime dependencies. Go with CGO disabled is one option; a Rust binary must also be built for a suitable static target rather than assuming the default output is static.

For an existing Go module containing a server main package:

FROM golang:1 AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o /server .

FROM scratch
COPY --from=builder /server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER 65532:65532
ENTRYPOINT ["/server"]

The server must support a non-root user and an unprivileged listening port. The copied CA bundle supports public HTTPS certificate validation. Scratch does not contain libc or a shell, but a statically linked application can implement DNS resolution itself. An empty base does not make the copied binary or dependencies vulnerability-free.

Chainguard Images

Chainguard's minimal Python image uses Wolfi, runs as nonroot by default, and omits shells and package managers. The development variant supplies build tools; the full variant prioritizes upstream compatibility. Review the specific image's SBOM, signature, available tags, and update policy rather than assuming every variant has the same contents.

FROM cgr.dev/chainguard/python:latest
WORKDIR /app
COPY --chown=nonroot:nonroot main.py /app/main.py
CMD ["main.py"]

For pip dependencies, Chainguard documents building a virtual environment in the matching latest-dev image and copying it to the runtime. Rebuild and deploy after base-image updates; running containers do not receive new image contents automatically.

Compare Operational Trade-offs

Image familyRuntime contentsWhat to verify
Distribution baseGeneral-purpose user spaceRemove unnecessary packages and keep it patched
DistrolessSelected runtime and librariesMatch dependencies; production variants have no shell
Chainguard minimalSelected runtime, without development toolsCheck the exact variant, SBOM, and supported tags
ScratchOnly what you copy inSupply binary dependencies, CA roots, and non-root settings

Multi-Stage Builds and Digest Pinning

Use a builder stage when compilation or dependency installation requires tools that the final image does not need. Copy only required artifacts. A standard-library-only application can use a single runtime stage.

The examples use readable tags for the lab. For deployment, select a verified release and record its actual digest. Inspect the resolved image reference rather than copying a made-up digest:

docker pull gcr.io/distroless/python3-debian13:nonroot
docker image inspect --format '{{index .RepoDigests 0}}' gcr.io/distroless/python3-debian13:nonroot

Use that returned image@sha256 reference in FROM. Pinning fixes the content; it does not establish publisher trust or automatically apply security patches. Verify signatures, scan the final image, and deliberately update the digest when rebuilding.

Continue Learning

Then verify image signatures with Cosign and scan the final image.

References

Exam Focus Points
  • ✓Minimal images remove unnecessary packages; scan the final digest and application dependencies instead of assuming zero vulnerabilities
  • ✓Distroless images contain only the application runtime with no shell, package manager, or utilities
  • ✓Scratch images are completely empty and work for statically compiled binaries (Go, Rust)
  • ✓Chainguard minimal Python runs as nonroot and has no shell or package manager; inspect its SBOM and rebuild to adopt updates
  • ✓Pin base image versions to a specific digest (not a mutable tag) to prevent supply chain attacks through tag manipulation
Knowledge Check

1. Why is the absence of a shell in distroless images a security benefit?

2. What type of applications can use scratch (empty) base images?

3. Why should you pin base images by digest instead of tag?