Docker Configuration Validator

What this skill does

# Docker Configuration Validator

This skill provides comprehensive validation for Dockerfiles and Docker Compose files, ensuring compliance with best practices, security standards, and modern syntax requirements.

## When to Use This Skill

Activate this skill when the user requests:
- Validate Dockerfiles or Docker Compose files
- Review Docker configurations for best practices
- Check for Docker security issues
- Verify multi-stage build implementation
- Audit Docker setup for production readiness
- Ensure modern Docker Compose syntax compliance
- Fix Docker configuration issues
- Create validation scripts or CI/CD integration

## Core Workflow

### Phase 1: Initial Assessment

When a user requests Docker validation, start by understanding the scope:

1. **Identify What to Validate**
   - Single Dockerfile or multiple?
   - Docker Compose file(s)?
   - Entire project directory?
   - Specific concerns or focus areas?
   - Production vs development environment?

2. **Understand Requirements**
   - Security compliance level needed?
   - Multi-stage build requirement?
   - Performance constraints?
   - CI/CD integration needed?
   - Automated validation script desired?

3. **Check Available Tools**
   - Is Hadolint available? (Dockerfile linter)
   - Is DCLint available? (Docker Compose linter)
   - Is Docker CLI available?
   - Should tools be installed as part of process?

### Phase 2: Dockerfile Validation

#### Step 1: Locate Dockerfiles

Find all Dockerfiles in the project:
```bash
find . -type f \( -name "Dockerfile*" ! -name "*.md" \)
```

#### Step 2: Run Hadolint Validation

**If Hadolint is available:**
```bash
# Validate each Dockerfile
hadolint Dockerfile

# JSON output for programmatic analysis
hadolint --format json Dockerfile

# Set failure threshold
hadolint --failure-threshold error Dockerfile
```

**If Hadolint is NOT available:**
- Perform manual validation using built-in checks (see Step 3)
- Recommend Hadolint installation
- Provide installation instructions

#### Step 3: Manual Dockerfile Validation

Check each Dockerfile for critical issues:

**1. Base Image Best Practices**
- ✅ Check: No `:latest` tags
- ✅ Check: Specific version pinned
- ✅ Check: Uses minimal base images (alpine/slim variants)
- ✅ Check: Trusted registry used

**2. Multi-Stage Build Verification**
```bash
# Count FROM statements (should be >= 2 for multi-stage)
FROM_COUNT=$(grep -c "^FROM " Dockerfile)

# Check for named stages
NAMED_STAGES=$(grep -c "^FROM .* AS " Dockerfile)

# Check for inter-stage copies
COPY_FROM=$(grep -c "COPY --from=" Dockerfile)
```

**Analysis:**
- If FROM_COUNT >= 2: Multi-stage build detected ✅
- If COPY_FROM == 0 and FROM_COUNT >= 2: Warning - artifacts may not be transferred
- If FROM_COUNT == 1: Single-stage build - recommend multi-stage for optimization

**3. Security Checks**
- ✅ Check: USER directive present (non-root)
- ✅ Check: Last USER is not root
- ✅ Check: No secrets in Dockerfile
- ✅ Check: WORKDIR uses absolute paths
- ✅ Check: No unnecessary privileges

**4. Layer Optimization**
- ✅ Check: Combined RUN commands
- ✅ Check: Package manager cache cleaned
- ✅ Check: COPY before RUN for better caching
- ✅ Check: .dockerignore file exists

**5. Best Practices**
- ✅ Check: HEALTHCHECK defined
- ✅ Check: WORKDIR used (not cd)
- ✅ Check: COPY preferred over ADD
- ✅ Check: CMD/ENTRYPOINT uses JSON notation
- ✅ Check: Labels included (maintainer, version)

#### Step 4: Dockerfile Issue Classification

Classify findings by severity:

**CRITICAL (Must Fix):**
- Running as root user
- Using `:latest` tags
- Secrets exposed in image
- Invalid syntax

**HIGH (Should Fix):**
- No multi-stage build when applicable
- No HEALTHCHECK
- Package versions not pinned
- Security vulnerabilities

**MEDIUM (Recommended):**
- Using ADD instead of COPY
- Not cleaning package cache
- Missing labels
- Inefficient layer structure

**LOW (Nice to Have):**
- Could use slimmer base image
- Could combine more RUN commands
- Could improve comments

