bash scripts/dockerfile-validate.sh Dockerfile

┌─────────────────────────────────────────────────────────┐
│  Auto-Install (if needed)                               │
│  ├─> Check for hadolint and Checkov                     │
│  ├─> Install in Python venvs if not found               │
│  └─> Set TEMP_INSTALL=true (triggers cleanup on exit)   │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [1/4] Syntax Validation (hadolint)                     │
│  ├─> Dockerfile syntax checking                         │
│  ├─> Instruction validation                             │
│  ├─> Shell script validation (via ShellCheck)           │
│  └─> 100+ built-in linting rules                        │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [2/4] Security Scan (Checkov)                          │
│  ├─> Security policy validation                         │
│  ├─> Hardcoded secret detection                         │
│  ├─> Port exposure checks                               │
│  ├─> USER directive validation                          │
│  └─> 50+ security policies                              │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [3/4] Best Practices Validation (custom)               │
│  ├─> Base image tag validation (:latest check)          │
│  ├─> USER directive enforcement (non-root)              │
│  ├─> HEALTHCHECK presence                               │
│  ├─> Layer efficiency (RUN command count)               │
│  ├─> Package cache cleanup verification                 │
│  ├─> Hardcoded secrets detection                        │
│  └─> COPY ordering for build cache efficiency           │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [4/4] Optimization Analysis (custom)                   │
│  ├─> Base image size analysis (Alpine suggestions)      │
│  ├─> Multi-stage build opportunities                    │
│  ├─> Layer count optimization                           │
│  ├─> .dockerignore file check                           │
│  └─> Build structure recommendations                    │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  Auto-Cleanup (bash trap - always runs)                 │
│  └─> Remove temp venvs if TEMP_INSTALL=true             │
└─────────────────────────────────────────────────────────┘

undefined

**Workflow:**

```bash

**Common Issues Detected:**

**DL-prefixed rules (hadolint-specific):**
- `DL3000` - Use absolute WORKDIR paths
- `DL3001` - For some bash commands make no sense in a Docker container
- `DL3002` - Last USER should not be root
- `DL3003` - Use WORKDIR to switch directories
- `DL3004` - Do not use sudo
- `DL3006` - Always tag image versions (avoid :latest)
- `DL3007` - Using latest is not recommended
- `DL3008` - Pin versions in apt-get install
- `DL3009` - Delete apt-cache after installing
- `DL3013` - Pin versions in pip install
- `DL3014` - Use -y switch for apt-get
- `DL3015` - Avoid additional packages with apt-get
- `DL3016` - Pin versions in npm install
- `DL3018` - Pin versions in apk add
- `DL3019` - Use --no-cache with apk add
- `DL3020` - Use COPY instead of ADD for files
- `DL3021` - COPY from previous stages should reference by name
- `DL3022` - COPY --from should reference a previously defined FROM alias
- `DL3025` - Use JSON notation for CMD and ENTRYPOINT
- `DL3059` - Multiple consecutive RUN instructions (combine for layer efficiency)

**SC-prefixed rules (ShellCheck for RUN commands):**
- `SC1091` - Not following sourced files
- `SC2046` - Quote to prevent word splitting
- `SC2086` - Double quote to prevent globbing
- `SC2164` - Use cd ... || exit for error handling

**Rule Severity Levels:**
- **error** - Will likely cause build failure or runtime issues
- **warning** - Violates best practices, should be fixed
- **info** - Suggestions for improvement
- **style** - Code style preferences

**Best Practices:**
- Run hadolint before every docker build
- Integrate into CI/CD pipelines
- Configure .hadolint.yaml for project-specific rules
- Address errors before warnings
- Use inline ignore comments sparingly with justification

undefined

**Workflow:**

```bash

**Common Security Checks:**

**General Security:**
- `CKV_DOCKER_1` - Ensure port 22 (SSH) is not exposed
- `CKV_DOCKER_2` - Ensure HEALTHCHECK instruction exists
- `CKV_DOCKER_3` - Ensure user is created and used (not root)
- `CKV_DOCKER_4` - Ensure ADD is not used (prefer COPY)
- `CKV_DOCKER_5` - Ensure update without install is not used alone
- `CKV_DOCKER_6` - Ensure SHELL instruction uses -o pipefail
- `CKV_DOCKER_7` - Ensure base image uses specific version tag
- `CKV_DOCKER_8` - Ensure last USER is not root
- `CKV_DOCKER_9` - Ensure apt-get dist-upgrade is not used
- `CKV_DOCKER_10` - Ensure yum update is not used alone

**Package Management:**
- Check for missing package manager cache cleanup
- Verify version pinning for installed packages
- Detect use of --no-install-recommends for apt-get

**Secrets Detection:**
- Scan for potential secrets in ENV or ARG
- Detect hardcoded credentials
- Identify exposed API keys or tokens

**Output Formats:**
- `cli` - Human-readable console output (default)
- `json` - JSON format for programmatic parsing
- `sarif` - SARIF format for IDE integration
- `gitlab_sast` - GitLab security dashboard format
- `junitxml` - JUnit XML for CI integration

**Understanding Results:**

1  | FROM node:18
20 | CMD ["node", "server.js"]

**Suppressing False Positives:**

Add inline comments to suppress specific checks:

