Initial commit
This commit is contained in:
Zhongwei Li
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"name": "docker-validation",
|
||||
"description": "Comprehensive Docker and Docker Compose validation following best practices and security standards. Validates Dockerfiles, multi-stage builds, modern Compose syntax, and generates automation scripts",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "rknall",
|
||||
"email": "zhongweili@tubi.tv"
|
||||
},
|
||||
"skills": [
|
||||
"./"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# docker-validation
|
||||
|
||||
Comprehensive Docker and Docker Compose validation following best practices and security standards. Validates Dockerfiles, multi-stage builds, modern Compose syntax, and generates automation scripts
|
||||
758
SKILL.md
Normal file
758
SKILL.md
Normal file
@@ -0,0 +1,758 @@
|
||||
---
|
||||
name: "Docker Configuration Validator"
|
||||
description: "Comprehensive Docker and Docker Compose validation following best practices and security standards. Use this skill when users ask to validate Dockerfiles, review Docker configurations, check Docker Compose files, verify multi-stage builds, audit Docker security, or ensure compliance with Docker best practices. Validates syntax, security, multi-stage builds, and modern Docker Compose requirements."
|
||||
---
|
||||
|
||||
# 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
|
||||
- Check for API keys in COPY/ADD
|
||||
- Check for credentials in RUN commands
|
||||
- Recommend secrets management solutions
|
||||
|
||||
**3. Vulnerable Base Images**
|
||||
- Check base image age and support status
|
||||
- Recommend security scanning (Trivy, Snyk)
|
||||
- Suggest pinned, supported versions
|
||||
|
||||
**4. Network Exposure**
|
||||
- Review EXPOSE directives
|
||||
- Check if unnecessary ports exposed
|
||||
- Validate port mappings in Compose
|
||||
|
||||
### Phase 6: Generate Validation Report
|
||||
|
||||
Structure the validation report:
|
||||
|
||||
```markdown
|
||||
# Docker Configuration Validation Report
|
||||
|
||||
## Executive Summary
|
||||
- **Total Dockerfiles Analyzed**: X
|
||||
- **Total Compose Files Analyzed**: X
|
||||
- **Critical Issues**: X
|
||||
- **High Priority Issues**: X
|
||||
- **Medium Priority Issues**: X
|
||||
- **Low Priority Issues**: X
|
||||
- **Overall Status**: ✅ PASS / ⚠️ WARNINGS / ❌ FAIL
|
||||
|
||||
## Dockerfile Analysis
|
||||
|
||||
### [Dockerfile Path]
|
||||
|
||||
#### Validation Results
|
||||
✅ **PASSED**: Multi-stage build implemented
|
||||
✅ **PASSED**: Running as non-root user
|
||||
⚠️ **WARNING**: Using ADD instead of COPY (line 15)
|
||||
❌ **FAILED**: Base image uses :latest tag (line 1)
|
||||
|
||||
#### Security Assessment
|
||||
- **User**: nodejs (non-root) ✅
|
||||
- **Base Image**: node:latest ❌
|
||||
- **Secrets**: None detected ✅
|
||||
- **Health Check**: Present ✅
|
||||
|
||||
#### Multi-Stage Build Analysis
|
||||
- **Stages**: 2 (builder, runtime)
|
||||
- **Named Stages**: Yes ✅
|
||||
- **Inter-Stage Copies**: 1 ✅
|
||||
- **Final Base**: node:20-alpine ✅
|
||||
- **Build Tools in Final**: No ✅
|
||||
|
||||
#### Issues Found
|
||||
|
||||
**CRITICAL:**
|
||||
1. Line 1: Using :latest tag
|
||||
- Issue: `FROM node:latest`
|
||||
- Fix: `FROM node:20-bullseye`
|
||||
- Impact: Unpredictable builds, security risk
|
||||
|
||||
**HIGH:**
|
||||
2. Line 45: Package cache not cleaned
|
||||
- Issue: `RUN apt-get install -y curl`
|
||||
- Fix: Add `&& rm -rf /var/lib/apt/lists/*`
|
||||
- Impact: Larger image size
|
||||
|
||||
**MEDIUM:**
|
||||
3. Line 15: Using ADD instead of COPY
|
||||
- Issue: `ADD app.tar.gz /app/`
|
||||
- Fix: `COPY app.tar.gz /app/` (or extract separately)
|
||||
- Impact: Less explicit behavior
|
||||
|
||||
## Docker Compose Analysis
|
||||
|
||||
### [Compose File Path]
|
||||
|
||||
#### Validation Results
|
||||
❌ **FAILED**: Obsolete 'version' field present
|
||||
⚠️ **WARNING**: 3 services using :latest tags
|
||||
✅ **PASSED**: Custom networks defined
|
||||
✅ **PASSED**: Named volumes configured
|
||||
|
||||
#### Modern Syntax Compliance
|
||||
- **Version Field**: Present ❌ (MUST REMOVE)
|
||||
- **Specific Tags**: 2 of 5 services ⚠️
|
||||
- **Restart Policies**: All services ✅
|
||||
- **Health Checks**: 3 of 5 services ⚠️
|
||||
|
||||
#### Issues Found
|
||||
|
||||
**CRITICAL:**
|
||||
1. Obsolete 'version' field
|
||||
- Issue: `version: '3.8'`
|
||||
- Fix: Remove the entire line
|
||||
- Impact: Using deprecated syntax
|
||||
|
||||
**HIGH:**
|
||||
2. Service 'web' uses :latest tag
|
||||
- Issue: `image: nginx:latest`
|
||||
- Fix: `image: nginx:1.24-alpine`
|
||||
- Impact: Unpredictable deployments
|
||||
|
||||
3. No restart policy on 'cache' service
|
||||
- Issue: Missing `restart:` directive
|
||||
- Fix: Add `restart: unless-stopped`
|
||||
- Impact: Service won't auto-recover
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions (Critical)
|
||||
1. Pin all Docker image versions (remove :latest)
|
||||
2. Remove obsolete 'version' field from Compose files
|
||||
3. Ensure all services run as non-root users
|
||||
4. Clean package manager caches in all Dockerfiles
|
||||
|
||||
### High Priority (Before Production)
|
||||
1. Implement health checks for all services
|
||||
2. Add restart policies to all Compose services
|
||||
3. Set up resource limits (memory, CPU)
|
||||
4. Implement proper secrets management
|
||||
|
||||
### Medium Priority (Best Practices)
|
||||
1. Use COPY instead of ADD unless extracting archives
|
||||
2. Add labels for better organization
|
||||
3. Implement logging drivers
|
||||
4. Add metadata to images
|
||||
|
||||
### Low Priority (Optimizations)
|
||||
1. Consider slimmer base images where possible
|
||||
2. Optimize layer caching with better ordering
|
||||
3. Add comprehensive comments
|
||||
4. Implement .dockerignore files
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Fix Critical Issues** (Estimated: 30 minutes)
|
||||
- Pin image versions
|
||||
- Remove version field from Compose
|
||||
- Add USER directives
|
||||
|
||||
2. **Address High Priority** (Estimated: 1-2 hours)
|
||||
- Add health checks
|
||||
- Configure restart policies
|
||||
- Set resource limits
|
||||
|
||||
3. **Re-validate** (Estimated: 10 minutes)
|
||||
- Run validation again after fixes
|
||||
- Ensure all critical issues resolved
|
||||
|
||||
4. **Set Up Automation** (Estimated: 1 hour)
|
||||
- Add pre-commit hooks
|
||||
- Integrate into CI/CD
|
||||
- Schedule regular security scans
|
||||
|
||||
## Validation Tools Recommendations
|
||||
|
||||
### Install Required Tools
|
||||
```bash
|
||||
# Hadolint (Dockerfile linter)
|
||||
brew install hadolint # macOS
|
||||
# or
|
||||
wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64
|
||||
|
||||
# DCLint (Docker Compose linter)
|
||||
npm install -g docker-compose-linter
|
||||
|
||||
# Trivy (Security scanner)
|
||||
brew install aquasecurity/trivy/trivy
|
||||
```
|
||||
|
||||
### Automated Validation Script
|
||||
[Provide custom validation script based on project needs]
|
||||
|
||||
### CI/CD Integration
|
||||
[Provide GitHub Actions / GitLab CI configuration]
|
||||
```
|
||||
|
||||
## Deliverables
|
||||
|
||||
At the end of validation, provide:
|
||||
|
||||
1. **Comprehensive Validation Report**
|
||||
- Executive summary with overall status
|
||||
- Detailed findings per file
|
||||
- Issue classification (Critical → Low)
|
||||
- Specific fixes for each issue
|
||||
- Recommendations prioritized
|
||||
|
||||
2. **Fixed Configuration Files** (if requested)
|
||||
- Corrected Dockerfiles
|
||||
- Updated Compose files
|
||||
- .hadolint.yaml configuration
|
||||
- .dclintrc.json configuration
|
||||
|
||||
3. **Validation Script** (if requested)
|
||||
- Custom bash script for automated validation
|
||||
- Checks for project-specific requirements
|
||||
- Color-coded output
|
||||
- Exit codes for CI/CD
|
||||
|
||||
4. **CI/CD Integration** (if requested)
|
||||
- GitHub Actions workflow
|
||||
- GitLab CI configuration
|
||||
- Pre-commit hooks
|
||||
- Integration with existing pipeline
|
||||
|
||||
5. **Documentation**
|
||||
- How to run validation locally
|
||||
- Tool installation instructions
|
||||
- Best practices guide
|
||||
- Common issues and solutions
|
||||
|
||||
## Validation Script Template
|
||||
|
||||
When user requests automated validation, create this script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# docker-validation.sh
|
||||
|
||||
set -e
|
||||
|
||||
# Color codes
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m'
|
||||
|
||||
ERRORS=0
|
||||
WARNINGS=0
|
||||
|
||||
echo -e "${BLUE}╔══════════════════════════════════════════╗${NC}"
|
||||
echo -e "${BLUE}║ Docker Configuration Validator ║${NC}"
|
||||
echo -e "${BLUE}╚══════════════════════════════════════════╝${NC}"
|
||||
|
||||
# 1. Prerequisites check
|
||||
echo -e "\n${BLUE}━━━ Checking Prerequisites ━━━${NC}"
|
||||
command -v docker >/dev/null || { echo "❌ Docker not found"; exit 1; }
|
||||
command -v hadolint >/dev/null || echo "⚠️ Hadolint not installed"
|
||||
|
||||
# 2. Dockerfile validation
|
||||
echo -e "\n${BLUE}━━━ Validating Dockerfiles ━━━${NC}"
|
||||
find . -name "Dockerfile*" -type f | while read df; do
|
||||
echo "Checking: $df"
|
||||
# [Validation logic here]
|
||||
done
|
||||
|
||||
# 3. Multi-stage build check
|
||||
echo -e "\n${BLUE}━━━ Checking Multi-Stage Builds ━━━${NC}"
|
||||
# [Multi-stage validation logic]
|
||||
|
||||
# 4. Compose validation
|
||||
echo -e "\n${BLUE}━━━ Validating Docker Compose ━━━${NC}"
|
||||
find . -name "*compose*.yml" | while read cf; do
|
||||
# Check for obsolete version field
|
||||
if grep -q "^version:" "$cf"; then
|
||||
echo -e "${RED}❌ $cf: Obsolete version field${NC}"
|
||||
ERRORS=$((ERRORS + 1))
|
||||
fi
|
||||
|
||||
# Validate syntax
|
||||
docker compose -f "$cf" config --quiet || ERRORS=$((ERRORS + 1))
|
||||
done
|
||||
|
||||
# 5. Security checks
|
||||
echo -e "\n${BLUE}━━━ Security Audit ━━━${NC}"
|
||||
# [Security validation logic]
|
||||
|
||||
# Final report
|
||||
echo -e "\n${BLUE}╔══════════════════════════════════════════╗${NC}"
|
||||
echo -e "${BLUE}║ Validation Summary ║${NC}"
|
||||
echo -e "${BLUE}╚══════════════════════════════════════════╝${NC}"
|
||||
|
||||
if [ $ERRORS -eq 0 ]; then
|
||||
echo -e "${GREEN}✅ All checks passed!${NC}"
|
||||
exit 0
|
||||
else
|
||||
echo -e "${RED}❌ Found $ERRORS error(s), $WARNINGS warning(s)${NC}"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## CI/CD Integration Templates
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Docker Validation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Lint Dockerfiles
|
||||
uses: hadolint/hadolint-action@v3.1.0
|
||||
with:
|
||||
dockerfile: ./Dockerfile
|
||||
failure-threshold: error
|
||||
|
||||
- name: Validate Compose files
|
||||
run: |
|
||||
for f in $(find . -name "*compose*.yml"); do
|
||||
docker compose -f "$f" config --quiet
|
||||
done
|
||||
|
||||
- name: Check for obsolete version field
|
||||
run: |
|
||||
if grep -r "^version:" . --include="*compose*.yml"; then
|
||||
echo "ERROR: Found obsolete version field"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- validate
|
||||
|
||||
docker-validation:
|
||||
stage: validate
|
||||
image: hadolint/hadolint:latest-debian
|
||||
script:
|
||||
- find . -name "Dockerfile*" -exec hadolint {} \;
|
||||
- |
|
||||
for f in $(find . -name "*compose*.yml"); do
|
||||
if grep -q "^version:" "$f"; then
|
||||
echo "ERROR: Obsolete version field in $f"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Communication Style
|
||||
|
||||
When conducting validation:
|
||||
|
||||
1. **Be Thorough**
|
||||
- Check all aspects systematically
|
||||
- Don't skip manual checks if tools unavailable
|
||||
- Validate both syntax and best practices
|
||||
|
||||
2. **Prioritize Clearly**
|
||||
- Critical issues first (security, functionality)
|
||||
- High priority next (production readiness)
|
||||
- Medium and low as improvements
|
||||
|
||||
3. **Provide Specific Fixes**
|
||||
- Show exact line numbers
|
||||
- Provide before/after code
|
||||
- Explain why the fix is needed
|
||||
- Include impact assessment
|
||||
|
||||
4. **Educate**
|
||||
- Explain Docker best practices
|
||||
- Reference official documentation
|
||||
- Provide learning resources
|
||||
- Share modern syntax requirements
|
||||
|
||||
5. **Be Actionable**
|
||||
- Give step-by-step remediation
|
||||
- Provide automation scripts
|
||||
- Suggest CI/CD integration
|
||||
- Estimate effort for fixes
|
||||
|
||||
## Common Validation Patterns
|
||||
|
||||
### Pattern 1: Quick Syntax Check
|
||||
- Run Hadolint and DCLint
|
||||
- Check for obsolete version field
|
||||
- Validate with Docker Compose config
|
||||
- Report critical syntax errors only
|
||||
|
||||
### Pattern 2: Full Production Audit
|
||||
- Complete Dockerfile validation
|
||||
- Multi-stage build verification
|
||||
- Security audit
|
||||
- Compose best practices
|
||||
- Generate comprehensive report
|
||||
- Provide automation scripts
|
||||
|
||||
### Pattern 3: Security-Focused Review
|
||||
- User privilege checks
|
||||
- Secret exposure scan
|
||||
- Base image security
|
||||
- Network exposure audit
|
||||
- Security scanning integration
|
||||
|
||||
### Pattern 4: Optimization Review
|
||||
- Multi-stage build effectiveness
|
||||
- Layer optimization
|
||||
- Image size analysis
|
||||
- Build time improvements
|
||||
- Caching strategies
|
||||
|
||||
## Key Rules to Enforce
|
||||
|
||||
### Dockerfile Rules (Critical)
|
||||
- ✅ No `:latest` tags (DL3006)
|
||||
- ✅ Last USER not root (DL3002)
|
||||
- ✅ Use absolute WORKDIR (DL3000)
|
||||
- ✅ Pin package versions (DL3008, DL3013)
|
||||
- ✅ Clean package cache (DL3009)
|
||||
|
||||
### Docker Compose Rules (Critical)
|
||||
- ✅ NO version field (obsolete since v2.27.0)
|
||||
- ✅ No `:latest` tags
|
||||
- ✅ Restart policies defined
|
||||
- ✅ Health checks configured
|
||||
- ✅ Named volumes for persistence
|
||||
|
||||
### Multi-Stage Build Rules
|
||||
- ✅ Minimum 2 stages
|
||||
- ✅ Named stages with AS
|
||||
- ✅ COPY --from for artifacts
|
||||
- ✅ Minimal final base image
|
||||
- ✅ No build tools in final stage
|
||||
|
||||
### Security Rules (Critical)
|
||||
- ✅ Run as non-root USER
|
||||
- ✅ No secrets in images
|
||||
- ✅ Minimal base images
|
||||
- ✅ Regular security scans
|
||||
- ✅ Least privilege principle
|
||||
|
||||
## Reference Resources
|
||||
|
||||
When providing recommendations, reference:
|
||||
- **Docker Best Practices**: Official Docker documentation
|
||||
- **Hadolint Rules**: Complete rule reference
|
||||
- **Compose Specification**: Latest Compose spec
|
||||
- **Security Standards**: CIS Docker Benchmark
|
||||
- **Multi-Stage Builds**: Official guide and examples
|
||||
|
||||
Remember: Docker validation is about ensuring reliable, secure, and efficient containerized applications. Always prioritize security and production readiness while maintaining developer experience.
|
||||
53
plugin.lock.json
Normal file
53
plugin.lock.json
Normal file
@@ -0,0 +1,53 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:rknall/claude-skills:docker-validation",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "8cc5ec984d23c20300a150de3c87be39b7b6c111",
|
||||
"treeHash": "d2440a839805bddbc3ac76a4c3bcee1d1b0dd48c5bb22652a7e5f58c6745cec0",
|
||||
"generatedAt": "2025-11-28T10:27:58.504775Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "docker-validation",
|
||||
"description": "Comprehensive Docker and Docker Compose validation following best practices and security standards. Validates Dockerfiles, multi-stage builds, modern Compose syntax, and generates automation scripts",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "tool-installation.md",
|
||||
"sha256": "67320fa4f3da391ca9fa796e7740472afefe860729453d2f88be052f65e3d2d0"
|
||||
},
|
||||
{
|
||||
"path": "validation-checklist.md",
|
||||
"sha256": "962d618839fe19bf41ff0319bc33de9c240c48c7408aaef59ca09d62da11f648"
|
||||
},
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "32fc2ef39ba11b721c5dd41910bb8fc871f9cdd88e864e108e09ee2a783cb479"
|
||||
},
|
||||
{
|
||||
"path": "SKILL.md",
|
||||
"sha256": "3d86d2c06e23e6c020b06d0a10b663a1211dba63c12489390724e4e48fdd46b0"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "8cf25cd9c9986106a943d40aae9247b2ebbf7ae71ba48bfa726177688fb2e221"
|
||||
}
|
||||
],
|
||||
"dirSha256": "d2440a839805bddbc3ac76a4c3bcee1d1b0dd48c5bb22652a7e5f58c6745cec0"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
534
tool-installation.md
Normal file
534
tool-installation.md
Normal file
@@ -0,0 +1,534 @@
|
||||
# Docker Validation Tools Installation Guide
|
||||
|
||||
Complete installation instructions for all tools needed for Docker configuration validation.
|
||||
|
||||
## Required Tools
|
||||
|
||||
### 1. Docker & Docker Compose
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# Install Docker Desktop (includes Docker and Compose)
|
||||
brew install --cask docker
|
||||
|
||||
# Start Docker Desktop application
|
||||
open -a Docker
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
#### Linux (Ubuntu/Debian)
|
||||
```bash
|
||||
# Install Docker Engine
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# Install Docker Compose
|
||||
sudo apt-get update
|
||||
sudo apt-get install docker-compose-plugin
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
#### Windows
|
||||
```powershell
|
||||
# Install Docker Desktop via Chocolatey
|
||||
choco install docker-desktop
|
||||
|
||||
# Or download from https://www.docker.com/products/docker-desktop
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
**Minimum Versions:**
|
||||
- Docker: 20.10.0+
|
||||
- Docker Compose: v2.27.0+ (for modern syntax support)
|
||||
|
||||
## Validation Tools
|
||||
|
||||
### 2. Hadolint (Dockerfile Linter)
|
||||
|
||||
**Why Hadolint?**
|
||||
- Parses Dockerfile into AST for deep analysis
|
||||
- Integrates ShellCheck for bash validation
|
||||
- Enforces Docker best practices
|
||||
- Highly configurable
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# Install via Homebrew (recommended)
|
||||
brew install hadolint
|
||||
|
||||
# Verify installation
|
||||
hadolint --version
|
||||
```
|
||||
|
||||
#### Linux
|
||||
```bash
|
||||
# Download binary (x86_64)
|
||||
HADOLINT_VERSION=v2.12.0
|
||||
wget -O /usr/local/bin/hadolint \
|
||||
https://github.com/hadolint/hadolint/releases/download/${HADOLINT_VERSION}/hadolint-Linux-x86_64
|
||||
|
||||
# Make executable
|
||||
chmod +x /usr/local/bin/hadolint
|
||||
|
||||
# Verify installation
|
||||
hadolint --version
|
||||
```
|
||||
|
||||
#### Windows
|
||||
```powershell
|
||||
# Download binary
|
||||
$HADOLINT_VERSION = "v2.12.0"
|
||||
Invoke-WebRequest -Uri "https://github.com/hadolint/hadolint/releases/download/${HADOLINT_VERSION}/hadolint-Windows-x86_64.exe" -OutFile "hadolint.exe"
|
||||
|
||||
# Move to PATH location
|
||||
Move-Item hadolint.exe C:\Windows\System32\hadolint.exe
|
||||
|
||||
# Verify installation
|
||||
hadolint --version
|
||||
```
|
||||
|
||||
#### Using Docker (Cross-platform)
|
||||
```bash
|
||||
# Run Hadolint in container
|
||||
docker run --rm -i hadolint/hadolint:latest < Dockerfile
|
||||
|
||||
# Create alias for convenience
|
||||
echo 'alias hadolint="docker run --rm -i hadolint/hadolint:latest"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Verify
|
||||
hadolint --version
|
||||
```
|
||||
|
||||
#### VS Code Integration
|
||||
```bash
|
||||
# Install VS Code extension
|
||||
code --install-extension exiasr.hadolint
|
||||
|
||||
# Extension will automatically use hadolint if installed
|
||||
```
|
||||
|
||||
### 3. DCLint (Docker Compose Linter)
|
||||
|
||||
**Why DCLint?**
|
||||
- Validates Docker Compose syntax
|
||||
- Enforces best practices
|
||||
- Checks for obsolete version field
|
||||
- Auto-fix capabilities
|
||||
|
||||
#### Prerequisites
|
||||
```bash
|
||||
# Requires Node.js 20.19.0+
|
||||
node --version
|
||||
|
||||
# If not installed:
|
||||
# macOS
|
||||
brew install node
|
||||
|
||||
# Linux (Ubuntu/Debian)
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Windows
|
||||
choco install nodejs
|
||||
```
|
||||
|
||||
#### Installation
|
||||
```bash
|
||||
# Install globally via npm (recommended)
|
||||
npm install -g docker-compose-linter
|
||||
|
||||
# Or install locally in project
|
||||
npm install --save-dev docker-compose-linter
|
||||
|
||||
# Verify installation
|
||||
dclint --version
|
||||
```
|
||||
|
||||
#### Using npx (No Installation)
|
||||
```bash
|
||||
# Run without global install
|
||||
npx dclint docker-compose.yml
|
||||
```
|
||||
|
||||
### 4. Trivy (Security Scanner)
|
||||
|
||||
**Why Trivy?**
|
||||
- Comprehensive vulnerability scanner
|
||||
- Scans images, filesystems, and configs
|
||||
- Free and open-source
|
||||
- Fast and easy to use
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# Install via Homebrew
|
||||
brew install aquasecurity/trivy/trivy
|
||||
|
||||
# Verify installation
|
||||
trivy --version
|
||||
```
|
||||
|
||||
#### Linux (Debian/Ubuntu)
|
||||
```bash
|
||||
# Add repository
|
||||
sudo apt-get install wget gnupg
|
||||
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
|
||||
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
|
||||
|
||||
# Install
|
||||
sudo apt-get update
|
||||
sudo apt-get install trivy
|
||||
|
||||
# Verify installation
|
||||
trivy --version
|
||||
```
|
||||
|
||||
#### Using Docker
|
||||
```bash
|
||||
# Run Trivy in container
|
||||
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy:latest image nginx:latest
|
||||
|
||||
# Scan Dockerfile
|
||||
docker run --rm -v $(pwd):/app aquasec/trivy:latest config /app/Dockerfile
|
||||
```
|
||||
|
||||
## Optional But Recommended Tools
|
||||
|
||||
### 5. Dive (Image Layer Analyzer)
|
||||
|
||||
Analyzes Docker image layers to optimize size.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install dive
|
||||
|
||||
# Linux
|
||||
wget https://github.com/wagoodman/dive/releases/download/v0.11.0/dive_0.11.0_linux_amd64.deb
|
||||
sudo apt install ./dive_0.11.0_linux_amd64.deb
|
||||
|
||||
# Usage
|
||||
dive nginx:latest
|
||||
```
|
||||
|
||||
### 6. Docker Bench Security
|
||||
|
||||
Automated security audit for Docker deployments.
|
||||
|
||||
```bash
|
||||
# Run security audit
|
||||
docker run --rm --net host --pid host --userns host --cap-add audit_control \
|
||||
-e DOCKER_CONTENT_TRUST=$DOCKER_CONTENT_TRUST \
|
||||
-v /etc:/etc:ro \
|
||||
-v /usr/bin/containerd:/usr/bin/containerd:ro \
|
||||
-v /usr/bin/runc:/usr/bin/runc:ro \
|
||||
-v /usr/lib/systemd:/usr/lib/systemd:ro \
|
||||
-v /var/lib:/var/lib:ro \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
--label docker_bench_security \
|
||||
docker/docker-bench-security
|
||||
```
|
||||
|
||||
### 7. Snyk (Alternative Security Scanner)
|
||||
|
||||
```bash
|
||||
# Install Snyk CLI
|
||||
npm install -g snyk
|
||||
|
||||
# Authenticate
|
||||
snyk auth
|
||||
|
||||
# Test Dockerfile
|
||||
snyk container test nginx:latest
|
||||
|
||||
# Test Docker image
|
||||
snyk container test myapp:latest --file=Dockerfile
|
||||
```
|
||||
|
||||
## Configuration Files Setup
|
||||
|
||||
### Create .hadolint.yaml
|
||||
```bash
|
||||
cat > .hadolint.yaml << 'EOF'
|
||||
---
|
||||
ignored:
|
||||
- DL3008 # Pin versions in apt-get (sometimes too strict)
|
||||
- DL3013 # Pin versions in pip
|
||||
- DL3018 # Pin versions in apk
|
||||
|
||||
override:
|
||||
error:
|
||||
- DL3002 # Last user should not be root
|
||||
- DL3020 # Use COPY instead of ADD
|
||||
warning:
|
||||
- DL3003 # Use WORKDIR instead of cd
|
||||
|
||||
trustedRegistries:
|
||||
- docker.io
|
||||
- ghcr.io
|
||||
- gcr.io
|
||||
- quay.io
|
||||
|
||||
strict-labels: true
|
||||
EOF
|
||||
```
|
||||
|
||||
### Create .dclintrc.json
|
||||
```bash
|
||||
cat > .dclintrc.json << 'EOF'
|
||||
{
|
||||
"rules": {
|
||||
"no-version-field": "error",
|
||||
"require-quotes": "warning",
|
||||
"service-name-case": ["error", "kebab-case"],
|
||||
"no-duplicate-keys": "error",
|
||||
"require-restart": "warning"
|
||||
},
|
||||
"exclude": [
|
||||
"node_modules/**",
|
||||
".git/**",
|
||||
"dist/**"
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Create .dockerignore
|
||||
```bash
|
||||
cat > .dockerignore << 'EOF'
|
||||
# Git
|
||||
.git
|
||||
.gitignore
|
||||
.gitattributes
|
||||
|
||||
# CI/CD
|
||||
.github
|
||||
.gitlab-ci.yml
|
||||
Jenkinsfile
|
||||
|
||||
# Documentation
|
||||
README.md
|
||||
CHANGELOG.md
|
||||
docs/
|
||||
|
||||
# Dependencies
|
||||
node_modules/
|
||||
vendor/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Build artifacts
|
||||
dist/
|
||||
build/
|
||||
target/
|
||||
*.log
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
*.pem
|
||||
*.key
|
||||
EOF
|
||||
```
|
||||
|
||||
## Verification Script
|
||||
|
||||
Create a script to verify all tools are installed:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# verify-tools.sh
|
||||
|
||||
echo "🔍 Checking Docker Validation Tools..."
|
||||
echo ""
|
||||
|
||||
# Check Docker
|
||||
if command -v docker &> /dev/null; then
|
||||
echo "✅ Docker: $(docker --version)"
|
||||
else
|
||||
echo "❌ Docker: NOT INSTALLED"
|
||||
fi
|
||||
|
||||
# Check Docker Compose
|
||||
if docker compose version &> /dev/null; then
|
||||
echo "✅ Docker Compose: $(docker compose version)"
|
||||
else
|
||||
echo "❌ Docker Compose: NOT INSTALLED"
|
||||
fi
|
||||
|
||||
# Check Hadolint
|
||||
if command -v hadolint &> /dev/null; then
|
||||
echo "✅ Hadolint: $(hadolint --version)"
|
||||
else
|
||||
echo "⚠️ Hadolint: NOT INSTALLED (recommended)"
|
||||
fi
|
||||
|
||||
# Check DCLint
|
||||
if command -v dclint &> /dev/null; then
|
||||
echo "✅ DCLint: $(dclint --version 2>&1 | head -1)"
|
||||
else
|
||||
echo "⚠️ DCLint: NOT INSTALLED (recommended)"
|
||||
fi
|
||||
|
||||
# Check Trivy
|
||||
if command -v trivy &> /dev/null; then
|
||||
echo "✅ Trivy: $(trivy --version | head -1)"
|
||||
else
|
||||
echo "⚠️ Trivy: NOT INSTALLED (optional)"
|
||||
fi
|
||||
|
||||
# Check Node.js (for DCLint)
|
||||
if command -v node &> /dev/null; then
|
||||
echo "✅ Node.js: $(node --version)"
|
||||
else
|
||||
echo "⚠️ Node.js: NOT INSTALLED (needed for DCLint)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📊 Installation Summary:"
|
||||
echo " Required tools: Docker, Docker Compose"
|
||||
echo " Recommended: Hadolint, DCLint"
|
||||
echo " Optional: Trivy, Dive, Docker Bench"
|
||||
```
|
||||
|
||||
Make it executable and run:
|
||||
```bash
|
||||
chmod +x verify-tools.sh
|
||||
./verify-tools.sh
|
||||
```
|
||||
|
||||
## Quick Start Commands
|
||||
|
||||
After installation, test the tools:
|
||||
|
||||
```bash
|
||||
# Test Hadolint
|
||||
echo 'FROM node:latest' > test.Dockerfile
|
||||
hadolint test.Dockerfile
|
||||
rm test.Dockerfile
|
||||
|
||||
# Test DCLint
|
||||
echo 'services:
|
||||
web:
|
||||
image: nginx:latest' > test-compose.yml
|
||||
dclint test-compose.yml
|
||||
rm test-compose.yml
|
||||
|
||||
# Test Docker Compose validation
|
||||
docker compose config --quiet
|
||||
|
||||
# Test Trivy (if installed)
|
||||
trivy image nginx:latest
|
||||
|
||||
# Test full validation
|
||||
./validate-docker.sh # (if you have the validation script)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hadolint: Command not found
|
||||
```bash
|
||||
# Check if binary exists
|
||||
ls -la /usr/local/bin/hadolint
|
||||
|
||||
# Check PATH
|
||||
echo $PATH
|
||||
|
||||
# Add to PATH if needed
|
||||
export PATH="/usr/local/bin:$PATH"
|
||||
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### DCLint: Module not found
|
||||
```bash
|
||||
# Check npm global prefix
|
||||
npm config get prefix
|
||||
|
||||
# If not in PATH, add it
|
||||
export PATH="$(npm config get prefix)/bin:$PATH"
|
||||
|
||||
# Or use npx
|
||||
npx dclint docker-compose.yml
|
||||
```
|
||||
|
||||
### Docker Compose: version command not recognized
|
||||
```bash
|
||||
# Check Docker Compose version
|
||||
docker compose version # New (v2)
|
||||
docker-compose --version # Old (v1, deprecated)
|
||||
|
||||
# If using v1, upgrade to v2
|
||||
# Follow Docker documentation for your OS
|
||||
```
|
||||
|
||||
### Permission Denied (Linux)
|
||||
```bash
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# Verify
|
||||
docker ps
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
Already includes all tools in standard ubuntu-latest runner:
|
||||
```yaml
|
||||
- name: Validate Docker configs
|
||||
run: |
|
||||
docker --version
|
||||
docker compose version
|
||||
# Install additional tools if needed
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
```yaml
|
||||
before_script:
|
||||
- apt-get update
|
||||
- apt-get install -y wget
|
||||
- wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64
|
||||
- chmod +x /usr/local/bin/hadolint
|
||||
```
|
||||
|
||||
## Update Tools
|
||||
|
||||
Keep tools up to date:
|
||||
|
||||
```bash
|
||||
# Update Hadolint (macOS)
|
||||
brew upgrade hadolint
|
||||
|
||||
# Update DCLint
|
||||
npm update -g docker-compose-linter
|
||||
|
||||
# Update Trivy (macOS)
|
||||
brew upgrade trivy
|
||||
|
||||
# Update Docker Desktop
|
||||
# Use built-in updater or:
|
||||
brew upgrade --cask docker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**All tools installed? Run `./verify-tools.sh` to confirm!**
|
||||
351
validation-checklist.md
Normal file
351
validation-checklist.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# Docker Validation Checklist
|
||||
|
||||
Complete checklist for validating Docker configurations. Use this as a reference when performing manual validation.
|
||||
|
||||
## Dockerfile Validation Checklist
|
||||
|
||||
### Base Image (Critical)
|
||||
- [ ] No `:latest` tags used
|
||||
- [ ] Specific version pinned (e.g., `node:20.11.0-alpine`)
|
||||
- [ ] Uses minimal base image (alpine, slim, or distroless variants)
|
||||
- [ ] Trusted registry used (docker.io, ghcr.io, gcr.io, quay.io)
|
||||
- [ ] Base image is actively maintained and supported
|
||||
|
||||
### Multi-Stage Build (High Priority)
|
||||
- [ ] At least 2 stages for production builds (build + runtime)
|
||||
- [ ] All stages named with `AS` keyword
|
||||
- [ ] Artifacts copied between stages using `COPY --from=`
|
||||
- [ ] Final stage uses minimal base image
|
||||
- [ ] Build tools NOT present in final stage
|
||||
- [ ] Only necessary files in final image
|
||||
|
||||
### Security (Critical)
|
||||
- [ ] `USER` directive present (non-root user specified)
|
||||
- [ ] Last `USER` is NOT root or 0
|
||||
- [ ] No secrets in ENV variables
|
||||
- [ ] No secrets in COPY/ADD commands
|
||||
- [ ] No secrets in RUN commands
|
||||
- [ ] No hardcoded passwords or API keys
|
||||
- [ ] Uses `--chown` when copying files for non-root user
|
||||
|
||||
### Directory & Paths (High Priority)
|
||||
- [ ] `WORKDIR` uses absolute paths (not relative)
|
||||
- [ ] No use of `cd` in RUN commands
|
||||
- [ ] `.dockerignore` file present
|
||||
- [ ] Build context is minimal (excludes unnecessary files)
|
||||
|
||||
### Layer Optimization (Medium Priority)
|
||||
- [ ] RUN commands combined where logical (using `&&`)
|
||||
- [ ] Package manager cache cleaned (apt, apk, yum)
|
||||
- [ ] Dependency files copied before source code (for better caching)
|
||||
- [ ] Multi-line commands use backslash continuation
|
||||
- [ ] No unnecessary layers created
|
||||
|
||||
### Package Management (High Priority)
|
||||
- [ ] Package versions pinned (apt-get, apk, yum)
|
||||
- [ ] Package cache cleaned after installation
|
||||
- [ ] Uses `--no-install-recommends` for apt-get
|
||||
- [ ] Uses `--virtual` for build dependencies in alpine
|
||||
- [ ] Python: Versions pinned in requirements.txt
|
||||
- [ ] Node: Uses `npm ci` instead of `npm install`
|
||||
|
||||
### Best Practices (Medium Priority)
|
||||
- [ ] `HEALTHCHECK` instruction defined
|
||||
- [ ] Uses `COPY` instead of `ADD` (unless extracting archives)
|
||||
- [ ] `CMD` and `ENTRYPOINT` use JSON notation
|
||||
- [ ] Labels included (maintainer, version, description)
|
||||
- [ ] Appropriate EXPOSE directives for documented ports
|
||||
- [ ] ENV variables clearly defined
|
||||
- [ ] Build args used for customization points
|
||||
|
||||
### Documentation (Low Priority)
|
||||
- [ ] Comments explain complex operations
|
||||
- [ ] Each stage has descriptive comment
|
||||
- [ ] Unusual patterns are documented
|
||||
- [ ] Maintainer/author documented in labels
|
||||
|
||||
## Hadolint Rule Reference
|
||||
|
||||
| Rule | Description | Severity | Check |
|
||||
|------|-------------|----------|-------|
|
||||
| DL3000 | Use absolute WORKDIR | Error | [ ] |
|
||||
| DL3001 | Some commands should not be used | Warning | [ ] |
|
||||
| DL3002 | Last USER should not be root | Error | [ ] |
|
||||
| DL3003 | Use WORKDIR to switch directories | Warning | [ ] |
|
||||
| DL3006 | Always tag image explicitly | Warning | [ ] |
|
||||
| DL3007 | Using latest is prone to errors | Warning | [ ] |
|
||||
| DL3008 | Pin versions in apt-get install | Warning | [ ] |
|
||||
| DL3009 | Delete apt-get lists after installing | Info | [ ] |
|
||||
| DL3013 | Pin versions in pip | Warning | [ ] |
|
||||
| DL3014 | Use -y flag with apt-get | Warning | [ ] |
|
||||
| DL3015 | Avoid additional packages | Info | [ ] |
|
||||
| DL3016 | Pin versions in npm | Warning | [ ] |
|
||||
| DL3018 | Pin versions in apk add | Warning | [ ] |
|
||||
| DL3019 | Use --no-cache with apk add | Info | [ ] |
|
||||
| DL3020 | Use COPY instead of ADD | Error | [ ] |
|
||||
| DL3022 | COPY --from should reference stage | Error | [ ] |
|
||||
| DL3025 | Use JSON for CMD and ENTRYPOINT | Warning | [ ] |
|
||||
|
||||
## Docker Compose Validation Checklist
|
||||
|
||||
### Modern Syntax (Critical)
|
||||
- [ ] NO `version` field present (obsolete since Compose v2.27.0)
|
||||
- [ ] File uses modern Compose Specification syntax
|
||||
- [ ] Compatible with Docker Compose v2.27.0+
|
||||
|
||||
### Service Configuration (High Priority)
|
||||
- [ ] All services have specific image tags (no `:latest`)
|
||||
- [ ] Restart policies defined (`restart: unless-stopped`)
|
||||
- [ ] Service dependencies specified (`depends_on`)
|
||||
- [ ] Container names specified (optional but recommended)
|
||||
- [ ] All services have descriptive names (kebab-case)
|
||||
|
||||
### Health Checks (High Priority)
|
||||
- [ ] Critical services have health checks
|
||||
- [ ] Health check intervals are reasonable
|
||||
- [ ] Health check timeout values appropriate
|
||||
- [ ] Start period allows for initialization
|
||||
- [ ] Retries configured for reliability
|
||||
|
||||
### Resource Management (Medium Priority)
|
||||
- [ ] Resource limits defined (memory, CPU)
|
||||
- [ ] Resource reservations specified
|
||||
- [ ] PID limits set (if applicable)
|
||||
- [ ] Ulimits configured (if needed)
|
||||
|
||||
### Networking (High Priority)
|
||||
- [ ] Custom networks defined (not default bridge)
|
||||
- [ ] Network drivers specified
|
||||
- [ ] Network isolation implemented
|
||||
- [ ] Port mappings use host IP when needed
|
||||
- [ ] Internal networks used for backend services
|
||||
|
||||
### Volumes & Persistence (High Priority)
|
||||
- [ ] Named volumes used for persistence
|
||||
- [ ] Volume drivers specified
|
||||
- [ ] Bind mounts use absolute paths
|
||||
- [ ] Volume permissions appropriate
|
||||
- [ ] No sensitive data in bind mounts
|
||||
- [ ] Volumes section defines named volumes
|
||||
|
||||
### Environment & Configuration (Critical)
|
||||
- [ ] Environment variables properly defined
|
||||
- [ ] No hardcoded secrets in compose file
|
||||
- [ ] `.env` file used for configuration
|
||||
- [ ] Secrets managed with Docker secrets or external
|
||||
- [ ] ENV files specified with `env_file`
|
||||
|
||||
### Security (Critical)
|
||||
- [ ] No `privileged: true` (unless absolutely necessary)
|
||||
- [ ] Capabilities properly configured
|
||||
- [ ] User/group specified for services
|
||||
- [ ] Read-only root filesystem (where applicable)
|
||||
- [ ] Security options configured
|
||||
- [ ] AppArmor/SELinux profiles defined
|
||||
|
||||
### Logging (Medium Priority)
|
||||
- [ ] Logging drivers configured
|
||||
- [ ] Log rotation configured
|
||||
- [ ] Log size limits set
|
||||
- [ ] Appropriate log drivers for environment
|
||||
|
||||
### Build Configuration (if using build)
|
||||
- [ ] Build context clearly specified
|
||||
- [ ] Build args defined if needed
|
||||
- [ ] Dockerignore file present
|
||||
- [ ] Target stage specified for multi-stage
|
||||
- [ ] Cache from configured for faster builds
|
||||
|
||||
## Multi-Stage Build Specific Checks
|
||||
|
||||
### Stage Structure
|
||||
- [ ] Build stage uses full toolchain image
|
||||
- [ ] Build stage installs ALL dependencies
|
||||
- [ ] Build stage compiles/builds artifacts
|
||||
- [ ] Runtime stage uses minimal image
|
||||
- [ ] Runtime stage copies only artifacts
|
||||
- [ ] Runtime stage installs only runtime deps
|
||||
|
||||
### Node.js Multi-Stage
|
||||
- [ ] Build stage: `npm ci` (not `npm install`)
|
||||
- [ ] Build stage: `npm run build`
|
||||
- [ ] Build stage: `npm run test` (optional)
|
||||
- [ ] Runtime stage: `npm ci --only=production`
|
||||
- [ ] Runtime stage: Copies from builder `dist/build` folder
|
||||
- [ ] Runtime stage: Uses alpine variant
|
||||
|
||||
### Python Multi-Stage
|
||||
- [ ] Build stage: Compiles wheels
|
||||
- [ ] Build stage: Installs build dependencies
|
||||
- [ ] Build stage: Creates virtual environment
|
||||
- [ ] Runtime stage: Installs pre-built wheels
|
||||
- [ ] Runtime stage: Minimal Python image (alpine/slim)
|
||||
- [ ] Runtime stage: No compiler or build tools
|
||||
|
||||
### Go Multi-Stage
|
||||
- [ ] Build stage: Full Go image
|
||||
- [ ] Build stage: CGO_ENABLED=0 for static binary
|
||||
- [ ] Build stage: Builds binary
|
||||
- [ ] Runtime stage: `scratch` or `distroless`
|
||||
- [ ] Runtime stage: Only binary copied
|
||||
- [ ] Runtime stage: Certificates copied if needed
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Image Security
|
||||
- [ ] Base images scanned for vulnerabilities
|
||||
- [ ] No images older than 6 months without review
|
||||
- [ ] Images from trusted sources only
|
||||
- [ ] Image digests used for critical deployments
|
||||
- [ ] Regular security updates applied
|
||||
|
||||
### Runtime Security
|
||||
- [ ] Runs as non-root user (UID > 0)
|
||||
- [ ] Minimal capabilities granted
|
||||
- [ ] No unnecessary privileges
|
||||
- [ ] Read-only root filesystem where possible
|
||||
- [ ] Temporary directories properly configured
|
||||
|
||||
### Network Security
|
||||
- [ ] Only necessary ports exposed
|
||||
- [ ] Internal networks for backend communication
|
||||
- [ ] No host network mode (unless required)
|
||||
- [ ] Firewall rules configured
|
||||
- [ ] TLS/SSL for external communications
|
||||
|
||||
### Data Security
|
||||
- [ ] No secrets in image layers
|
||||
- [ ] Secrets managed via secrets management
|
||||
- [ ] Sensitive volumes properly protected
|
||||
- [ ] Encryption at rest configured
|
||||
- [ ] Backup strategy for persistent data
|
||||
|
||||
### Access Control
|
||||
- [ ] Least privilege principle applied
|
||||
- [ ] Appropriate user permissions
|
||||
- [ ] No root access to containers
|
||||
- [ ] Host resources properly isolated
|
||||
- [ ] Volume mounts restricted
|
||||
|
||||
## CI/CD Integration Checklist
|
||||
|
||||
### Pre-commit Validation
|
||||
- [ ] Pre-commit hook validates Dockerfiles
|
||||
- [ ] Pre-commit hook checks Compose files
|
||||
- [ ] Hook checks for obsolete version field
|
||||
- [ ] Hook runs Hadolint/DCLint
|
||||
- [ ] Hook prevents commits with critical issues
|
||||
|
||||
### Pipeline Validation
|
||||
- [ ] Hadolint runs on all Dockerfiles
|
||||
- [ ] Docker Compose config validation
|
||||
- [ ] DCLint runs on Compose files
|
||||
- [ ] Security scanning integrated (Trivy, Snyk)
|
||||
- [ ] Build tests before merge
|
||||
- [ ] Automated PR comments with issues
|
||||
|
||||
### Deployment Validation
|
||||
- [ ] Validation runs before deployment
|
||||
- [ ] Rollback on validation failure
|
||||
- [ ] Health checks verified post-deployment
|
||||
- [ ] Smoke tests after deployment
|
||||
- [ ] Monitoring alerts configured
|
||||
|
||||
## Common Issue Quick Reference
|
||||
|
||||
### ❌ Using :latest Tag
|
||||
**Check:** `grep -r ":latest" Dockerfile docker-compose.yml`
|
||||
**Fix:** Pin specific version (e.g., `nginx:1.24-alpine`)
|
||||
|
||||
### ❌ Obsolete Version Field
|
||||
**Check:** `grep "^version:" docker-compose.yml`
|
||||
**Fix:** Remove the entire `version:` line
|
||||
|
||||
### ❌ Running as Root
|
||||
**Check:** `grep "^USER" Dockerfile | tail -1`
|
||||
**Fix:** Add `USER <non-root-user>` before CMD/ENTRYPOINT
|
||||
|
||||
### ❌ No Multi-Stage Build
|
||||
**Check:** `grep -c "^FROM" Dockerfile`
|
||||
**Fix:** Implement at least 2 stages
|
||||
|
||||
### ❌ Package Cache Not Cleaned
|
||||
**Check:** Look for apt/apk without cleanup
|
||||
**Fix:** Add `rm -rf /var/lib/apt/lists/*` or `--no-cache`
|
||||
|
||||
### ❌ Using ADD Instead of COPY
|
||||
**Check:** `grep "^ADD" Dockerfile`
|
||||
**Fix:** Replace with `COPY` unless extracting archives
|
||||
|
||||
### ❌ No Health Check
|
||||
**Check:** `grep "HEALTHCHECK" Dockerfile`
|
||||
**Fix:** Add appropriate HEALTHCHECK instruction
|
||||
|
||||
### ❌ No Restart Policy
|
||||
**Check:** `grep "restart:" docker-compose.yml`
|
||||
**Fix:** Add `restart: unless-stopped` to services
|
||||
|
||||
## Validation Priority Matrix
|
||||
|
||||
| Priority | Dockerfile | Docker Compose | Multi-Stage | Security |
|
||||
|----------|-----------|----------------|-------------|----------|
|
||||
| CRITICAL | No :latest, USER set | No version field | N/A | Non-root user |
|
||||
| HIGH | HEALTHCHECK, WORKDIR | Restart policy, Health checks | 2+ stages | No secrets |
|
||||
| MEDIUM | Layer optimization | Resource limits | Named stages | Minimal image |
|
||||
| LOW | Comments, Labels | Logging config | Optimization | Hardening |
|
||||
|
||||
## Tool-Specific Validation
|
||||
|
||||
### Hadolint Configuration (.hadolint.yaml)
|
||||
```yaml
|
||||
ignored:
|
||||
- DL3008 # Pin apt versions (too strict for some use cases)
|
||||
override:
|
||||
error:
|
||||
- DL3002 # Last USER must not be root
|
||||
- DL3020 # Use COPY not ADD
|
||||
trustedRegistries:
|
||||
- docker.io
|
||||
- ghcr.io
|
||||
- gcr.io
|
||||
```
|
||||
|
||||
### DCLint Configuration (.dclintrc.json)
|
||||
```json
|
||||
{
|
||||
"rules": {
|
||||
"no-version-field": "error",
|
||||
"require-quotes": "warning",
|
||||
"no-duplicate-keys": "error"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Validation Commands
|
||||
|
||||
```bash
|
||||
# Validate Dockerfile
|
||||
hadolint Dockerfile
|
||||
|
||||
# Validate Docker Compose
|
||||
docker compose config --quiet
|
||||
|
||||
# Check for obsolete version field
|
||||
grep "^version:" docker-compose.yml
|
||||
|
||||
# Count FROM statements (multi-stage check)
|
||||
grep -c "^FROM" Dockerfile
|
||||
|
||||
# Check final USER
|
||||
grep "^USER" Dockerfile | tail -1
|
||||
|
||||
# Find :latest tags
|
||||
grep -r ":latest" .
|
||||
|
||||
# Full validation
|
||||
./validate-docker.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Use this checklist to ensure comprehensive validation of all Docker configurations.**
|
||||
Reference in New Issue
Block a user