### Phase 3: Docker Compose Validation

#### Step 1: Locate Compose Files

Find all Docker Compose files:
```bash
find . -maxdepth 3 -type f \( -name "docker-compose*.yml" -o -name "docker-compose*.yaml" -o -name "compose*.yml" \)
```

#### Step 2: Check for Obsolete Version Field

**CRITICAL CHECK:** Modern Docker Compose (v2.27.0+) does NOT use version field

```bash
# Check for obsolete version field
if grep -q "^version:" docker-compose.yml; then
    echo "❌ ERROR: Found obsolete 'version' field"
    echo "Remove 'version:' line - it's obsolete in Compose v2.27.0+"
fi
```

**Old (Deprecated):**
```yaml
version: '3.8'  # ❌ REMOVE THIS
services:
  web:
    image: nginx:latest
```

**New (Modern):**
```yaml
# No version field!
services:
  web:
    image: nginx:1.24-alpine
```

#### Step 3: Built-in Docker Compose Validation

```bash
# Syntax validation
docker compose config --quiet

# Show resolved configuration
docker compose config

# Validate specific file
docker compose -f docker-compose.prod.yml config --quiet
```

#### Step 4: DCLint Validation (if available)

```bash
# Lint compose file
dclint docker-compose.yml

# Auto-fix issues
dclint --fix docker-compose.yml

# JSON output
dclint --format json docker-compose.yml
```

#### Step 5: Manual Compose Validation

**1. Image Best Practices**
- ✅ Check: No `:latest` tags
- ✅ Check: Specific versions specified
- ✅ Check: Images from trusted sources

**2. Service Configuration**
- ✅ Check: Restart policies defined
- ✅ Check: Health checks configured
- ✅ Check: Resource limits set (optional but recommended)
- ✅ Check: Proper service dependencies (depends_on)

**3. Networking**
- ✅ Check: Custom networks defined
- ✅ Check: Network isolation implemented
- ✅ Check: Appropriate network drivers used

**4. Volumes & Persistence**
- ✅ Check: Named volumes for persistence
- ✅ Check: Volume drivers specified
- ✅ Check: Bind mounts use absolute paths
- ✅ Check: No sensitive data in volumes

**5. Environment & Secrets**
- ✅ Check: Environment variables properly managed
- ✅ Check: No hardcoded secrets
- ✅ Check: .env file usage recommended
- ✅ Check: Secrets management configured

**6. Security**
- ✅ Check: No privileged mode (unless necessary)
- ✅ Check: Capabilities properly configured
- ✅ Check: User/group specified
- ✅ Check: Read-only root filesystem (where applicable)

### Phase 4: Multi-Stage Build Deep Dive

When validating multi-stage builds, ensure:

**1. Stage Structure**
```dockerfile
# Build stage
FROM node:20-bullseye AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm run test

# Production stage
FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/index.js"]
```

**2. Validation Checklist**
- ✅ At least 2 stages (build + runtime)
- ✅ All stages are named with AS keyword
- ✅ Artifacts copied between stages using COPY --from
- ✅ Final stage uses minimal base image
- ✅ Build tools NOT in final stage
- ✅ Only necessary files in final image
- ✅ Final stage runs as non-root user

**3. Common Patterns to Check**

**Node.js Multi-Stage:**
- Build stage: Install all deps, build, test
- Runtime stage: Production deps only, built artifacts

**Python Multi-Stage:**
- Build stage: Compile dependencies, build wheels
- Runtime stage: Install pre-built wheels, app only

**Go Multi-Stage:**
- Build stage: Full Go toolchain, compile binary
- Runtime stage: Scratch/distroless, binary only

### Phase 5: Security Audit

Perform comprehensive security checks:

**1. User & Permissions**
```bash
# Check for USER directive
USER_COUNT=$(grep -c "^USER " Dockerfile)
LAST_USER=$(grep "^USER " Dockerfile | tail -1 | awk '{print $2}')

if [ "$USER_COUNT" -eq 0 ]; then
    echo "❌ CRITICAL: No USER specified (runs as root!)"
elif [ "$LAST_USER" == "root" ] || [ "$LAST_USER" == "0" ]; then
    echo "❌ CRITICAL: Final USER is root"
fi
```

**2. Exposed Secrets**
- Check for passwords in ENV