🚨 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:

• Image security: Minimal, scanned, signed images

• Build security: Secure build process, no secrets in layers

• Runtime security: Restricted capabilities, resource limits

• Network security: Isolation, least privilege

• Host security: Hardened host OS, updated Docker daemon

• Orchestration security: Secure configuration, RBAC

• 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:password@github.com/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:

• 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

• 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

• 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"

• 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:

GitHub Actions example

name: Build with SBOM

jobs: build: steps: - name: Build image with SBOM run: | docker buildx build
--sbom=true
--provenance=true
--tag my-image:${{ github.sha }}
--push
.

  - name: Generate SBOM with Syft
    run: |
      syft my-image:${{ github.sha }} -o spdx-json > sbom.json

  - name: Upload SBOM artifact
    uses: actions/upload-artifact@v3
    with:
      name: sbom
      path: sbom.json

  - name: Scan SBOM for vulnerabilities
    run: |
      grype sbom:sbom.json --fail-on high

SBOM Best Practices:

Generate for every image:

• Production images: mandatory

• Development images: recommended

• Base images: critical

Store SBOMs with provenance:

• Version control alongside Dockerfile

• Artifact registry with image

• Dedicated SBOM repository

Automate SBOM generation:

• Integrate into CI/CD pipeline

• Generate on every build

• Fail builds if SBOM generation fails

Use SBOM for vulnerability management:

Scan SBOM instead of image (faster)

grype sbom:sbom.json trivy sbom sbom.json

Compare SBOMs between versions

diff <(syft old-image:1.0 -o json) <(syft new-image:2.0 -o json)

• SBOM formats:

• SPDX: Industry standard, ISO/IEC 5962:2021

• CycloneDX: OWASP standard, security-focused

• Choose based on compliance requirements

Chainguard Images with Built-in SBOM:

Chainguard images include SBOM attestation by default

docker buildx imagetools inspect cgr.dev/chainguard/node:latest

Extract SBOM

cosign download sbom cgr.dev/chainguard/node:latest > chainguard-node-sbom.json

Or use multi-stage and don't include secrets:

FROM node AS builder ARG NPM_TOKEN RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc &&
npm install &&
rm .npmrc # Still in layer history!

Better - secret only in build stage

FROM node AS dependencies RUN --mount=type=secret,id=npmrc,target=/root/.npmrc
npm install

FROM node AS runtime COPY --from=dependencies /app/node_modules ./node_modules

No .npmrc in final image

Secure Build Context

Threat: Sensitive files included in build context

Mitigation: Create comprehensive .dockerignore :

Secrets

.env .env.local *.key *.pem credentials.json secrets/

Version control

.git .gitignore

Cloud credentials

.aws/ .gcloud/

Private data

database.sql backups/

SSH keys

.ssh/ id_rsa id_rsa.pub

Sensitive logs

*.log logs/

Image Signing

Enable Docker Content Trust:

Enable image signing

export DOCKER_CONTENT_TRUST=1

Set up keys

docker trust key generate my-key docker trust signer add --key my-key.pub my-name my-image

Push signed image

docker push my-image:tag

Pull only signed images

docker pull my-image:tag # Fails if not signed

Runtime Security

User Privileges

Threat: Container escape via root

Mitigation:

Create and use non-root user

FROM node:20-alpine RUN addgroup -g 1001 appuser &&
adduser -S appuser -u 1001 -G appuser USER appuser WORKDIR /home/appuser/app COPY --chown=appuser:appuser . . CMD ["node", "server.js"]

Verification:

Check user in running container

docker exec container-name whoami # Should not be root docker exec container-name id # Check UID/GID

Capabilities

Threat: Excessive kernel capabilities

Default Docker capabilities:

• CHOWN, DAC_OVERRIDE, FOWNER, FSETID

• KILL, SETGID, SETUID, SETPCAP

• NET_BIND_SERVICE, NET_RAW

• SYS_CHROOT, MKNOD, AUDIT_WRITE, SETFCAP

Mitigation:

Drop all, add only needed

docker run
--cap-drop=ALL
--cap-add=NET_BIND_SERVICE
my-image