```dockerfile

**Exit Codes:**
- `0` - All checks passed
- `1` - One or more checks failed

**Best Practices:**
- Run Checkov after hadolint (syntax first, then security)
- Address high-severity findings first
- Document all suppressions with clear justification
- Integrate into CI/CD pipelines
- Review new policies regularly
- Combine with image vulnerability scanning (e.g., trivy, snyk)

undefined

**2. Multi-Stage Build Detection:**
```bash

**3. USER Directive Check:**
```bash

**4. HEALTHCHECK Presence:**
```bash

**5. Layer Efficiency:**
```bash

**6. Package Manager Cache Cleanup:**
```bash

**Best Practices Checklist:**

**Base Images:**
- ✓ Use specific version tags, not :latest
- ✓ Consider Alpine variants for smaller size
- ✓ Pin to digest for reproducibility
- ✓ Use official images from verified publishers
- ✓ Scan base images for vulnerabilities

**Layer Optimization:**
- ✓ Combine related RUN commands with &&
- ✓ Order instructions from least to most frequently changing
- ✓ COPY package files before source code
- ✓ Clean up package manager caches in same layer
- ✓ Use .dockerignore to exclude unnecessary files

**Security:**
- ✓ Run as non-root user (USER directive)
- ✓ Don't install unnecessary packages (--no-install-recommends)
- ✓ Don't hardcode secrets (use build secrets or runtime configs)
- ✓ Use COPY instead of ADD (unless extracting archives)
- ✓ Avoid curl | bash installations

**Multi-Stage Builds:**
- ✓ Separate build dependencies from runtime
- ✓ Name stages explicitly (FROM ... AS stagename)
- ✓ Copy only necessary artifacts between stages
- ✓ Use minimal runtime base images

**Runtime Configuration:**
- ✓ Define HEALTHCHECK for services
- ✓ Use exec form for ENTRYPOINT and CMD
- ✓ Set WORKDIR to absolute paths
- ✓ Document exposed ports with EXPOSE
- ✓ Add metadata with LABEL

**Build Performance:**
- ✓ Leverage build cache by proper instruction ordering
- ✓ Use BuildKit features (--mount=type=cache)
- ✓ Minimize context size with .dockerignore
- ✓ Parallelize multi-stage builds when possible

undefined

**2. Layer Optimization:**
```dockerfile

**3. Build Cache Efficiency:**
```dockerfile

**4. Multi-Stage Build Opportunities:**
```dockerfile

**Optimization Metrics:**
- **Layer count:** Fewer layers = smaller image
- **Image size:** Minimal base + cleanup = smaller download
- **Build time:** Cache hits + parallel stages = faster builds
- **Attack surface:** Fewer packages = fewer vulnerabilities

**Reference Documentation:**

Load detailed best practices:

undefined

undefined

**Benefits of .dockerignore:**
- Reduces build context size
- Faster builds (less data to transfer)
- Prevents accidental secret leaks
- Excludes development-only files

**Best Practices:**
- Always create .dockerignore for non-trivial projects
- Include .git directory
- Exclude local configuration files (.env, *.local)
- Exclude documentation unless needed in image
- Exclude test files and test data
- Pattern syntax similar to .gitignore

undefined

**Minimum Versions:**
- hadolint: >= 2.12.0
- Checkov: Latest (for newest policies)
- Python: >= 3.8 (for temporary installations)
- Docker: >= 20.10 (optional, for testing builds)

**Testing Auto-Install and Cleanup:**

To test the temporary installation and cleanup functionality even when tools are already installed:

```bash

This will:
1. Install hadolint and Checkov in temporary Python venvs
2. Run all validations using the temporary installations
3. Clean up temporary venvs on exit (success or failure)

Solution: Move ARG that defines base image tag before FROM
ARG VERSION=18
FROM node:${VERSION}

Solution: Check instruction spelling (RUN, COPY, FROM, etc.)
Common typos: RUNS, COPIES, FRUM

Solution: Add set -e or check individual command success
RUN apt-get update && apt-get install -y package || exit 1

Solution: Check file path is relative to build context
Verify file exists and not excluded by .dockerignore

Solution: Use build secrets (BuildKit)

**Performance: Slow builds**

undefined

undefined

undefined

User: "Validate my Dockerfile"

Steps:
1. Read the Dockerfile using Read tool to understand structure
2. Run validation script: bash scripts/dockerfile-validate.sh Dockerfile
3. Review output from all 4 stages (hadolint, Checkov, best practices, optimization)
4. Summarize findings organized by severity (critical → low)
5. Use Read tool to load relevant reference files:
   - Read references/security_checklist.md (if security issues found)
   - Read references/optimization_guide.md (if optimization issues found)
   - Read references/docker_best_practices.md (if best practice issues found)
6. Propose specific fixes with code examples based on reference content
7. Ask user: "Would you like me to apply these fixes?"
8. Apply fixes if user approves

User: "Check all Dockerfiles in my project"

Steps:
1. Find all Dockerfile* files
2. Validate each sequentially
3. Aggregate results
4. Identify common issues across files
5. Provide unified report
6. Suggest project-wide improvements

User: "Security audit my Dockerfile"

Steps:
1. Run Checkov security scan
2. Run hadolint for security rules (DL3* series)
3. Check for hardcoded secrets
4. Verify USER directive
5. Check base image vulnerabilities
6. Provide security-focused report
7. Prioritize critical findings

User: "How can I optimize my Dockerfile?"

Steps:
1. Analyze current layer structure
2. Identify multi-stage opportunities
3. Check build cache efficiency
4. Suggest base image alternatives
5. Calculate potential size savings
6. Provide before/after comparison
7. Implement optimizations if approved