diff --git a/playbooks/docker-security-audit.md b/playbooks/docker-security-audit.md index a71af80..fc5f394 100644 --- a/playbooks/docker-security-audit.md +++ b/playbooks/docker-security-audit.md @@ -8,7 +8,7 @@ When invoked, read `containers.local.txt` in the current working directory and w ## How to Use -Tell the AI: _"Use the docker-security-audit playbook"_ +Tell the AI: _"Run this playbook: https://git.chns.tech/CHNS/AI/raw/branch/main/playbooks/docker-security-audit.md"_ The AI will: 1. Read `containers.local.txt` to get the list of images to audit @@ -27,7 +27,8 @@ Do not skip or abbreviate checks. Run every tool listed for every image. Before scanning any images: - [ ] Confirm `trivy` is installed: `trivy --version` -- [ ] Confirm `docker scout` is available: `docker scout version` +- [ ] Confirm `grype` is installed: `grype version` +- [ ] Confirm `hadolint` is installed: `hadolint --version` - [ ] Confirm Docker daemon is running: `docker info` - [ ] Confirm a `reports/` directory exists in the working directory @@ -90,15 +91,25 @@ Report findings grouped by severity: - 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) +### Step 4 — CVE Scan (Grype) -Run: `docker scout cves ` +Run: `grype --output json` -- Cross-reference with Trivy results — note any findings unique to Scout that Trivy missed +- Cross-reference with Trivy results — note any findings unique to Grype 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" +- If Grype and Trivy agree, note "Confirmed by both scanners" -### Step 5 — Extended Checks (Trivy) +### Step 5 — Dockerfile Static Analysis (Hadolint) + +Locate the Dockerfile for this image if available in the current working directory or a subdirectory. + +Run: `hadolint ` + +- Report every rule violation with: rule ID, severity, line number, and description +- Flag `DL` (Dockerfile) and `SC` (ShellCheck) rule violations separately +- If no Dockerfile is found locally, note it as INFO and skip this step — do not fail the audit + +### Step 7 — Extended Checks (Trivy) Run each of the following and report all findings: @@ -121,7 +132,7 @@ Run each of the following and report all findings: `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 +### Step 8 — Image Cleanup After all scans are complete for this image: @@ -134,56 +145,40 @@ After all scans are complete for this image: ## Report Generation -After all images are scanned, generate a single report file: +After all images are scanned, generate the following files. All output goes into a timestamped folder: -**Filename:** `reports/docker-audit-.md` +**Folder:** `reports/audit-/` -The report must include: +Create this folder before writing any files. If it already exists, continue writing into it. -### Report Sections +--- + +### File 1 — Overview Report (replaces previous audit file) + +**Filename:** `reports/audit-/audit-.md` + +This is the top-level summary. It must link to each per-image detail file. #### 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 | +| Image | CRITICAL | HIGH | MEDIUM | LOW | Secrets | Misconfigs | Hadolint | Status | Removed | Detail File | +|---|---|---|---|---|---|---|---|---|---|---| +| image:tag | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ACTIVE/NOT ACTIVE | YES/NO/FAILED | [image-name.md](image-name.md) | -#### Critical & High Findings (Detail) +#### Critical & High Findings (All Images) -For every CRITICAL or HIGH CVE across all images: +List every CRITICAL or HIGH CVE across all images — abbreviated to one line each: ``` -Image: -CVE: CVE-XXXX-XXXXX -Package: -Fixed in: (or "No fix available") -Scanner: Trivy / Docker Scout / Both -Risk: +[image:tag] CVE-XXXX-XXXXX — — Fixed in: ``` -#### Secrets Detected +#### Secrets Detected (All Images) -For every secret finding: +List every secret finding across all images — one line each: ``` -Image: -Type: -Confidence: HIGH / MEDIUM / LOW -Path: -Action: INVESTIGATE / ROTATE IMMEDIATELY -``` - -#### Misconfigurations - -For every misconfiguration finding: - -``` -Image: -Check: -Title: -Severity: -Detail: -Fix: +[image:tag] — Confidence: HIGH/MEDIUM/LOW — Action: INVESTIGATE/ROTATE IMMEDIATELY ``` #### Cleanup Log @@ -201,6 +196,93 @@ After all findings: --- +### File 2 — Per-Image Detail Reports + +**Filename per image:** `reports/audit-/-.md` + +- Replace `:` and `/` in the image name with `-` to form a safe filename (e.g. `nginx-latest.md`, `myrepo-myapp-1.2.3.md`) +- Generate one file per image — do not combine images into a single detail file + +Each per-image file must include: + +#### Header + +``` +# Image Audit: +Date: +Digest: +Status: ACTIVE / NOT ACTIVE +``` + +#### CVE Findings (Trivy + Grype) + +Full detail for every CRITICAL and HIGH CVE: + +``` +CVE: CVE-XXXX-XXXXX +Package: +Fixed in: (or "No fix available") +Scanner: Trivy / Grype / Both +Risk: +``` + +Summarise MEDIUM and LOW as counts with a table — do not list individually unless they have a known public exploit. + +#### Secrets + +Full detail for every secret finding: + +``` +Type: +Confidence: HIGH / MEDIUM / LOW +Path: +Action: INVESTIGATE / ROTATE IMMEDIATELY +``` + +#### Hadolint Findings + +Full detail for every Hadolint rule violation: + +``` +Rule:
+Line: +Severity: +Detail: +``` + +If no Dockerfile was found, note: `Hadolint: Skipped — no Dockerfile located` + +#### Misconfigurations + +Full detail for every misconfiguration finding: + +``` +Check: +Title: +Severity: +Detail: +Fix: +``` + +#### License Findings + +List any unknown or restrictive licenses flagged by Trivy. + +#### SBOM + +Note the SBOM filename saved alongside this report: + +`SBOM saved: reports/audit-/sbom--.json` + +Update the SBOM output path to match this folder: +`trivy image --format cyclonedx --output reports/audit-/sbom--.json ` + +#### Cleanup + +Note whether the image was removed, skipped (active), or failed to remove — and the reason if failed. + +--- + ## Severity Reference | Severity | Action Required |