authegg/docker-security-hardening

Docker Security Hardening

Enforce Docker and container security best practices based on Bret Fisher's container security recommendations, the OWASP Docker Security Cheat Sheet, and CIS Docker Benchmark.

When to Use

• Creating or editing any Dockerfile
• Writing or modifying docker-compose.yml / compose.yaml
• Configuring Kubernetes deployments with container specs
• Setting up CI/CD pipelines that build Docker images
• Reviewing container configurations before production deployment
• When the user mentions "container security", "Docker hardening", "image scanning", or "production readiness"

Security Checklist — Apply to Every Docker File

Dockerfile Requirements (Check All)

1. Non-root USER directive: Every Dockerfile MUST include USER <non-root> before the final CMD/ENTRYPOINT. Use existing users from official images (e.g., node, postgres) or create a dedicated one:

   RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
   USER appuser
   

2. Slim base images only: NEVER use full base images in production (e.g., node:20, python:3.12). Always use -slim, -alpine, or distroless:

   # ❌ BAD: Full image with unnecessary packages
   FROM node:20
   
   # ✅ GOOD: Minimal attack surface
   FROM node:20-slim
   FROM gcr.io/distroless/nodejs
   FROM cgr.dev/chainguard/node
   

3. Multi-stage builds: Separate build and runtime stages. Dev dependencies, build tools, and test frameworks must NOT appear in the final stage:

   FROM node:20-slim AS build
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci
   COPY . .
   RUN npm run build
   
   FROM node:20-slim AS production
   WORKDIR /app
   COPY --from=build /app/dist ./dist
   COPY --from=build /app/node_modules ./node_modules
   USER node
   CMD ["node", "dist/index.js"]
   

4. No secrets in images: NEVER put passwords, API keys, tokens, or private keys in ENV, ARG, or COPY. Use BuildKit secrets or runtime injection:

   # ❌ BAD
   ENV DATABASE_PASSWORD=mysecret
   ARG API_KEY
   
   # ✅ GOOD: BuildKit secret mount
   RUN --mount=type=secret,id=db_pass cat /run/secrets/db_pass
   

5. HEALTHCHECK directive: Include health checks for orchestrator integration:

   HEALTHCHECK --interval=30s --timeout=3s \
     CMD curl -f http://localhost:3000/health || exit 1
   

6. Pin images by digest in production:

   # ❌ BAD: Mutable tag
   FROM node:20-slim
   
   # ✅ GOOD: Immutable digest
   FROM node@sha256:abc123def456...
   

7. COPY over ADD: Prefer COPY; only use ADD for tar extraction.

8. .dockerignore: Must exclude .git, .env, node_modules, *.key, *.pem, test files.

docker-compose / Runtime Requirements

9. Drop all capabilities:

   cap_drop:
     - ALL
   cap_add:
     - NET_BIND_SERVICE  # Only what's needed
   

10. Enable no-new-privileges:

    security_opt:
      - no-new-privileges:true
    

11. Read-only filesystem:

    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid
    

12. Resource limits:

    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
    

13. No Docker socket mounts: NEVER mount /var/run/docker.sock into application containers.

14. No privileged mode: Never use privileged: true.

15. Network isolation: Create separate frontend/backend networks:

    networks:
      frontend:
      backend:
        internal: true
    

CI/CD Requirements

16. Dockerfile linting: Run hadolint Dockerfile in CI.

17. CVE scanning: Fail builds on CRITICAL/HIGH:

    trivy image --severity HIGH,CRITICAL --exit-code 1 <image>
    

18. SBOM generation:

    syft <image> --output cyclonedx-json=sbom.json
    

19. Secret scanning:

    trivy fs --scanners secret .
    

Secure Templates

Complete Secure Node.js Dockerfile

FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force
COPY . .
RUN npm run build

FROM node:20-slim AS production
RUN apt-get update && apt-get upgrade -y && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./
HEALTHCHECK --interval=30s --timeout=3s \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]

Complete Secure docker-compose Service

services:
  app:
    build:
      context: .
      target: production
    user: "1000:1000"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp:noexec,nosuid
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

networks:
  frontend:
  backend:
    internal: true

Severity Classification

When reporting findings, classify as:

• CRITICAL (must block): Running as root + exposed, secrets in image, privileged mode, Docker socket mount
• HIGH (must fix before deploy): No USER directive, full base images in prod, no CVE scanning
• MEDIUM (should fix): No HEALTHCHECK, no resource limits, no .dockerignore
• LOW (best practice): Image not pinned by digest, no SBOM, missing labels

References

For detailed hook scripts, CI pipeline templates, and the complete .dockerignore template, see the references/ and scripts/ directories in this skill.

• references/ci-pipeline-template.md — GitHub Actions security pipeline
• references/dockerignore-template.md — Production .dockerignore
• scripts/dockerfile-security-check.sh — Automated Dockerfile security scanner
• scripts/block-dangerous-docker-commands.sh — Dangerous Docker command blocker