🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Docker Security Guide

This skill provides comprehensive security guidelines for Docker across all platforms, covering threats, mitigations, and compliance requirements.

Security Principles

Defense in Depth

Apply security at multiple layers:

1. Image security: Minimal, scanned, signed images
2. Build security: Secure build process, no secrets in layers
3. Runtime security: Restricted capabilities, resource limits
4. Network security: Isolation, least privilege
5. Host security: Hardened host OS, updated Docker daemon
6. Orchestration security: Secure configuration, RBAC
7. Monitoring: Detection, logging, alerting

Least Privilege

Grant only the minimum permissions necessary:

• Non-root users
• Dropped capabilities
• Read-only filesystems
• Minimal network exposure
• Restricted syscalls (seccomp)
• Limited resources

Image Security

Base Image Selection

Threat: Vulnerable or malicious base images

Mitigation:

# Use official images only
FROM node:20.11.0-alpine3.19  # Official, specific version

# NOT
FROM randomuser/node  # Unverified source
FROM node:latest      # Unpredictable, can break

Verification:

# Verify image source
docker image inspect node:20-alpine | grep -A 5 "Author"

# Enable Docker Content Trust (image signing)
export DOCKER_CONTENT_TRUST=1
docker pull node:20-alpine

Minimal Images

Threat: Larger attack surface, more vulnerabilities

Mitigation:

# Prefer minimal distributions
FROM alpine:3.19           # ~7MB
FROM gcr.io/distroless/static  # ~2MB
FROM scratch               # 0MB (for static binaries)

# vs
FROM ubuntu:22.04          # ~77MB with more packages

Benefits:

• Fewer packages = fewer vulnerabilities
• Smaller attack surface
• Faster downloads and starts
• Less disk space

Micro-Distros for Security-Critical Applications (2025)

Wolfi/Chainguard Images:

• Zero-CVE goal, SBOM included by default
• Nightly security patches, signed with provenance
• Available for: Node, Python, Go, Java, .NET, etc.

Usage:

# Development stage (includes build tools)
FROM cgr.dev/chainguard/node:latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Production stage (minimal, zero-CVE goal)
FROM cgr.dev/chainguard/node:latest
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER node
ENTRYPOINT ["node", "server.js"]

When to use: Security-critical apps, compliance requirements (SOC2, HIPAA, PCI-DSS), zero-trust environments, supply chain security emphasis.

See docker-best-practices skill for full image comparison table.

Vulnerability Scanning

Tools:

• Docker Scout (built-in)
• Trivy
• Grype
• Snyk
• Clair

Process:

# Scan with Docker Scout
docker scout cves IMAGE_NAME
docker scout recommendations IMAGE_NAME

# Scan with Trivy
trivy image IMAGE_NAME
trivy image --severity HIGH,CRITICAL IMAGE_NAME

# Scan Dockerfile
trivy config Dockerfile

# Scan for secrets
trivy fs --scanners secret .

CI/CD Integration:

# GitHub Actions example
- name: Scan image
  run: |
    docker scout cves my-image:${{ github.sha }}
    trivy image --exit-code 1 --severity CRITICAL my-image:${{ github.sha }}

Multi-Stage Builds for Security

Threat: Build tools and secrets in final image

Mitigation:

# Build stage with build tools
FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN go build -o app

# Final stage - minimal, no build tools
FROM gcr.io/distroless/base-debian11
COPY --from=builder /app/app /
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Benefits:

• No compiler/build tools in production image
• Secrets used in build don't persist
• Smaller, more secure final image

Build-Time Security

Secrets Management

NEVER:

# BAD - Secret in layer history
ENV API_KEY=abc123
RUN git clone https://user:[email protected]/repo.git
COPY .env /app/.env

DO:

# Use BuildKit secrets
# syntax=docker/dockerfile:1

FROM alpine
RUN --mount=type=secret,id=github_token \
    git clone https://$(cat /run/secrets/github_token)@github.com/repo.git