In docker-compose.yml:

services: app: cap_drop: - ALL cap_add: - NET_BIND_SERVICE

Common needed capabilities:

• NET_BIND_SERVICE : Bind to ports < 1024

• NET_ADMIN : Network configuration

• SYS_TIME : Set system time

Read-Only Filesystem

Threat: Container modification, malware persistence

Mitigation:

docker run
--read-only
--tmpfs /tmp:noexec,nosuid,size=64M
--tmpfs /var/run:noexec,nosuid,size=64M
my-image

In Compose:

services: app: read_only: true tmpfs: - /tmp:noexec,nosuid,size=64M - /var/run:noexec,nosuid,size=64M

Security Options

no-new-privileges:

docker run --security-opt="no-new-privileges:true" my-image

Prevents privilege escalation via setuid/setgid binaries.

AppArmor (Linux):

docker run --security-opt="apparmor=docker-default" my-image

SELinux (Linux):

docker run --security-opt="label=type:container_runtime_t" my-image

Seccomp (syscall filtering):

Use default profile

docker run --security-opt="seccomp=default" my-image

Or custom profile

docker run --security-opt="seccomp=./seccomp-profile.json" my-image

Resource Limits

Threat: DoS via resource exhaustion

Mitigation:

docker run
--memory="512m"
--memory-swap="512m" \ # Disable swap --cpus="1.0"
--pids-limit=100
--ulimit nofile=1024:1024
my-image

In Compose:

services: app: deploy: resources: limits: cpus: '1.0' memory: 512M pids: 100 reservations: cpus: '0.5' memory: 256M ulimits: nofile: soft: 1024 hard: 1024

Comprehensive Secure Run Command

docker run
--name secure-app
--detach
--restart unless-stopped
--user 1000:1000
--cap-drop=ALL
--cap-add=NET_BIND_SERVICE
--read-only
--tmpfs /tmp:noexec,nosuid,size=64M
--security-opt="no-new-privileges:true"
--security-opt="seccomp=default"
--memory="512m"
--cpus="1.0"
--pids-limit=100
--network=isolated-network
--publish 127.0.0.1:8080:8080
--volume secure-data:/data:ro
--health-cmd="curl -f http://localhost/health || exit 1"
--health-interval=30s
my-secure-image:1.2.3

Network Security

Network Isolation

Threat: Lateral movement between containers

Mitigation:

networks: frontend: driver: bridge backend: driver: bridge internal: true # No external access

services: web: networks: - frontend

api: networks: - frontend - backend

database: networks: - backend # Isolated from frontend

Port Exposure

Threat: Unnecessary network exposure

Mitigation:

Bind to localhost only

docker run -p 127.0.0.1:8080:8080 my-image

NOT (binds to all interfaces)

docker run -p 8080:8080 my-image

In Compose:

services: app: ports: - "127.0.0.1:8080:8080" # Localhost only

Inter-Container Communication

Disable default inter-container communication

/etc/docker/daemon.json

{ "icc": false }

Then explicitly allow via networks:

services: app1: networks: - app-network app2: networks: - app-network # Can communicate with app1

networks: app-network: driver: bridge

Secrets Management

Docker Secrets (Swarm Mode)

Create secret

echo "mypassword" | docker secret create db_password -

Use in service

docker service create
--name my-service
--secret db_password
my-image

Access in container at /run/secrets/db_password

In stack file:

version: '3.8'

services: app: image: my-image secrets: - db_password

secrets: db_password: external: true

Secrets Best Practices

• Never in environment variables (visible in docker inspect )

• Never in images (in layer history)

• Never in version control (Git history)

• Mount as files with restricted permissions

• Use secret management systems (Vault, AWS Secrets Manager, etc.)

• Rotate regularly

Alternative: Mounted secrets:

docker run -v /secure/secrets:/run/secrets:ro my-image

Compliance & Benchmarking

CIS Docker Benchmark

Automated checking:

Clone docker-bench-security

git clone https://github.com/docker/docker-bench-security.git cd docker-bench-security sudo sh docker-bench-security.sh

Or run as container

