npx skills add mukul975/Anthropic-Cybersecurity-SkillsMITRE ATT&CK
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,curlfor reconnaissance - Minimal CVEs: Fewer packages means fewer vulnerabilities to patch
- Non-root by default:
:nonroottag 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/shEphemeral Debug Containers (Kubernetes 1.25+)
# Attach a debug container with full tooling
kubectl debug -it pod-name --image=busybox:1.36 --target=app-containerCrane/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-debian12Image 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
References and resources
Everything below is rendered for inspection. Script files are read-only and never run.
References 3
api-reference.md1.6 KB
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}]
}standards.md0.6 KB
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)
workflows.md0.7 KB
Workflows - Distroless Container Images
Migration Workflow
- Identify current base image and its package footprint
- Select appropriate distroless variant for your runtime
- Create multi-stage Dockerfile with build and runtime stages
- Test application functionality with distroless base
- Scan both old and new images to compare CVE counts
- Update debugging procedures (ephemeral containers, debug variants)
- Deploy to staging and validate
- Roll out to production
Image Build Pipeline
- Build application in builder stage (full SDK image)
- Copy only runtime artifacts to distroless stage
- Set non-root user via
:nonroottag - Scan final image with Trivy/Grype
- Sign image with cosign
- Push to registry with digest pinning
Scripts 2
agent.py5.8 KB
#!/usr/bin/env python3
"""Distroless container image analysis agent using Trivy for comparing image security posture."""
import argparse
import json
import logging
import os
import subprocess
from datetime import datetime
from typing import Dict, List
logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
logger = logging.getLogger(__name__)
def run_trivy_scan(image: str) -> dict:
"""Scan image with Trivy and return JSON results."""
cmd = ["trivy", "image", "--format", "json", "--severity", "CRITICAL,HIGH,MEDIUM", image]
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
if result.stdout:
return json.loads(result.stdout)
except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError) as exc:
logger.error("Trivy scan failed for %s: %s", image, exc)
return {}
def get_image_size(image: str) -> int:
"""Get image size using docker inspect."""
try:
result = subprocess.run(
["docker", "inspect", "--format", "{{.Size}}", image],
capture_output=True, text=True, timeout=30)
return int(result.stdout.strip()) if result.stdout.strip() else 0
except (FileNotFoundError, ValueError):
return 0
def count_packages(scan_data: dict) -> int:
"""Count total packages found in Trivy scan."""
count = 0
for result in scan_data.get("Results", []):
count += len(result.get("Vulnerabilities", []))
return count
def count_vulns_by_severity(scan_data: dict) -> dict:
"""Count vulnerabilities by severity from Trivy results."""
counts = {"CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0}
for result in scan_data.get("Results", []):
for vuln in result.get("Vulnerabilities", []):
sev = vuln.get("Severity", "").upper()
if sev in counts:
counts[sev] += 1
counts["total"] = sum(counts.values())
return counts
def compare_images(base_image: str, distroless_image: str) -> dict:
"""Compare a standard base image against its distroless equivalent."""
base_scan = run_trivy_scan(base_image)
distroless_scan = run_trivy_scan(distroless_image)
base_vulns = count_vulns_by_severity(base_scan)
distroless_vulns = count_vulns_by_severity(distroless_scan)
base_size = get_image_size(base_image)
distroless_size = get_image_size(distroless_image)
size_reduction = ((base_size - distroless_size) / base_size * 100) if base_size else 0
vuln_reduction = ((base_vulns["total"] - distroless_vulns["total"]) / base_vulns["total"] * 100) if base_vulns["total"] else 0
return {
"base_image": {"image": base_image, "size_bytes": base_size, "vulnerabilities": base_vulns},
"distroless_image": {"image": distroless_image, "size_bytes": distroless_size, "vulnerabilities": distroless_vulns},
"size_reduction_pct": round(size_reduction, 1),
"vuln_reduction_pct": round(vuln_reduction, 1),
}
def check_distroless_properties(image: str) -> dict:
"""Check if an image exhibits distroless properties (no shell, no package manager)."""
checks = {"has_shell": False, "has_package_manager": False, "has_user": False}
try:
result = subprocess.run(
["docker", "run", "--rm", "--entrypoint", "", image, "sh", "-c", "echo shell_exists"],
capture_output=True, text=True, timeout=10)
checks["has_shell"] = "shell_exists" in result.stdout
except (FileNotFoundError, subprocess.TimeoutExpired):
pass
try:
for pm in ["apt", "apk", "yum", "dnf"]:
result = subprocess.run(
["docker", "run", "--rm", "--entrypoint", "", image, "which", pm],
capture_output=True, text=True, timeout=10)
if result.returncode == 0:
checks["has_package_manager"] = True
break
except (FileNotFoundError, subprocess.TimeoutExpired):
pass
return checks
def generate_report(images: List[str], distroless_pairs: Dict[str, str] = None) -> dict:
"""Generate distroless adoption report."""
report = {"analysis_date": datetime.utcnow().isoformat(), "image_scans": [], "comparisons": []}
for image in images:
scan = run_trivy_scan(image)
vulns = count_vulns_by_severity(scan)
props = check_distroless_properties(image)
report["image_scans"].append({
"image": image, "vulnerabilities": vulns, "properties": props,
"is_minimal": not props["has_shell"] and not props["has_package_manager"],
})
if distroless_pairs:
for base, distroless in distroless_pairs.items():
report["comparisons"].append(compare_images(base, distroless))
report["summary"] = {
"images_scanned": len(images),
"minimal_images": sum(1 for s in report["image_scans"] if s["is_minimal"]),
}
return report
def main():
parser = argparse.ArgumentParser(description="Distroless Container Image Analysis Agent")
parser.add_argument("--images", nargs="+", required=True, help="Images to analyze")
parser.add_argument("--compare", nargs=2, action="append", metavar=("BASE", "DISTROLESS"),
help="Compare base vs distroless pairs")
parser.add_argument("--output-dir", default=".")
parser.add_argument("--output", default="distroless_report.json")
args = parser.parse_args()
os.makedirs(args.output_dir, exist_ok=True)
pairs = {c[0]: c[1] for c in args.compare} if args.compare else None
report = generate_report(args.images, pairs)
out_path = os.path.join(args.output_dir, args.output)
with open(out_path, "w") as f:
json.dump(report, f, indent=2)
logger.info("Report saved to %s", out_path)
print(json.dumps(report["summary"], indent=2))
if __name__ == "__main__":
main()
process.py6.8 KB
#!/usr/bin/env python3
"""
Container Image Base Analysis Tool
Analyzes container images to identify non-minimal base images and
recommends distroless alternatives based on the application runtime.
"""
import json
import subprocess
import sys
import argparse
from datetime import datetime
DISTROLESS_RECOMMENDATIONS = {
"golang": "gcr.io/distroless/static-debian12:nonroot",
"go": "gcr.io/distroless/static-debian12:nonroot",
"rust": "gcr.io/distroless/static-debian12:nonroot",
"java": "gcr.io/distroless/java21-debian12:nonroot",
"openjdk": "gcr.io/distroless/java21-debian12:nonroot",
"python": "gcr.io/distroless/python3-debian12:nonroot",
"node": "gcr.io/distroless/nodejs22-debian12:nonroot",
"nodejs": "gcr.io/distroless/nodejs22-debian12:nonroot",
"dotnet": "mcr.microsoft.com/dotnet/runtime-deps:8.0-noble-chiseled",
"ruby": "gcr.io/distroless/base-debian12:nonroot",
"c": "gcr.io/distroless/cc-debian12:nonroot",
"cpp": "gcr.io/distroless/cc-debian12:nonroot",
}
BLOATED_BASES = {"ubuntu", "debian", "centos", "fedora", "amazonlinux", "oraclelinux"}
def run_command(cmd: list[str], timeout: int = 60) -> str:
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
return result.stdout.strip()
except (subprocess.TimeoutExpired, FileNotFoundError):
return ""
def get_image_info(image: str) -> dict:
"""Get image metadata using docker inspect or crane."""
output = run_command(["docker", "inspect", image])
if output:
try:
data = json.loads(output)
if data:
return data[0]
except json.JSONDecodeError:
pass
return {}
def analyze_image_layers(image: str) -> dict:
"""Analyze image layers and size."""
info = get_image_info(image)
if not info:
return {"error": f"Cannot inspect image: {image}"}
return {
"image": image,
"size_bytes": info.get("Size", 0),
"size_mb": round(info.get("Size", 0) / 1024 / 1024, 1),
"layers": len(info.get("RootFS", {}).get("Layers", [])),
"os": info.get("Os", ""),
"architecture": info.get("Architecture", ""),
"user": info.get("Config", {}).get("User", "root"),
"entrypoint": info.get("Config", {}).get("Entrypoint", []),
"cmd": info.get("Config", {}).get("Cmd", []),
"env": info.get("Config", {}).get("Env", []),
"has_shell": check_shell_exists(image),
}
def check_shell_exists(image: str) -> bool:
"""Check if the image contains a shell."""
for shell in ["/bin/sh", "/bin/bash", "/bin/dash"]:
output = run_command(["docker", "run", "--rm", "--entrypoint", "",
image, "test", "-f", shell])
# If command succeeds, shell exists
output = run_command(["docker", "run", "--rm", "--entrypoint", "",
image, "ls", "/bin/sh"], timeout=10)
return bool(output)
def scan_vulnerabilities(image: str) -> dict:
"""Scan image for vulnerabilities using trivy."""
output = run_command(["trivy", "image", "--format", "json", "--quiet", image], timeout=120)
if not output:
return {"total": -1, "critical": -1, "high": -1, "medium": -1, "low": -1}
try:
data = json.loads(output)
counts = {"total": 0, "critical": 0, "high": 0, "medium": 0, "low": 0}
for result in data.get("Results", []):
for vuln in result.get("Vulnerabilities", []):
counts["total"] += 1
sev = vuln.get("Severity", "").lower()
if sev in counts:
counts[sev] += 1
return counts
except json.JSONDecodeError:
return {"total": -1, "critical": -1, "high": -1, "medium": -1, "low": -1}
def recommend_distroless(image: str) -> str:
"""Recommend a distroless base image based on current image."""
image_lower = image.lower()
for runtime, distroless in DISTROLESS_RECOMMENDATIONS.items():
if runtime in image_lower:
return distroless
return "gcr.io/distroless/base-debian12:nonroot"
def analyze_kubernetes_images(namespace: str = "") -> list[dict]:
"""Analyze all container images in a Kubernetes cluster."""
cmd = ["kubectl", "get", "pods", "-o", "json"]
if namespace:
cmd.extend(["-n", namespace])
else:
cmd.append("--all-namespaces")
output = run_command(cmd)
if not output:
return []
images = set()
try:
data = json.loads(output)
for pod in data.get("items", []):
for cs in pod.get("status", {}).get("containerStatuses", []):
images.add(cs.get("image", ""))
except json.JSONDecodeError:
return []
results = []
for image in sorted(images):
if not image:
continue
is_distroless = "distroless" in image or "chiseled" in image
is_bloated = any(base in image.lower() for base in BLOATED_BASES)
results.append({
"image": image,
"is_distroless": is_distroless,
"is_bloated_base": is_bloated,
"recommendation": "Already minimal" if is_distroless else recommend_distroless(image)
})
return results
def generate_report(results: list[dict], output_format: str = "text") -> str:
if output_format == "json":
return json.dumps({"timestamp": datetime.utcnow().isoformat(),
"results": results}, indent=2)
lines = ["=" * 70, "CONTAINER IMAGE BASE ANALYSIS REPORT",
f"Generated: {datetime.utcnow().isoformat()}", "=" * 70]
minimal = [r for r in results if r.get("is_distroless")]
bloated = [r for r in results if r.get("is_bloated_base")]
lines.append(f"\nImages Analyzed: {len(results)}")
lines.append(f"Minimal/Distroless: {len(minimal)}")
lines.append(f"Bloated Base: {len(bloated)}")
if bloated:
lines.append("\n## Images Needing Migration")
for r in bloated:
lines.append(f" {r['image']}")
lines.append(f" Recommended: {r['recommendation']}")
lines.append("\n" + "=" * 70)
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Container Image Base Analyzer")
parser.add_argument("--image", help="Analyze a specific image")
parser.add_argument("--namespace", default="", help="K8s namespace to scan")
parser.add_argument("--format", choices=["text", "json"], default="text")
args = parser.parse_args()
if args.image:
info = analyze_image_layers(args.image)
info["recommendation"] = recommend_distroless(args.image)
print(generate_report([info], args.format))
else:
results = analyze_kubernetes_images(args.namespace)
print(generate_report(results, args.format))
if __name__ == "__main__":
main()