Implementing Container Image Minimal Base With Distroless

Implementing Container Image Minimal Base with Distroless

Overview

Google distroless images contain only your application and its runtime dependencies, without package managers, shells, or other programs found in standard Linux distributions. By eliminating unnecessary OS components, distroless images achieve up to 95% reduction in attack surface compared to traditional base images like ubuntu or debian. Major projects including Kubernetes itself, Knative, and Tekton use distroless images in production. As of 2025, Docker also offers Hardened Images (DHI) as an open-source alternative for minimal container bases.

When to Use

• When deploying or configuring implementing container image minimal base with distroless capabilities in your environment
• When establishing security controls aligned to compliance requirements
• When building or improving security architecture for this domain
• When conducting security assessments that require this implementation

Common Misconfigurations & Verification

• Distroless image still runs as root: the plain gcr.io/distroless/static-debian12 tag defaults to UID 0; only the :nonroot tag (UID 65534) drops root, and even then an explicit USER nonroot:nonroot is needed if you override the entrypoint. Verify: docker run --rm <img> id should not report uid=0.
• No readOnlyRootFilesystem at runtime: distroless shrinks the image but a writable rootfs still lets an attacker drop files - pair it with securityContext.readOnlyRootFilesystem: true and allowPrivilegeEscalation: false.
• Setuid binaries copied in: COPY --from=builder can pull in setuid helpers from the build stage. Verify with dive <img> or docker run --rm <img> + a find for mode 4000 in the build stage.
• Wrong base for linkage: a CGO/dynamically linked binary on static-debian12 fails at runtime ("no such file"); use base- or cc-debian12. A glibc binary needs base, not static.
• Debug variant in production: :debug ships a busybox shell at /busybox/sh, reintroducing exec - confirm prod manifests pin the non-debug, :nonroot tag by digest.
• Verify the result: trivy image <img> should drop to 0-5 findings vs the previous base, and crane export <img> - | tar -tf - | grep -E 'sh$|apt|apk' should return nothing.

Prerequisites

• Docker 20.10+ or compatible container build tool (Buildah, Kaniko)
• Multi-stage Dockerfile knowledge
• Application compiled as a static binary or with runtime bundled
• Container registry for image storage

Available Distroless Images

Multi-Stage Build Patterns

Go Application

# Build stage
FROM golang:1.22-bookworm AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server

# Runtime stage - static distroless
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder /server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]

Java Application

# Build stage
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

# Runtime stage - Java distroless
FROM gcr.io/distroless/java21-debian12:nonroot
COPY --from=builder /app/target/app.jar /app.jar
USER nonroot:nonroot
ENTRYPOINT ["java", "-jar", "/app.jar"]

Python Application

# Build stage
FROM python:3.12-bookworm AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --target=/deps -r requirements.txt
COPY . .

# Runtime stage - Python distroless
FROM gcr.io/distroless/python3-debian12:nonroot
WORKDIR /app
COPY --from=builder /deps /deps
COPY --from=builder /app /app
ENV PYTHONPATH=/deps
USER nonroot:nonroot
ENTRYPOINT ["python3", "/app/main.py"]

Node.js Application

# Build stage
FROM node:22-bookworm AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

# Runtime stage - Node distroless
FROM gcr.io/distroless/nodejs22-debian12:nonroot
WORKDIR /app
COPY --from=builder /app .
USER nonroot:nonroot
CMD ["server.js"]

Security Benefits

Attack Surface Comparison

Security Implications

• No shell: Attackers cannot exec into containers to run commands
• No package manager: Cannot install additional tools or malware
• No coreutils: No cat, ls, find, curl for reconnaissance
• Minimal CVEs: Fewer packages means fewer vulnerabilities to patch
• Non-root by default: :nonroot tag runs as UID 65534

Debugging Distroless Containers

Since distroless has no shell, use these techniques for debugging:

Debug Image Variant

# Use debug variant in non-production environments only
FROM gcr.io/distroless/base-debian12:debug
# Includes busybox shell at /busybox/sh

# Exec into debug variant
kubectl exec -it pod-name -- /busybox/sh

Ephemeral Debug Containers (Kubernetes 1.25+)

# Attach a debug container with full tooling
kubectl debug -it pod-name --image=busybox:1.36 --target=app-container

Crane/Dive for Image Inspection

# Inspect image layers without running
crane export gcr.io/distroless/static-debian12 - | tar -tf - | head -50

# Analyze image layers
dive gcr.io/distroless/static-debian12

Image Scanning Results

Typical vulnerability comparison using Trivy:

# Scan Ubuntu-based image
trivy image myapp:ubuntu
# Result: 47 vulnerabilities (3 CRITICAL, 12 HIGH)

# Scan Distroless-based image
trivy image myapp:distroless
# Result: 2 vulnerabilities (0 CRITICAL, 0 HIGH)

References

• GoogleContainerTools/distroless GitHub
• Distroless Images - Docker Documentation
• Alpine, Distroless, or Scratch? - Google Cloud
• Docker Hardened Images