docker run --rm --net host --pid host --userns host
--cap-add audit_control
-v /var/lib:/var/lib:ro
-v /var/run/docker.sock:/var/run/docker.sock:ro
-v /usr/lib/systemd:/usr/lib/systemd:ro
-v /etc:/etc:ro
docker/docker-bench-security

Key CIS Recommendations

Host Configuration

• Keep Docker up to date

• Restrict network traffic between containers

• Set logging level to 'info'

• Enable Docker Content Trust

Docker Daemon

• Use TLS for Docker daemon socket

• Don't expose daemon on TCP without TLS

• Enable user namespace support

Docker Files

• Verify Docker files ownership and permissions

• Audit Docker files and directories

Container Images

• Create user for container

• Use trusted base images

• Don't install unnecessary packages

Container Runtime

• Run containers with limited privileges

• Set resource limits

• Don't share host network namespace

Monitoring & Detection

Logging

services: app: logging: driver: "json-file" options: max-size: "10m" max-file: "3" labels: "service,env" env: "ENV,VERSION"

Centralized logging:

services: app: logging: driver: "syslog" options: syslog-address: "tcp://log-server:514" tag: "{{.Name}}/{{.ID}}"

Runtime Monitoring

Tools:

• Falco: Runtime security monitoring

• Sysdig: Container visibility

• Prometheus + cAdvisor: Metrics

• Docker events: Real-time events

Monitor for:

• Unexpected processes

• File modifications

• Network connections

• Resource spikes

• Failed authentication

• Privilege escalation attempts

Monitor Docker events

docker events --filter 'type=container' --filter 'event=start'

Watch specific container

docker events --filter "container=my-container"

Runtime security with Falco

docker run --rm -it
--privileged
-v /var/run/docker.sock:/host/var/run/docker.sock
-v /dev:/host/dev
-v /proc:/host/proc:ro
falcosecurity/falco

Platform-Specific Security

Linux

User namespace remapping:

// /etc/docker/daemon.json { "userns-remap": "default" }

Benefits: Root in container → unprivileged on host

SELinux:

Enable SELinux for Docker

setenforce 1

Run with SELinux labels

docker run --security-opt label=type:svirt_sandbox_file_t my-image

Volumes with SELinux

docker run -v /host/path:/container/path:z my-image

AppArmor:

Check AppArmor status

aa-status

Run with AppArmor profile

docker run --security-opt apparmor=docker-default my-image

Windows

Hyper-V isolation:

More isolated than process isolation

docker run --isolation=hyperv my-image

Windows Defender:

• Ensure real-time protection enabled

• Configure exclusions carefully

• Scan images regularly

macOS

Docker Desktop security:

• Keep Docker Desktop updated

• Enable "Use gRPC FUSE for file sharing"

• Limit file sharing to necessary paths

• Review resource allocation

Security Checklist

Image:

• Based on official, minimal image

• Specific version tag (not latest )

• Scanned for vulnerabilities

• No secrets in layers

• Runs as non-root user

• Signed (Content Trust)

Build:

• .dockerignore configured

• Multi-stage build (if applicable)

• Build secrets handled properly

• Build from trusted sources only

Runtime:

• Non-root user

• Capabilities dropped

• Read-only filesystem (where possible)

• Security options set

• Resource limits configured

• Isolated network

• Minimal port exposure

• Secrets mounted securely

Operations:

• CIS benchmark compliance

• Logging configured

• Monitoring in place

• Regular vulnerability scans

• Incident response plan

• Regular updates

• Audit logs enabled

Common Security Mistakes

❌ NEVER:

• Run as root

• Use --privileged

• Mount Docker socket (/var/run/docker.sock )

• Hardcode secrets

• Use latest tag

• Skip vulnerability scanning

• Expose unnecessary ports

• Disable security features

• Ignore security updates

• Trust unverified images

✅ ALWAYS:

• Run as non-root

• Drop capabilities

• Scan for vulnerabilities

• Use secrets management

• Tag with specific versions

• Enable security options

• Apply least privilege

• Keep systems updated

• Monitor runtime behavior

• Use official images

This security guide represents current best practices. Security threats evolve constantly—always check the latest Docker security documentation and CVE databases.