Container Image Optimizer

## Purpose & When-To-Use

**Trigger conditions:**
- Need to containerize an application with optimal image size
- Converting existing Dockerfile to multi-stage build
- Implementing container security best practices
- Reducing build times through layer caching optimization
- Scanning images for vulnerabilities before deployment

**Not for:**
- Kubernetes manifest generation (use kubernetes-manifest-generator skill)
- Complete deployment orchestration (use cloud-native-orchestrator agent)
- Runtime container orchestration (use Kubernetes or Docker Swarm)
- Container registry management

---

## Pre-Checks

**Time normalization:**
- Compute `NOW_ET` using NIST/time.gov semantics (America/New_York, ISO-8601): 2025-10-26T01:33:54-04:00
- Use `NOW_ET` for all citation access dates

**Input validation:**
- `application_language` must be one of: nodejs, python, go, java, rust
- `build_type` must be: development or production
- `base_image` if specified must be recognized (alpine, distroless, scratch, ubuntu, debian)
- `exposed_port` must be valid port number (1-65535)

**Source freshness:**
- Docker Multi-Stage Builds (accessed 2025-10-26T01:33:54-04:00): https://docs.docker.com/build/building/multi-stage/
- Docker Best Practices (accessed 2025-10-26T01:33:54-04:00): https://docs.docker.com/develop/dev-best-practices/
- Distroless Images (accessed 2025-10-26T01:33:54-04:00): https://github.com/GoogleContainerTools/distroless
- Trivy Scanner (accessed 2025-10-26T01:33:54-04:00): https://github.com/aquasecurity/trivy

**Decision thresholds:**
- T1 for basic multi-stage Dockerfile generation
- T2 for production optimization with security scanning and hardening

---

## Procedure

### T1: Basic Multi-Stage Dockerfile (≤2k tokens)

**Step 1: Generate multi-stage Dockerfile**
- Create build stage with language-specific toolchain
- Create runtime stage with minimal base image
- Copy only built artifacts (no source code or build tools)
- Set appropriate working directory and user

**Step 2: Create .dockerignore**
- Exclude common development files (.git, node_modules, __pycache__)
- Exclude CI/CD and documentation files
- Include only necessary application files

**Output:**
- Basic multi-stage Dockerfile
- .dockerignore file
- docker build command

**Abort conditions:**
- Unsupported language or framework
- Missing critical build information

---

### T2: Production-Optimized Container (≤6k tokens)

**All T1 steps plus:**

**Step 1: Advanced image optimization**
- Select minimal base image (distroless for production, alpine for tools)
- Optimize layer ordering (least-frequently-changed first)
- Combine RUN commands to reduce layers
- Use BuildKit cache mounts for package managers
- Implement build argument for versioning

**Step 2: Security hardening**
- Run as non-root user (create dedicated app user)
- Set read-only root filesystem where possible
- Drop unnecessary capabilities
- Scan image with Trivy or Grype
- Sign image layers (reference Sigstore/Cosign)

**Step 3: Build optimization**
- Configure BuildKit features (cache, secrets)
- Add health check instruction
- Set proper signal handling (STOPSIGNAL)
- Minimize final image size (target <100MB for simple apps)

**Step 4: Generate security report**
- Run vulnerability scanner
- Report CVEs by severity (Critical, High, Medium, Low)
- Provide remediation recommendations
- Check for exposed secrets in layers

**Output:**
- Production-optimized Dockerfile
- Security scan report with CVE details
- Build and scan commands
- Image size comparison (before/after optimization)

**Abort conditions:**
- Critical vulnerabilities found without patches available
- Base image not maintained or deprecated

---

### T3: Advanced Container Engineering (≤12k tokens)

**All T1 + T2 steps plus:**

**Step 1: Multi-architecture builds**
- Configure buildx for ARM64 and AMD64
- Platform-specific optimizations
- Cross-compilation setup

**Step 2: Advanced security**
- SBOM generation with Syft
- Image signing workflow
- Runtime security recommendations (Falco rules)

**Step 3: CI/CD integration**
- GitHub Actions / GitLab CI Dockerfile build pipeline
- Automated vulnerability scanning in CI
- Image promotion workflow

**Output:**
- Multi-arch Dockerfile
- CI/CD pipeline configuration
- SBOM and signed image artifacts
- Comprehensive security compliance report

---

## Decision Rules

**Base image selection:**
- **Distroless** (production): Minimal attack surface, no shell, smallest size
- **Alpine** (tooling needed): Small size, package manager available, shell for debugging
- **Scratch** (static binaries): Go/Rust compiled binaries, absolute minimal
- **Ubuntu/Debian** (compatibility): Legacy dependencies, broader package availability

