@hybridlabor-api/aos 4.7.2 → 4.9.0

package/skills/global_config/dockerfile-validator/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: dockerfile-validator
+description: Validate, lint, audit, or scan a Dockerfile for security and best practices.
+category: engineering-method
+source: cc-devops-skills
+date_added: "2026-09-25"
+---
+
+# Dockerfile Validator
+
+Validate Dockerfiles with deterministic stages, clear severity reporting, and explicit fallbacks when tools or network access are constrained.
+
+## Trigger Phrases
+
+Use this skill when the user asks for tasks like:
+- "validate this Dockerfile"
+- "lint/check my Dockerfile"
+- "security scan Dockerfile"
+- "optimize Docker image size/build time"
+- "review Dockerfile before merge"
+- "find issues in Dockerfile.prod/Dockerfile.dev"
+
+## Use / Do Not Use
+
+Use this skill for:
+- Syntax and lint validation
+- Security and secrets checks
+- Best-practice and performance review
+- Dockerfile hardening before CI/CD or production
+
+Do not use this skill for:
+- Generating a new Dockerfile from scratch (use `dockerfile-generator`)
+- Running containers, debugging runtime behavior, or image registry operations
+
+## Local Files In This Skill
+
+- Validator script: `scripts/dockerfile-validate.sh`
+- References:
+  - `references/security_checklist.md`
+  - `references/optimization_guide.md`
+  - `references/docker_best_practices.md`
+- Example Dockerfiles: `examples/*.Dockerfile`
+
+## Deterministic Execution Flow (Required)
+
+Run these steps in order. Do not skip steps unless a documented fallback branch applies.
+
+### 1. Preflight and Path Setup
+
+Assume repo root as working directory:
+
+```bash
+cd /path/to/repo
+SKILL_DIR="devops-skills-plugin/skills/dockerfile-validator"
+TARGET_DOCKERFILE="Dockerfile"   # replace when user provides a path
+```
+
+Validate inputs before running tools:
+
+```bash
+test -f "$SKILL_DIR/scripts/dockerfile-validate.sh"
+test -f "$TARGET_DOCKERFILE"
+```
+
+If either check fails, stop and report the exact missing path.
+
+### 2. Read the Target Dockerfile Explicitly
+
+Use explicit file-read commands (not abstract "Read tool" wording):
+
+```bash
+sed -n '1,220p' "$TARGET_DOCKERFILE"
+```
+
+If needed for long files:
+
+```bash
+sed -n '220,440p' "$TARGET_DOCKERFILE"
+```
+
+### 3. Run Validation Script
+
+Primary command:
+
+```bash
+bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE"
+```
+
+Optional captured run for structured reporting:
+
+```bash
+bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE" | tee /tmp/dockerfile-validator.out
+```
+
+### 4. Classify Findings by Severity (Standard)
+
+Use this standard severity model:
+
+- `Critical`
+  - Hardcoded secrets/credentials
+  - Explicit root runtime with high-risk context
+  - High-impact security policy failures
+- `High`
+  - Checkov failures for container hardening
+  - hadolint errors likely to cause insecure/unreliable builds
+  - Missing or unsafe runtime-user posture (`USER`)
+- `Medium`
+  - `:latest` image tags, missing pinning, cache-cleanup misses
+  - Build cache inefficiency and layered install anti-patterns
+- `Low`
+  - Style/info guidance and non-blocking optimization suggestions
+
+### 5. No-Issue Fast Path (Required)
+
+If validation has no actionable findings:
+- Return a concise pass summary.
+- Do **not** open reference files.
+- Do **not** generate fix diffs.
+
+Use fast path when all are true:
+- Script reports overall pass.
+- No security failures.
+- No error/warning findings requiring user action.
+
+### 6. Reference Loading Rules (Only When Findings Exist)
+
+Only read references that match actual findings. Read each required file once.
+
+Issue-to-reference mapping:
+
+| Issue category | Trigger examples | Read this file |
+|---|---|---|
+| Secrets, root user, exposed sensitive ports, hardening gaps | `CKV_DOCKER_*`, hardcoded token/password, root runtime | `references/security_checklist.md` |
+| Image size, layer count, multi-stage opportunities, cache efficiency, `.dockerignore` gaps | too many `RUN`, single-stage with build deps, cache misses | `references/optimization_guide.md` |
+| Tag pinning, instruction usage, COPY vs ADD, WORKDIR/CMD/ENTRYPOINT conventions | `:latest`, unpinned packages, instruction-level best practices | `references/docker_best_practices.md` |
+
+Explicit read commands:
+
+```bash
+sed -n '1,220p' "$SKILL_DIR/references/security_checklist.md"
+sed -n '1,220p' "$SKILL_DIR/references/optimization_guide.md"
+sed -n '1,220p' "$SKILL_DIR/references/docker_best_practices.md"
+```
+
+For targeted extraction:
+
+```bash
+rg -n "USER|secrets|EXPOSE|HEALTHCHECK" "$SKILL_DIR/references/security_checklist.md"
+rg -n "multi-stage|cache|layer|dockerignore" "$SKILL_DIR/references/optimization_guide.md"
+rg -n "FROM|COPY|ADD|WORKDIR|CMD|ENTRYPOINT|latest" "$SKILL_DIR/references/docker_best_practices.md"
+```
+
+### 7. Produce Standard Report Output
+
+Use this template for every non-fast-path run:
+
+```markdown
+## Dockerfile Validation Report
+- Target: <path>
+- Command: `bash <skill-script> <target>`
+- Overall result: PASS | FAIL | PARTIAL (fallback)
+
+### Critical
+- <issue or `None`>
+
+### High
+- <issue or `None`>
+
+### Medium
+- <issue or `None`>
+
+### Low
+- <issue or `None`>
+
+### Recommended Fixes
+- <specific code-level fix per actionable issue>
+
+### References Used
+- <list only files actually read>
+
+### Fallbacks Used
+- `None` or exact fallback branch + reason
+```
+
+### 8. Offer Fix Application
+
+After reporting:
+- Ask whether to apply fixes.
+- If user approves, patch the Dockerfile and rerun validation.
+
+## Fallback Behavior (Explicit)
+
+When the primary script cannot complete, use deterministic fallback branches and report them.
+
+### Fallback A: Python/Tool Install Constraint
+
+Condition:
+- Script exits with tool-install failure (for example Python missing, package install blocked, or restricted environment).
+
+Action:
+1. Report primary failure and why.
+2. Run manual minimum checks:
+
+```bash
+# Basic syntax signal (if Docker is available)
+DOCKERFILE_DIR="$(dirname "$TARGET_DOCKERFILE")"
+docker build --no-cache -f "$TARGET_DOCKERFILE" "$DOCKERFILE_DIR"
+
+# High-value static checks
+grep -nEi "^[[:space:]]*FROM[[:space:]]+.*:latest" "$TARGET_DOCKERFILE" || true
+grep -nEi "^[[:space:]]*(ENV|ARG)[[:space:]].*(password|secret|token|api[_-]?key)[[:space:]]*=" "$TARGET_DOCKERFILE" || true
+grep -nEi "^[[:space:]]*USER[[:space:]]+(root|0(:0)?)$" "$TARGET_DOCKERFILE" || true
+grep -nEi "^[[:space:]]*HEALTHCHECK[[:space:]]+" "$TARGET_DOCKERFILE" || true
+```
+
+3. Classify output with `PARTIAL` result and clearly label skipped checks.
+
+### Fallback B: hadolint Not Available but Docker Available
+
+Use hadolint container image:
+
+```bash
+docker run --rm -i hadolint/hadolint < "$TARGET_DOCKERFILE"
+```
+
+### Fallback C: No Docker, No hadolint/checkov
+
+Run only manual regex-based checks (Fallback A step 2), clearly mark as `PARTIAL`, and state which scanners were skipped.
+
+## Quick Command Set
+
+### Validate one Dockerfile
+
+```bash
+cd /path/to/repo
+bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile
+```
+
+### Validate alternate file
+
+```bash
+cd /path/to/repo
+bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile.prod
+```
+
+### Validate skill examples
+
+```bash
+cd /path/to/repo/devops-skills-plugin/skills/dockerfile-validator
+bash scripts/dockerfile-validate.sh examples/good-example.Dockerfile
+bash scripts/dockerfile-validate.sh examples/security-issues.Dockerfile
+```
+
+### Run regression checks (CI entrypoint)
+
+```bash
+cd /path/to/repo
+bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh
+```
+
+Optional strict mode for CI environments that must enforce ShellCheck:
+
+```bash
+STRICT_SHELLCHECK=true bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh
+```
+
+## Progressive Disclosure Rules
+
+- Always read the target Dockerfile first.
+- Do not read any reference files unless findings require them.
+- Read only the matching reference file(s) from the issue-to-reference mapping.
+- Do not reread the same reference unless new issue categories appear.
+
+## Done Criteria
+
+Consider this skill execution complete only when all conditions below are satisfied:
+
+- Trigger matched a Dockerfile validation/lint/security/optimization request.
+- Target Dockerfile path was explicitly verified.
+- Validation command (or explicit fallback) was executed.
+- Findings were reported using severity buckets (`Critical`, `High`, `Medium`, `Low`).
+- Reference usage matched issue categories and was explicitly listed.
+- No-issue fast path skipped unnecessary reference reads.
+- If fixes were applied, validation was rerun and final status reported.
+
+## Resources
+
+- Script: `scripts/dockerfile-validate.sh`
+- CI/regression entrypoint: `scripts/test_validate.sh`
+- Security reference: `references/security_checklist.md`
+- Optimization reference: `references/optimization_guide.md`
+- Best-practices reference: `references/docker_best_practices.md`
+- Examples: `examples/good-example.Dockerfile`, `examples/bad-example.Dockerfile`, `examples/security-issues.Dockerfile`, `examples/python-optimized.Dockerfile`, `examples/golang-distroless.Dockerfile`
+
+## Source Links
+
+- [Docker Build Best Practices](https://docs.docker.com/build/building/best-practices/)
+- [Dockerfile Reference](https://docs.docker.com/reference/dockerfile/)
+- [Checkov Dockerfile Scanning](https://www.checkov.io/7.Scan%20Examples/Dockerfile.html)
+- [hadolint](https://github.com/hadolint/hadolint)

package/skills/global_config/dockerfile-validator/examples/.dockerignore.example

@@ -0,0 +1,34 @@
+# VCS
+.git
+.gitignore
+
+# Local environment and secrets
+.env
+.env.*
+*.pem
+*.key
+
+# Build and dependency artifacts
+node_modules/
+dist/
+build/
+target/
+venv/
+.venv/
+__pycache__/
+*.pyc
+
+# Logs and temp files
+*.log
+*.tmp
+tmp/
+
+# Tooling and editor files
+.idea/
+.vscode/
+.DS_Store
+
+# Docker-related files not needed in image
+Dockerfile*
+docker-compose*.yml
+.dockerignore

package/skills/global_config/dockerfile-validator/examples/bad-example.Dockerfile

@@ -0,0 +1,37 @@
+# Bad Example - Demonstrates common mistakes and anti-patterns
+# DO NOT USE THIS IN PRODUCTION
+
+# Issue 1: Using :latest tag (unpredictable, not reproducible)
+FROM ubuntu:latest
+
+# Issue 2: Running as root (security risk)
+# Issue 3: No WORKDIR set (unclear where commands run)
+
+# Issue 4: Separate RUN commands (creates unnecessary layers)
+RUN apt-get update
+RUN apt-get install -y curl
+RUN apt-get install -y vim
+RUN apt-get install -y git
+# Issue 5: No cache cleanup (increases image size)
+
+# Issue 6: Using shell form instead of exec form
+WORKDIR app
+
+# Issue 7: Copying everything before installing dependencies (poor caching)
+COPY . .
+
+# Issue 8: No version pinning for packages
+RUN pip install flask
+
+# Issue 9: Potential secret exposure
+ENV API_KEY=secret123
+ENV PASSWORD=admin
+
+# Issue 10: Exposing SSH port (security risk)
+EXPOSE 22
+EXPOSE 80
+
+# Issue 11: No HEALTHCHECK defined
+# Issue 12: No USER directive (runs as root)
+# Issue 13: Shell form instead of exec form (poor signal handling)
+CMD python app.py

package/skills/global_config/dockerfile-validator/examples/golang-distroless.Dockerfile

@@ -0,0 +1,50 @@
+# syntax=docker/dockerfile:1
+
+# Multi-stage Go Dockerfile with distroless runtime
+# Demonstrates minimal attack surface and optimal size
+
+# Build stage
+FROM golang:1.21-alpine AS builder
+
+# Install build dependencies
+# hadolint ignore=DL3018
+RUN apk add --no-cache git ca-certificates
+
+WORKDIR /src
+
+# Copy go mod files for dependency caching
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build static binary
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
+    -ldflags='-w -s -extldflags "-static"' \
+    -a \
+    -o /app/server \
+    ./cmd/server
+
+# Runtime stage - distroless (minimal, secure)
+# checkov:skip=CKV_DOCKER_2:Distroless runtime uses external liveness/readiness probes instead of in-container HEALTHCHECK.
+# checkov:skip=CKV_DOCKER_3:distroless:nonroot image already runs as a non-root user.
+FROM gcr.io/distroless/static-debian11:nonroot
+
+# Copy CA certificates for HTTPS
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+
+# Copy binary from builder
+COPY --from=builder /app/server /server
+
+# Expose port
+EXPOSE 8080
+
+# Already running as non-root (distroless:nonroot)
+# User is automatically set to uid:gid 65532:65532
+
+# Health check (limited in distroless, use external checks)
+# HEALTHCHECK not available in distroless
+
+# Exec form entrypoint
+ENTRYPOINT ["/server"]

package/skills/global_config/dockerfile-validator/examples/good-example.Dockerfile

@@ -0,0 +1,52 @@
+# syntax=docker/dockerfile:1
+
+# Example of a well-structured, secure, and optimized Dockerfile
+# This demonstrates Docker best practices for a Node.js application
+
+# Build stage - includes all build dependencies
+FROM node:21-alpine AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files first for better layer caching
+COPY package.json package-lock.json ./
+
+# Install dependencies with cache mount for faster rebuilds
+RUN --mount=type=cache,target=/root/.cache/npm \
+    npm ci --only=production
+
+# Copy application source
+COPY . .
+
+# Build the application (if needed)
+RUN npm run build
+
+# Runtime stage - minimal image with only necessary runtime dependencies
+FROM node:21-alpine AS runtime
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy built application and dependencies from builder stage
+COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs:nodejs /app/package.json ./
+
+# Switch to non-root user
+USER nodejs
+
+# Expose application port
+EXPOSE 3000
+
+# Add healthcheck for container monitoring
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD node -e "require('http').get('http://localhost:3000/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1); })"
+
+# Use exec form for better signal handling
+ENTRYPOINT ["node"]
+CMD ["dist/index.js"]

package/skills/global_config/dockerfile-validator/examples/python-optimized.Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+
+# Multi-stage Python Dockerfile with best practices
+# Optimized for size and security
+
+# Build stage
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+# hadolint ignore=DL3008
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for layer caching
+COPY requirements.txt ./
+
+# Install Python dependencies with cache mount
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --user --no-cache-dir -r requirements.txt
+
+# Runtime stage - minimal
+FROM python:3.12-slim AS runtime
+
+# Create non-root user
+RUN groupadd -r app && useradd -r -g app app
+
+WORKDIR /app
+
+# Copy Python packages from builder
+COPY --from=builder /root/.local /root/.local
+
+# Copy application code
+COPY --chown=app:app . .
+
+# Add local bin to PATH
+ENV PATH=/root/.local/bin:$PATH
+
+# Switch to non-root user
+USER app
+
+# Expose application port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s \
+    CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
+
+# Use exec form
+ENTRYPOINT ["python"]
+CMD ["-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

package/skills/global_config/dockerfile-validator/examples/security-issues.Dockerfile

@@ -0,0 +1,42 @@
+# Dockerfile with Intentional Security Issues
+# FOR TESTING VALIDATION ONLY - DO NOT USE IN PRODUCTION
+
+# Issue: Using :latest tag
+FROM python:latest
+
+# Issue: Running as root user throughout
+
+WORKDIR /app
+
+# Issue: Hardcoded secrets
+ENV DATABASE_PASSWORD=super_secret_password
+ENV API_TOKEN=abc123xyz789
+ARG SECRET_KEY=my_secret_key
+
+# Issue: Installing unnecessary packages, no version pinning
+RUN apt-get update && apt-get install -y \
+    openssh-server \
+    telnet \
+    ftp \
+    vim \
+    nano
+
+# Issue: No cache cleanup
+# (apt lists remain, increasing image size)
+
+# Issue: Using ADD instead of COPY
+ADD . /app
+
+# Issue: Installing packages without version pins
+RUN pip install flask requests sqlalchemy
+
+# Issue: Exposing SSH port
+EXPOSE 22
+EXPOSE 23
+EXPOSE 5000
+
+# Issue: No USER directive - will run as root
+# Issue: No HEALTHCHECK
+
+# Issue: Shell form (doesn't handle signals properly)
+CMD python app.py