Docker Security Scanner

---
name: docker-security-scanner
description: |
  Trigger when the user asks to scan Docker images for vulnerabilities, check
  CVEs, or audit container security. Phrases: "scan docker", "image CVEs",
  "container vulnerabilities", "Trivy", "docker security".
allowed-tools:
  - Read
  - Bash(docker *)
  - Bash(trivy *)
  - Bash(grype *)
---

# Docker Security Scanner

Scan a Docker image for known CVEs, rank findings by severity and
exploitability, and propose a remediation path. Uses Trivy.

## Prerequisites

- Docker image built and available locally or in a registry
- `trivy` installed (`brew install trivy` or Homebrew-equivalent)

## Steps

1. **Scan the image:**
   ```bash
   trivy image --severity HIGH,CRITICAL --format json <image>:<tag> > trivy.json
   ```

2. **Parse and bucket results:**
   - Base-image CVEs (fixable by upgrading base image)
   - Application dependency CVEs (fixable in package.json / requirements.txt)
   - OS-level CVEs (fixable by package upgrade in Dockerfile)

3. **For each bucket, propose the minimum fix:**
   - Base image old -> bump to latest patch of same major (e.g. node:20.x.y to node:20.x.z)
   - Dep CVE -> check if a patched version exists, propose the minor-version bump
   - OS CVE -> add an `apt-get upgrade -y` step or switch to a distro with the fix

4. **Rescan after fixes** and confirm the CVE count drops. Do not claim
   complete until the HIGH/CRITICAL count is zero or explicitly accepted.

5. **Add scanning to CI.** A single GitHub Actions step that runs Trivy against
   the PR-built image and fails on HIGH/CRITICAL.

## Common patterns

- `alpine` images are smaller but rebuild more often due to `musl` CVEs.
- `distroless` base images (gcr.io/distroless/) remove the shell and package
  manager entirely, eliminating most OS CVEs.
- Pinning to digest (`@sha256:...`) pins CVEs as well. Pin at minor version,
  not digest, unless you have a CVE monitoring loop.

## Output

- `trivy.json` in the repo (gitignored if verbose)
- A markdown report at `security/docker-scan.md`: top 10 findings, fix plan
- CI workflow entry that scans the image on every PR