docker.yaml

# Docker Code Review Guidelines
# Comprehensive rules for Docker security, best practices, and resource management

name: Docker Code Review Guidelines
description: Guidelines for reviewing Docker configurations covering security, best practices, networking, and resource management
globs:
  - "**/Dockerfile"
  - "**/Dockerfile.*"
  - "**/*.dockerfile"
  - "**/docker-compose.yaml"
  - "**/docker-compose.yml"
  - "**/docker-compose.*.yaml"
  - "**/docker-compose.*.yml"

areas:
  - name: security
    description: Security rules to prevent container vulnerabilities
    rules:
      - name: use-non-root-user
        description: Run containers as a non-root user using USER directive. Running as root inside containers increases the attack surface if the container is compromised. Create a dedicated user with minimal permissions.
        severity: high

      - name: use-minimal-base-images
        description: Use minimal base images like alpine, distroless, or scratch when possible. Smaller images have fewer vulnerabilities and reduced attack surface. Avoid full OS images like ubuntu or debian unless necessary.
        severity: medium

      - name: no-secrets-in-images
        description: Never embed secrets, API keys, passwords, or certificates directly in Docker images. Use Docker secrets, environment variables at runtime, or external secret management systems. Secrets in images persist in layer history.
        severity: high

      - name: image-signing-verification
        description: Sign Docker images and verify signatures before deployment. Use Docker Content Trust (DCT) or Notary to ensure image integrity and provenance. Enable DOCKER_CONTENT_TRUST=1 in CI/CD pipelines.
        severity: medium

      - name: avoid-privileged-mode
        description: Never run containers in privileged mode unless absolutely necessary. Privileged containers have full access to the host system. Use specific capabilities with --cap-add instead of --privileged.
        severity: high

      - name: read-only-root-filesystem
        description: Use --read-only flag to make the container's root filesystem read-only. This prevents attackers from modifying system files. Mount specific directories as writable using tmpfs or volumes where needed.
        severity: medium

  - name: best_practices
    description: Docker best practices for efficient and maintainable images
    rules:
      - name: use-multi-stage-builds
        description: Use multi-stage builds to reduce final image size and exclude build-time dependencies. Copy only necessary artifacts from build stages to the final stage. This improves security and reduces image size significantly.
        severity: medium

      - name: optimize-layer-caching
        description: Order Dockerfile instructions from least to most frequently changing. Copy dependency files before source code, install dependencies before copying application code. This maximizes layer cache utilization.
        severity: low

      - name: use-dockerignore
        description: Include a .dockerignore file to exclude unnecessary files from the build context. Exclude .git, node_modules, __pycache__, test files, documentation, and local configuration. This speeds up builds and reduces image size.
        severity: low

      - name: include-health-checks
        description: Add HEALTHCHECK instruction to enable container health monitoring. Define meaningful health checks that verify application readiness. Orchestrators use health checks for container lifecycle management.
        severity: medium

      - name: pin-base-image-versions
        description: Always pin base image versions with specific tags or SHA256 digests. Never use :latest tag in production Dockerfiles. Pinning ensures reproducible builds and prevents unexpected breaking changes.
        severity: high

      - name: minimize-layer-count
        description: Combine related RUN commands using && to reduce layer count. Clean up package manager caches in the same layer as installation. Each layer adds overhead to image size and pull time.
        severity: low

      - name: use-copy-over-add
        description: Prefer COPY over ADD unless you need ADD's specific features (URL fetching, tar extraction). COPY is more explicit and predictable. Use curl or wget in RUN for remote files to leverage caching.
        severity: low

  - name: networking
    description: Container networking security and configuration
    rules:
      - name: minimal-port-exposure
        description: Only expose ports that are absolutely necessary. Use EXPOSE to document ports, but prefer runtime -p flags for actual exposure. Never expose database or internal service ports to the host.
        severity: medium

      - name: use-network-isolation
        description: Use Docker networks to isolate containers and control communication. Create separate networks for frontend, backend, and database tiers. Only connect containers to networks they need.
        severity: medium

      - name: avoid-host-networking
        description: Avoid using --network=host mode as it removes network isolation. Host networking gives the container full access to host network interfaces. Use bridge networking with explicit port mappings instead.
        severity: high

  - name: resource_management
    description: Container resource limits and constraints
    rules:
      - name: set-memory-limits
        description: Always set memory limits using --memory or deploy.resources.limits.memory in compose. Unbounded memory usage can cause host system instability. Set appropriate limits based on application requirements.
        severity: medium

      - name: set-cpu-limits
        description: Set CPU limits using --cpus or deploy.resources.limits.cpus. Prevent containers from monopolizing host CPU resources. Use CPU shares for relative prioritization between containers.
        severity: medium

      - name: configure-storage-limits
        description: Configure storage driver options and use --storage-opt to limit container filesystem size. Use volume mounts for persistent data. Clean up unused images, containers, and volumes regularly.
        severity: low

  - name: image_management
    description: Container image tagging and lifecycle management
    rules:
      - name: avoid-latest-tag
        description: Never use :latest tag in production deployments. Latest is mutable and can change unexpectedly. Use semantic versioning, git commit SHAs, or build timestamps for immutable image references.
        severity: high

      - name: implement-vulnerability-scanning
        description: Integrate vulnerability scanning into CI/CD pipelines. Use tools like Trivy, Clair, or Snyk to scan images before deployment. Set policies to fail builds on critical vulnerabilities.
        severity: medium

      - name: use-immutable-tags
        description: Configure registries to enforce tag immutability where possible. Prevent tag overwriting to ensure deployment consistency. Use unique tags for each build rather than reusing tags.
        severity: medium

      - name: implement-image-lifecycle
        description: Implement image retention policies in registries. Clean up old, unused images to save storage and reduce vulnerability surface. Keep a defined number of recent versions for rollback purposes.
        severity: low