Distroless container images: shipping without a shell

Ship images with no package manager, no shell, and almost no attack surface — and still debug when you need to.

Most container intrusions follow a script after the initial code execution: spawn a shell, fetch a second stage with curl or wget, look around with coreutils, install something with the package manager. A distroless image contains the application, its runtime dependencies, CA certificates and timezone data, and none of those tools. The attacker's script stops at step one. The cost is that your scripts stop there too, and the rest of this guide is about that.

Which image, by what the binary needs

Distroless images (Debian 13 generation)

Every image has four tags: latest and nonroot, and their debug and debug-nonroot counterparts. nonroot runs as user 65532, which is the tag to use unless the binary must bind a port below 1024 without CAP_NET_BIND_SERVICE or write to a root-owned path, both of which are better fixed in the application than by running as root. The unsuffixed names such as gcr.io/distroless/static still resolve, but the -debian13 form says which Debian package set you are inheriting security updates from.

FROM golang:1.27 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /app ./cmd/server
 
FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]          # vector form: there is no shell to expand a string

Four things that stop working, and what replaces them

Shell-form instructions. CMD /app --port 8080 is executed by /bin/sh -c, which does not exist; use the JSON array form for ENTRYPOINT and CMD, and for HEALTHCHECK. Health checks that shell out. HEALTHCHECK CMD curl -f http://localhost/health fails for two reasons, no shell and no curl, and the shell goes first: the probe log records exec: "/bin/sh": stat /bin/sh: no such file or directory before curl is ever looked up. Either build a --healthcheck mode into the binary (CMD ["/app", "healthcheck"]) or let the orchestrator probe over HTTP, as Kubernetes liveness and readiness probes do without any tool in the image. docker exec … sh. For a live container use kubectl debug with an ephemeral container, or run the debug-nonroot tag of the same image in a non-production environment, which adds a busybox under /busybox (on PATH, 382 applets in the image checked here) and nothing else. Package installs at runtime. There is no apt; anything the process needs is copied in at build time, including CA bundles for private authorities and locale or timezone data beyond what the base ships.

The /etc/passwd line above is the one the fixture copied out of the :nonroot image with docker cp (there is no cat inside to print it): nonroot:x:65532:65532:nonroot:/home/nonroot:/sbin/nologin. Two operational habits follow from the tag scheme. The debug and debug-nonroot tags contain a busybox shell, so an admission rule or a CI check that rejects them for production namespaces keeps the property you chose the image for; the difference between :nonroot and :debug-nonroot is one word in a Dockerfile and is easy to leave behind after a troubleshooting session. And because the project rebuilds its images as Debian publishes package updates, pin by digest rather than by tag and rebuild your image on a schedule, so that a fix in ca-certificates or tzdata reaches production through a reviewed change rather than through whatever :nonroot happened to point at when the build ran.

When the image stops working: recovery in order of preference

Distroless is the runtime half of a small-image story; the build half, where the compiler lives in a stage that never ships, is in multi-stage builds. What a minimal image actually blocks, and what it does not, becomes clearer after walking through a container escape step by step and noting which steps needed a shell.

Related posts

Quick reference