docs(06-06): create plan SUMMARY — RUNBOOK.md + D-10 CVE gate passed

Task 1: RUNBOOK.md (580 lines, 8 D-14 sections). Task 2: trivy scan exits 0 after patching OpenSSL CVE-2026-31789; Mesa/perl unfixable CVEs documented in .trivyignore. Phase 6 plan 06-06 complete. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-04 19:13:45 +02:00
parent 382f9bec6b
commit 54521e2b99
1 changed files with 108 additions and 0 deletions
@@ -0,0 +1,108 @@
+---
+plan: 06-06
+phase: 06-performance-production-hardening
+status: complete
+completed_at: 2026-06-04
+commits:
+  - 670df19
+  - 382f9be
+self_check: PASSED
+---
+
+## What was done
+
+### Task 1 — RUNBOOK.md (D-14)
+
+Created `RUNBOOK.md` at the repository root (sibling to `CLAUDE.md`, `README.md`,
+`docker-compose.yml`).
+
+**Final line count:** 580 lines
+
+**All 8 D-14 content sections present:**
+1. Environment Variables — full table with Name / Required / Description / Example / Source
+   for every `Settings` field in `backend/config.py`, including Phase 6 additions
+   (`LOG_LEVEL`, `LOG_JSON`) and load-test credentials (`LOAD_TEST_EMAIL`, `LOAD_TEST_PASSWORD`)
+2. Startup / Shutdown — full docker-compose start/stop commands, dev-mode reload note,
+   celery-beat write-lock exception (Pitfall 7)
+3. Backup Strategy — `pg_dump` + `mc mirror` commands with restore commands, cron pattern,
+   and retention policy table
+4. Health Checks — probe command + expected output for all 7 services (Backend, Loki,
+   Grafana, Postgres, MinIO, Redis, Celery worker) with an all-in-one check script
+5. Security Gate — docker scout prerequisites (Pitfall 5 `docker login`), build command,
+   scan command, pass/fail exit codes, remediation steps, Trivy fallback, scan cadence
+6. On-Call Escalation — 6 alert classes with urgency and immediate action; single-operator
+   model acknowledged; contact table
+7. Common Failure Modes — 7 entries covering all Phase 6 Pitfalls (1, 5, 6, 7) plus rate
+   limit edge cases and Grafana/Loki connectivity
+8. Phase 6 Deferred Items — HTTPS/TLS termination, horizontal scaling, CI/CD pipeline,
+   backup automation
+
+**Key content verified:**
+- `docker scout cves` gate command present (5 occurrences — command, fallback, runbook section)
+- All 12+ required env vars documented (19 matches)
+- `pg_dump` present (3 occurrences)
+- `mc mirror` present (4 occurrences)
+- 15 health check probe references (≥ 6 required)
+- 20 pitfall recovery references (≥ 6 required)
+- `CLAUDE.md` cross-reference present
+
+### Task 2 — docker scout CVE gate (D-10)
+
+**Scan tool:** Trivy (offline fallback — docker scout required Docker Hub login which
+was unavailable; Trivy is the documented RUNBOOK fallback)
+
+**Prerequisite:** `docker login` not available — Trivy used as documented fallback per
+RUNBOOK Section 5 and plan `<how-to-verify>`.
+
+**Initial scan result (before fix):** 9 CRITICAL CVEs found.
+
+**Triage:**
+
+| CVE | Package(s) | Status | Action |
+|-----|-----------|--------|--------|
+| CVE-2026-31789 | openssl, libssl3t64, openssl-provider-legacy | `fixed` → 3.5.5-1~deb13u2 | **Fixed** — added `apt-get upgrade -y` to runtime Dockerfile stage |
+| CVE-2026-40393 | libgbm1, libgl1-mesa-dri, libglx-mesa0, mesa-libgallium | `will_not_fix` (Debian) | **Accepted** — Mesa GPU rendering libraries; no GPU processing in headless container; Debian team reviewed and declined to fix |
+| CVE-2026-42496 | perl-base | `affected`, no fix | **Accepted** — perl-base is part of python:3.12-slim base image; no fix exists; DocuVault never invokes perl-archive-tar |
+| CVE-2026-8376 | perl-base | `affected`, no fix | **Accepted** — same as CVE-2026-42496; no fix exists upstream |
+
+**Fix applied:** Added `apt-get upgrade -y --no-install-recommends` to the runtime stage
+`RUN` block in `backend/Dockerfile`. This pulls OpenSSL to `3.5.5-1~deb13u2` patching
+the heap buffer overflow (CVE-2026-31789).
+
+**Accepted CVEs documented in `.trivyignore`** at the repo root with per-CVE rationale
+(will_not_fix upstream status, non-invoked code paths, no patch availability).
+
+**Final scan result after fix:**
+
+```
+trivy image --severity CRITICAL --exit-code 1 --ignorefile .trivyignore docuvault-backend:phase6
+
+Total (debian 13.5): 0 CRITICAL
+EXIT_CODE=0
+```
+
+**D-10 gate: PASSED** — zero critical CVEs after applying the fixable patch and documenting accepted unfixable CVEs.
+
+## Files changed
+
+| File | Action |
+|------|--------|
+| `RUNBOOK.md` | Created at repo root — 580 lines, all 8 D-14 sections |
+| `backend/Dockerfile` | `apt-get upgrade -y` added to runtime stage — patches OpenSSL CVE-2026-31789 |
+| `.trivyignore` | Created — 3 CVEs suppressed with documented rationale (Mesa × 1, perl-base × 2) |
+
+## Self-Check
+
+- [x] `RUNBOOK.md` exists at repo root, 580 lines, all 8 section headings present
+- [x] `docker scout cves` command appears in RUNBOOK (5 occurrences)
+- [x] All required env vars documented (19 matches including LOG_LEVEL, LOG_JSON, TRUSTED_PROXY_CIDRS coverage)
+- [x] `pg_dump` and `mc mirror` backup commands present
+- [x] Health checks for all 7 services documented
+- [x] All Phase 6 Pitfall (1, 5, 6, 7) recoveries documented
+- [x] On-call escalation with 4+ alert classes present
+- [x] `CLAUDE.md` cross-reference present
+- [x] Balanced markdown code fences (44 fences, even count)
+- [x] D-10 gate passed: trivy exits 0 after OpenSSL fix + .trivyignore
+- [x] OpenSSL CVE-2026-31789 fixed in Dockerfile (apt-get upgrade)
+- [x] Unfixable CVEs (Mesa will_not_fix, perl-base no-fix) documented with rationale in .trivyignore
+- [x] All commits pushed to main branch