What it does. Reduces container attack surface by building application images on Google distroless base images that ship only the application runtime - no shell, package manager, or OS utilities - using multi-stage build patterns plus debugging and scanning techniques adapted to distroless. Use when hardening container images, cutting attack surface in a container architecture, or answering an assessment finding about bloated base images. Keywords: distroless, multi-stage build, no shell, nonroot tag, debug image, scratch, attack surface. Do not use for scanning an image for known CVEs - use scanning-docker-images-with-trivy. Part of mukul975/Anthropic-Cybersecurity-Skills (817 security skills) (mukul975/Anthropic-Cybersecurity-Skills).

Upstream	mukul975/Anthropic-Cybersecurity-Skills
Skill file	skills/implementing-container-image-minimal-base-with-distroless/SKILL.md
License	Apache-2.0 (skill folder LICENSE)
Author	mukul975
Fetched	2026-09-10

Install

• npx skills add mukul975/Anthropic-Cybersecurity-Skills --skill implementing-container-image-minimal-base-with-distroless, or copy the skill folder into ~/.claude/skills/implementing-container-image-minimal-base-with-distroless/.
• Raw file: curl -sL https://raw.githubusercontent.com/mukul975/Anthropic-Cybersecurity-Skills/HEAD/skills/implementing-container-image-minimal-base-with-distroless/SKILL.md

SKILL.md (verbatim)

name: implementing-container-image-minimal-base-with-distroless
description: >-
  Reduces container attack surface by building application images on Google distroless base
  images that ship only the application runtime - no shell, package manager, or OS utilities -
  using multi-stage build patterns plus debugging and scanning techniques adapted to
  distroless. Use when hardening container images, cutting attack surface in a container
  architecture, or answering an assessment finding about bloated base images. Keywords:
  distroless, multi-stage build, no shell, nonroot tag, debug image, scratch, attack surface.
  Do not use for scanning an image for known CVEs - use scanning-docker-images-with-trivy.
domain: cybersecurity
subdomain: container-security
tags:
- distroless
- container-images
- minimal-base
- attack-surface
- docker
- security-hardening
- supply-chain
- kubernetes
version: '1.0'
author: mahipal
license: Apache-2.0
nist_csf:
- PR.PS-01
- PR.IR-01
- ID.AM-08
- DE.CM-01
mitre_attack:
- T1610
- T1611
- T1609
- T1525
- T1195

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

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

Image	Use Case	Size
gcr.io/distroless/static-debian12	Statically compiled binaries (Go, Rust)	~2MB
gcr.io/distroless/base-debian12	Dynamically linked binaries needing glibc	~20MB
gcr.io/distroless/cc-debian12	C/C++ applications needing libstdc++	~25MB
gcr.io/distroless/java21-debian12	Java 21 applications	~220MB
gcr.io/distroless/python3-debian12	Python 3 applications	~50MB
gcr.io/distroless/nodejs22-debian12	Node.js 22 applications	~130MB

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

Component	Ubuntu	Alpine	Distroless
Shell (bash/sh)	Yes	Yes	No
Package manager	apt	apk	No
coreutils	Full	BusyBox	No
curl/wget	Yes	Yes	No
User management	Yes	Yes	No
Known CVEs (typical)	50-200+	5-20	0-5
Image size (base)	~77MB	~7MB	~2-20MB

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

Other files in this skill

• LICENSE
• assets/template.md
• references/api-reference.md
• references/standards.md
• references/workflows.md
• scripts/agent.py
• scripts/process.py

assets/template.md (verbatim)

Distroless Migration Assessment Template

Application Information

Field	Value
Application Name
Current Base Image
Runtime
Target Distroless Image

Migration Checklist

• Multi-stage Dockerfile created
• Application tested with distroless base
• Image scanned for vulnerabilities (before/after comparison)
• Non-root user configured
• Debug procedures documented
• CI/CD pipeline updated

Vulnerability Comparison

Metric	Before	After
Image Size
Critical CVEs
High CVEs
Total CVEs

Sign-Off

Role	Name	Date
Developer
Security Engineer

references/api-reference.md (verbatim)

API Reference: Distroless Container Image Analysis Agent

Dependencies

Library	Version	Purpose
trivy CLI	>=0.50	Container vulnerability scanning (subprocess)
docker CLI	>=24.0	Image inspection and property checks (subprocess)

CLI Usage

python scripts/agent.py \
  --images gcr.io/distroless/static-debian12 python:3.12-slim \
  --compare python:3.12 gcr.io/distroless/python3-debian12 \
  --output-dir /reports/

Functions

run_trivy_scan(image) -> dict

Runs trivy image --format json --severity CRITICAL,HIGH,MEDIUM.

get_image_size(image) -> int

Runs docker inspect --format {{.Size}} for byte count.

count_vulns_by_severity(scan_data) -> dict

Parses Trivy JSON Results for CRITICAL/HIGH/MEDIUM/LOW counts.

compare_images(base_image, distroless_image) -> dict

Scans both images, computes size and vulnerability reduction percentages.

check_distroless_properties(image) -> dict

Tests for shell access and package manager presence via docker run.

generate_report(images, distroless_pairs) -> dict

Full analysis with individual scans, comparisons, and summary.

Distroless Properties Checked

Property	Check Method
Shell access	docker run --entrypoint "" image sh -c "echo"
Package manager	docker run --entrypoint "" image which apt/apk/yum

Output Schema

{
  "summary": {"images_scanned": 4, "minimal_images": 2},
  "comparisons": [{"size_reduction_pct": 82.3, "vuln_reduction_pct": 95.0}],
  "image_scans": [{"image": "gcr.io/distroless/static", "is_minimal": true}]
}

references/standards.md (verbatim)

Standards - Distroless Container Images

NIST SP 800-190

• Section 3.1.1: Minimize image content to reduce attack surface
• Section 4.1.1: Use minimal base images for container builds

CIS Docker Benchmark v1.6

• 4.1: Ensure a user for the container has been created
• 4.2: Ensure containers use trusted base images
• 4.6: Ensure HEALTHCHECK instructions have been added
• 4.9: Ensure COPY is used instead of ADD

OWASP Docker Security

• D2: Patch Management Strategies (fewer packages = fewer patches)
• D3: Network Segmentation and Firewalling
• D4: Secure Defaults and Hardening (no shell = hardened by default)

references/workflows.md (verbatim)

Workflows - Distroless Container Images

Migration Workflow

1. Identify current base image and its package footprint
2. Select appropriate distroless variant for your runtime
3. Create multi-stage Dockerfile with build and runtime stages
4. Test application functionality with distroless base
5. Scan both old and new images to compare CVE counts
6. Update debugging procedures (ephemeral containers, debug variants)
7. Deploy to staging and validate
8. Roll out to production

Image Build Pipeline

1. Build application in builder stage (full SDK image)
2. Copy only runtime artifacts to distroless stage
3. Set non-root user via :nonroot tag
4. Scan final image with Trivy/Grype
5. Sign image with cosign
6. Push to registry with digest pinning

Back to mukul975/Anthropic-Cybersecurity-Skills (817 security skills) or Agent skills.