# Build with secret (not in image)
docker build --secret id=github_token,src=./token.txt .

BuildKit Frontend Security (2025)

Threat: Malicious or compromised BuildKit frontends can execute arbitrary code during build

🚨 2025 CRITICAL WARNING: BuildKit supports custom frontends (parsers) via # syntax= directive. Untrusted frontends have FULL BUILD-TIME code execution and can:

• Steal secrets from build context
• Modify build outputs
• Exfiltrate data
• Compromise the build environment

Risk Example:

# 🔴 DANGER - Untrusted frontend (code execution risk!)
# syntax=docker/dockerfile:1@sha256:abc123...untrusted

FROM alpine
RUN echo "This frontend could do anything during build"

Mitigation:

1. Only use official Docker frontends:

# ✅ Safe - Official Docker frontend
# syntax=docker/dockerfile:1

# ✅ Safe - Specific version
# syntax=docker/dockerfile:1.5

# ✅ Safe - Pinned with digest (verify from docker.com)
# syntax=docker/dockerfile:1@sha256:ac85f380a63b13dfcefa89046420e1781752bab202122f8f50032edf31be0021

2. Verify frontend sources:

• Use ONLY docker/dockerfile:* frontends
• Pin to specific versions with SHA256 digest
• Verify digests from official Docker documentation
• Never use third-party frontends without thorough vetting

3. Audit all Dockerfiles for unsafe syntax directives:

# Check all Dockerfiles for potentially malicious syntax directives
grep -r "^# syntax=" . --include="Dockerfile*"

# Verify all frontends are official Docker images
grep -r "^# syntax=" . --include="Dockerfile*" | grep -v "docker/dockerfile"

4. BuildKit security configuration (defense in depth):

# Restrict frontend sources in BuildKit config
# /etc/buildkit/buildkitd.toml
[frontend."dockerfile.v0"]
  # Only allow official Docker frontends
  allowedImages = ["docker.io/docker/dockerfile:*"]

Supply Chain Protection:

• Treat custom frontends as HIGH RISK code execution vectors
• Review ALL # syntax= directives in Dockerfiles before builds
• Use content trust for frontend images
• Monitor for frontend vulnerabilities
• Include frontend verification in CI/CD security gates

SBOM (Software Bill of Materials) Generation (2025)

Critical 2025 Requirement: Document origin and history of all components for supply chain transparency and compliance.

Why SBOM is Mandatory:

• Supply chain security visibility
• Vulnerability tracking and response
• Compliance requirements (Executive Order 14028, etc.)
• License compliance
• Incident response readiness

Generate SBOM with Docker Scout:

# Generate SBOM for image
docker scout sbom IMAGE_NAME

# Export SBOM in different formats
docker scout sbom --format spdx IMAGE_NAME > sbom.spdx.json
docker scout sbom --format cyclonedx IMAGE_NAME > sbom.cyclonedx.json

# Include SBOM attestation during build
# ⚠️ WARNING: BuildKit attestations are NOT cryptographically signed!
docker buildx build \
  --sbom=true \
  --provenance=true \
  --tag my-image:latest \
  .

# View SBOM attestations (unsigned metadata only)
docker buildx imagetools inspect my-image:latest --format "{{ json .SBOM }}"

🚨 CRITICAL SECURITY LIMITATION: BuildKit attestations (--sbom=true, --provenance=true) are NOT cryptographically signed. This means:

• Anyone with push access can create tampered attestations
• SBOMs can be incomplete or falsified
• Provenance data cannot be trusted without external verification
• For production: Use external signing tools (cosign, Notary) and Syft for SBOM generation

Generate SBOM with Syft:

# Install Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh

# Generate SBOM from image
syft my-image:latest

# Generate in specific format
syft my-image:latest -o spdx-json > sbom.spdx.json
syft my-image:latest -o cyclonedx-json > sbom.cyclonedx.json

# Generate from Dockerfile
syft dir:. -o spdx-json > sbom.spdx.json

SBOM in CI/CD Pipeline: