zhongwei/gh-rknall-claude-skills-docker-validation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:51:57 +08:00
commit 7853bc6a00
6 changed files with 1711 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View 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
View 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
View 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
View 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
View 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
View 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.**