From 2a1b93d8f6e38680fe1a5db5a6246a3665e0af8d Mon Sep 17 00:00:00 2001 From: Derek Cooper Date: Sun, 22 Mar 2026 12:15:33 -0700 Subject: [PATCH] created docker security audit playbook --- .gitignore | 2 + playbooks/docker-security-audit.md | 223 +++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 .gitignore create mode 100644 playbooks/docker-security-audit.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..47aa0fa --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +containers.local.txt +reports/ diff --git a/playbooks/docker-security-audit.md b/playbooks/docker-security-audit.md new file mode 100644 index 0000000..a71af80 --- /dev/null +++ b/playbooks/docker-security-audit.md @@ -0,0 +1,223 @@ +# Playbook: Docker Image Security Audit + +Use this playbook to audit Docker images across your environment for vulnerabilities, misconfigurations, secrets, and anything that could compromise the host or network. + +When invoked, read `containers.local.txt` in the current working directory and work through each section for every image listed. + +--- + +## How to Use + +Tell the AI: _"Use the docker-security-audit playbook"_ + +The AI will: +1. Read `containers.local.txt` to get the list of images to audit +2. For each image — pull it, run all checks below, and evaluate results +3. For each finding — report CRITICAL, HIGH, MEDIUM, LOW, or INFO +4. Generate a timestamped report file in the `reports/` directory +5. Remove the image from the local host after scanning **unless** it is currently active (`docker ps`) +6. At the end, give an overall environment summary + +Do not skip or abbreviate checks. Run every tool listed for every image. + +--- + +## Pre-Flight + +Before scanning any images: + +- [ ] Confirm `trivy` is installed: `trivy --version` +- [ ] Confirm `docker scout` is available: `docker scout version` +- [ ] Confirm Docker daemon is running: `docker info` +- [ ] Confirm a `reports/` directory exists in the working directory + +**AI Action:** Run the above checks. If any tool is missing, stop and tell the user what needs to be installed before continuing. Do not proceed with a partial toolset. + +### containers.local.txt Bootstrap + +Check if `containers.local.txt` exists in the current working directory. + +- **If it does not exist:** Create it with the following content, then stop and instruct the user to populate it before running the audit: + +``` +# Local Docker image inventory +# Format: image:tag — one per line +# This file is excluded from git. Keep it updated per host. +# Images without a tag will be treated as :latest (flagged as WARN in audit). + +``` + + Tell the user: _"`containers.local.txt` was not found and has been created. Add your image:tag entries (one per line) and re-run the playbook."_ + +- **If it exists but is empty or contains only comments:** Same as above — stop and prompt the user to add images. +- **If it exists and has valid entries:** Continue to scanning. + +--- + +## Per-Image Procedure + +Repeat this entire procedure for **every** `image:tag` entry in `containers.local.txt`. + +### Step 1 — Check if Already Active + +Run: `docker ps --format '{{.Image}}'` + +- If the image is in the active list → mark as **ACTIVE**, skip Step 6 (do not remove) +- If not active → mark as **NOT ACTIVE**, will be removed after scan + +### Step 2 — Pull the Image + +Run: `docker pull ` + +- If pull fails → mark as WARN (image may be private, unavailable, or tag deleted) and skip to next image +- Note the image digest and creation date + +### Step 3 — CVE Scan (Trivy) + +Run: `trivy image --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL --format json ` + +Report findings grouped by severity: + +| Severity | Count | Notable CVEs | +|---|---|---| +| CRITICAL | | | +| HIGH | | | +| MEDIUM | | | +| LOW | | | +| UNKNOWN | | | + +- List every CRITICAL and HIGH CVE individually with: CVE ID, affected package, fixed version (if available), and a one-line description of the risk +- Summarise MEDIUM/LOW as counts only unless the user asks for detail +- Flag any CVE with a known public exploit (Trivy marks these with `--ignore-unfixed` info) + +### Step 4 — CVE Scan (Docker Scout) + +Run: `docker scout cves ` + +- Cross-reference with Trivy results — note any findings unique to Scout that Trivy missed +- Report new findings in the same severity table format as Step 3 +- If Scout and Trivy agree, note "Confirmed by both scanners" + +### Step 5 — Extended Checks (Trivy) + +Run each of the following and report all findings: + +**Secrets scan:** +`trivy image --scanners secret ` +- Report any detected secrets: type, file path inside image, line number if available +- Even LOW confidence matches should be reported — flag clearly as low confidence + +**Misconfiguration scan:** +`trivy image --scanners misconfig ` +- Dockerfile best practice violations +- CIS Docker Benchmark failures +- Report each finding with: check ID, title, severity, description, and remediation + +**License scan:** +`trivy image --scanners license --severity UNKNOWN,HIGH ` +- Flag any unknown or restrictive licenses (GPL in a closed deployment, etc.) + +**SBOM generation:** +`trivy image --format cyclonedx --output reports/sbom--.json ` +- Generate and save an SBOM for the image — no pass/fail, this is for records + +### Step 6 — Image Cleanup + +After all scans are complete for this image: + +- If **NOT ACTIVE**: run `docker rmi ` + - Confirm removal succeeded + - If removal fails (e.g. stopped container referencing it), note the reason and flag for manual cleanup +- If **ACTIVE**: skip removal, note it in the report + +--- + +## Report Generation + +After all images are scanned, generate a single report file: + +**Filename:** `reports/docker-audit-.md` + +The report must include: + +### Report Sections + +#### Summary Table + +| Image | CRITICAL | HIGH | MEDIUM | LOW | Secrets | Misconfigs | Status | Removed | +|---|---|---|---|---|---|---|---|---| +| image:tag | 0 | 0 | 0 | 0 | 0 | 0 | ACTIVE/NOT ACTIVE | YES/NO/FAILED | + +#### Critical & High Findings (Detail) + +For every CRITICAL or HIGH CVE across all images: + +``` +Image: +CVE: CVE-XXXX-XXXXX +Package: +Fixed in: (or "No fix available") +Scanner: Trivy / Docker Scout / Both +Risk: +``` + +#### Secrets Detected + +For every secret finding: + +``` +Image: +Type: +Confidence: HIGH / MEDIUM / LOW +Path: +Action: INVESTIGATE / ROTATE IMMEDIATELY +``` + +#### Misconfigurations + +For every misconfiguration finding: + +``` +Image: +Check: +Title: +Severity: +Detail: +Fix: +``` + +#### Cleanup Log + +List every image and whether it was removed, skipped (active), or failed to remove. + +#### Overall Risk Rating + +After all findings: + +- **CRITICAL findings present** → Environment status: **AT RISK** — immediate action required +- **HIGH findings only** → Environment status: **ELEVATED** — remediate within 7 days +- **MEDIUM/LOW only** → Environment status: **ACCEPTABLE** — remediate in next maintenance window +- **No findings** → Environment status: **CLEAN** + +--- + +## Severity Reference + +| Severity | Action Required | +|---|---| +| CRITICAL | Stop and flag immediately. Do not defer. Notify user before continuing. | +| HIGH | Report in full. User must acknowledge before moving to next image. | +| MEDIUM | Report and continue. Include in final report. | +| LOW | Count only unless user requests detail. | +| INFO | Include in SBOM/records only. | + +--- + +## Notes for the AI + +- Never skip an image without documenting why +- Never abbreviate CVE lists for CRITICAL or HIGH findings +- If a scan command fails (not just returns no findings), report the error and the command that failed +- Do not remove an image that appears in `docker ps` output under any circumstances +- If `containers.local.txt` references an image with no tag, assume `:latest` and note it as a WARN (unpinned tag) +- SBOM files are supplemental — save them but do not report their contents unless the user asks