container-scan

When to use

Trigger on any of:

• "Scan this Docker image before I push."
• "Is ghcr.io/acme/api:1.14.2 safe to ship?"
• Pre-release gate: CI job that builds an image and needs a pass/fail.
• Investigating a base-image upgrade ("did alpine:3.19 clear the openssl CVE?").

Do not use for running-container runtime monitoring (that is Falco/EDR territory) or for dependency scanning of the source tree pre-build (use dependency-audit).

Inputs

• IMAGE — OCI reference to scan, e.g. ghcr.io/acme/api:1.14.2 or a local tag api:dev. Required unless DOCKERFILE is given.
• DOCKERFILE (optional) — path to a Dockerfile to lint and scan.
• CONTEXT (optional) — build context when DOCKERFILE is provided.
• OUT_DIR (default: ./container-scan-out).
• FAIL_ON (default: CRITICAL,HIGH) — severities that cause non-zero exit.
• IGNORE_UNFIXED (default: 0) — Trivy --ignore-unfixed.
• Optional env:
  • TRIVY_CACHE_DIR — share vulnerability DB across runs.
  • TRIVY_IGNOREFILE — path to .trivyignore.

Outputs

• trivy-image.json — Trivy CVE scan of the image.
• trivy-secret.json — secrets found in image layers.
• trivy-config.json — Dockerfile / IaC misconfiguration scan.
• hadolint.json — Dockerfile lint (if DOCKERFILE provided).
• image-inspect.json — docker inspect output.
• container-scan-report.md — human summary with pass/fail gates.

Tool dependencies

• trivy >= 0.50 (https://aquasecurity.github.io/trivy/).
• docker or podman (for image inspect and saving images).
• hadolint >= 2.12 (optional; auto-skipped if missing).
• jq.
• syft (optional) for SBOM generation.

Procedure

1. Validate inputs. If IMAGE not provided and DOCKERFILE is, build first: docker build -t scan-target:tmp -f "$DOCKERFILE" "$CONTEXT".
2. Pull the image if remote: docker pull "$IMAGE" (or podman pull).
3. Inspect: docker image inspect "$IMAGE" > "$OUT_DIR/image-inspect.json". Parse Config.User, Config.ExposedPorts, RootFS.Layers, History[].CreatedBy.
4. Trivy vulnerability scan:

   trivy image \
     --format json --output "$OUT_DIR/trivy-image.json" \
     --severity CRITICAL,HIGH,MEDIUM,LOW \
     --vuln-type os,library \
     --scanners vuln \
     ${IGNORE_UNFIXED:+--ignore-unfixed} \
     "$IMAGE"
   

5. Trivy secret scan (examines each layer):

   trivy image --scanners secret \
     --format json --output "$OUT_DIR/trivy-secret.json" "$IMAGE"
   

6. Trivy config scan (Dockerfile + embedded IaC):

   trivy config --format json --output "$OUT_DIR/trivy-config.json" \
     ${DOCKERFILE:+"$(dirname "$DOCKERFILE")"} \
     ${DOCKERFILE:-"$IMAGE"}
   

7. If DOCKERFILE provided, run hadolint: hadolint --format json "$DOCKERFILE" > "$OUT_DIR/hadolint.json".
8. Best-practice checks against image-inspect.json:
   • Config.User must be non-empty and not root / 0 (else FAIL).
   • RootFS.Layers count should be <= 20 (advisory).
   • Base image SHOULD be distroless, Chainguard Wolfi, or *-slim — heuristic: missing /bin/sh, /bin/bash, or no shell in manifest.
   • No ADD http:// URLs in history (use COPY + verified artefact).
   • No secrets in Config.Env (cross-check against trivy-secret.json).
   • Healthcheck defined (Config.Healthcheck) — advisory.
9. Optional SBOM: syft "$IMAGE" -o cyclonedx-json > "$OUT_DIR/sbom.cdx.json".
10. Aggregate and write container-scan-report.md:
    • Gate table: Critical CVE, High CVE, Secrets in layers, Non-root, Dockerfile issues (each row: status + count).
    • Findings grouped by severity with fix-version hints.
    • Upgrade plan: which base-image bump clears the most CVEs.
11. Exit non-zero if any gate in $FAIL_ON failed.