**Language-specific optimizations:**
- **Node.js**: Use NODE_ENV=production, npm ci --only=production, multi-stage with build dependencies
- **Python**: Use pip install --no-cache-dir, requirements.txt pinning, compiled .pyc files
- **Go**: Static compilation (CGO_ENABLED=0), scratch base, single binary
- **Java**: JRE instead of JDK in runtime, jlink for minimal JRE, GraalVM native image
- **Rust**: Multi-stage with cargo build --release, strip binaries, musl for static linking

**Security scan thresholds:**
- **Critical CVEs**: Block build, require patching
- **High CVEs**: Warn, require review and exception approval
- **Medium/Low CVEs**: Report, track for future updates

**Ambiguity handling:**
- If base_image not specified → select distroless for production, alpine for development
- If package_manager unclear → infer from language (npm for nodejs, pip for python)
- If build process complex → request build script or package.json/requirements.txt

---

## Output Contract

**Required fields (all tiers):**
```dockerfile
# Dockerfile structure
FROM <build-base> AS builder
WORKDIR /build
COPY <dependencies-file> .
RUN <install-dependencies>
COPY . .
RUN <build-command>

FROM <runtime-base>
WORKDIR /app
COPY --from=builder /build/<artifacts> .
USER <non-root-user>
EXPOSE <port>
CMD [<entrypoint>]
```

```yaml
build_instructions:
  command: "docker build -t app:version ."
  buildkit_features: ["cache-mounts", "secrets"]
  estimated_build_time: "2-5 minutes"

image_metrics:
  final_size_mb: integer
  layer_count: integer
  optimization_ratio: "percentage reduction vs single-stage"
```

**Additional T2 fields:**
```yaml
security_report:
  scanner: "trivy | grype"
  scan_timestamp: "ISO-8601"
  vulnerabilities:
    critical: integer
    high: integer
    medium: integer
    low: integer
  recommendations: ["array of remediation steps"]

dockerfile_best_practices:
  non_root_user: boolean
  minimal_base: boolean
  layer_optimization: boolean
  healthcheck_present: boolean
```

**Additional T3 fields:**
```yaml
multi_arch_support:
  platforms: ["linux/amd64", "linux/arm64"]
  buildx_config: "buildx command"

supply_chain_security:
  sbom_file: "syft SBOM JSON"
  signature_verification: "cosign verification command"

ci_cd_integration:
  github_actions: "workflow YAML"
  automated_scanning: boolean
```

---

## Examples

```dockerfile
# T1 Example: Node.js Multi-Stage Dockerfile
FROM node:18-alpine AS builder
WORKDIR /build
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001
COPY --from=builder /build/dist ./dist
COPY --from=builder /build/node_modules ./node_modules
USER nodejs
EXPOSE 3000
CMD ["node", "dist/index.js"]
```

```
# .dockerignore
node_modules
.git
.env
*.md
.github
tests
coverage
```

---

## Quality Gates

**Token budgets (enforced):**
- **T1**: ≤2,000 tokens - basic multi-stage Dockerfile generation
- **T2**: ≤6,000 tokens - production optimization with security scanning
- **T3**: ≤12,000 tokens - multi-arch, SBOM, CI/CD integration

**Safety checks:**
- No hardcoded secrets in Dockerfile or layers
- Non-root user configured for runtime
- Base images from trusted registries only
- Security scan shows no unpatched Critical CVEs (T2+)

**Auditability:**
- Base image tags are pinned (not :latest)
- Build stages are named and documented
- Security scan results include timestamp and scanner version
- Layer count and size metrics provided

**Determinism:**
- Same inputs produce identical Dockerfile structure
- Package versions pinned in dependency files
- Build process reproducible

**Validation requirements:**
- Dockerfile must pass `docker build` without errors
- T2+ images must pass Trivy scan with acceptable CVE thresholds
- Final image size meets optimization targets (<100MB for simple apps)

---

## Resources

**Official Documentation (accessed 2025-10-26T01:33:54-04:00):**
- Docker Multi-Stage Builds: https://docs.docker.com/build/building/multi-stage/
- Dockerfile Best Practices: https://docs.docker.com/build/building/best-practices/
- Docker BuildKit: https://docs.docker.com/build/buildkit/
- Docker Security: https://docs.docker.com/engine/security/

**Base Images:**
- Distroless Images: https://github.com/GoogleContainerTools/distroless
- Alpine Linux: https://alpinelinux.org/
- Official Docker Images: https://hub.docker.com/_/alpine

**Security Tools:**
- Trivy Scanner: https://github.com/aquasecurity/trivy
- Grype Scanner: https://github.com/anchore/grype
- Syft SBOM Generator: https://github.com/anchore/syft
- Cosign Image Signing: https://github.com/sigstore/cosign

**Optimization Guides:**
- Node.js Docker Best Practices: https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md
- Python Docker Best Practices: https://docs.python.org/3/using/unix.html#on-linux
- Go Docker Best Practices: https://docs.docker.com/language/golang/build-images/