Scan images for known vulnerabilities (0.59.0)

The Images page knew what was running and whether it was current. It could not
say whether any of it was exploitable, which is the question people actually
have about a homelab full of images they pulled once and forgot.

Trivy runs as a throwaway container rather than being installed into
StackPilot's image, reusing the helper-container pattern backups already use for
volume contents. Three reasons: a 100 MB security tool and a vulnerability
database that changes weekly have no business in a release artifact, pinning
SCANNER_IMAGE is then a real version control, and the scanner updates itself by
pulling a newer tag. It gets the socket read-only so it inspects images the
daemon already has instead of pulling them again, and a named volume for its
database so the ~50 MB download happens once rather than per scan.

The number the UI leads with is "fixable", not the total. A base image with 300
unfixable low-severity CVEs is not a task and a page that shows 300 in red
teaches people to ignore it; three findings with a fixed version available are
something to do this afternoon. Counts are stored per severity, findings are
sorted worst-first and capped at 200 — every finding is counted, only the list
is trimmed, so the cap can never hide the severity distribution.

The failure mode this had to avoid is a security feature that reads as clean
when it is broken. A scanner that cannot run stores the error and *keeps the
previous counts* rather than resetting to zero, so a transient daemon problem
does not silently turn a bad image green. There is a test for exactly that, and
another for unparseable output. Staleness is handled the same way: the local
image id is recorded with the scan, and pulling the image marks the result stale
instead of presenting yesterday's numbers for today's bytes.

Sweeps are deliberately serial and singly-locked. Scanning is CPU- and IO-heavy,
and running eight at once on a homelab box would starve the very containers the
scan is meant to protect. docker-py is synchronous, so the scan itself goes to a
thread — otherwise a ten-minute scan blocks every other request on the loop.

Reading results is allowed for the read-only role, which the authorization
matrix made me justify in writing: CVE ids and package versions for images whose
tags and compose files that role can already see, and polling them is the
monitoring use case a read-only API token exists for. Running a scan stays
admin-only because it spends real CPU.

20 tests against a report shaped like Trivy's real output, covering the counting,
the fixable number, worst-first ordering, the cap, both failure paths, staleness,
and that two sweeps cannot overlap. Verified end to end through the API as well,
including that a failed rescan keeps its previous counts and shows the error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -13,6 +13,36 @@ as intuitive as Dockge, as capable as Portainer for Compose workflows.
 > (Auto-update) + Phase 23 (Secrets & configs) + Phase 24 (Design System v2)
 > complete.
 
+## Upgrading to 0.59.0 — CVE scanning
+
+The Images page can tell you what is wrong with the images you are running.
+**Scan for CVEs** scans every image a stack uses; each row then shows critical
+and high counts, the total, and — the number that actually matters — how many
+findings **have a fix available**. A base image with 300 unfixable low-severity
+CVEs is not a task; three fixable ones are. Clicking a row opens the full list
+with package, installed version, fixed version and a link to the advisory.
+
+**The scanner is a container, not a dependency.** Trivy runs as a throwaway
+container (the same trick backups use for volume contents), so a 100 MB security
+tool and its weekly-changing vulnerability database stay out of StackPilot's own
+image, and the scanner updates itself by pulling a newer tag. It gets the Docker
+socket **read-only** to inspect images the daemon already has, and a named
+volume (`stackpilot-trivy-cache`) so its ~50 MB database downloads once instead
+of per scan. The first scan is therefore slow; the rest are not.
+
+Set `SCANNER_IMAGE` to pin a version (default `aquasec/trivy:latest`).
+
+**A scan that fails never looks clean.** If the scanner cannot run, the row
+keeps the counts from the last good scan and shows the error — silence would
+otherwise read as "no vulnerabilities", which is the one failure mode a security
+feature must not have. Results also go stale honestly: pull an image and its
+scan is marked *stale* rather than presenting yesterday's numbers for today's
+image.
+
+Reading results works with the read-only role and a read-only API token, so a
+monitoring script can poll `GET /api/images/scans`. Running a scan is admin-only
+— it spends real CPU and spawns a container.
+
 ## Upgrading to 0.58.0 — deploy stacks from Git
 
 A stack can now be backed by a Git repository. **Stack detail → Git**: point it
@@ -426,6 +456,11 @@ it is what your saved destination credentials are encrypted with.
   compose** converter.
 - **Dashboard** — system resource bar, stack grid with quick actions, and a
   recent-activity audit feed.
+- **CVE scanning** — Trivy runs as a throwaway container against the images your
+  stacks use; the Images page shows critical/high counts, how many findings are
+  fixable, and the full advisory list per image. A failed scan reports the
+  failure rather than reading as "clean", and a scan goes stale when the image
+  is pulled again.
 - **GitOps** — a stack can be deployed from a Git repository (branch and
   subdirectory selectable, HTTPS token or SSH key for private repos), synced
   manually, on a poll interval or from a push webhook, with optional automatic
@@ -986,6 +1021,16 @@ GET  /api/dashboard/funnel[?refresh=true]   (stack-health funnel, 30s TTL cache)
 GET  /api/dashboard/summary                 (containers, uptime series, ops activity)
 ```
 
+### CVE scanning endpoints
+
+```
+GET  /api/images/scans              (cached results; read-only role may read)
+GET  /api/images/scan?image=…       (one image, with its findings)
+POST /api/images/scan               ({"image": "…"}, admin — runs the scanner)
+POST /api/images/scan-all           (every image a stack uses, serial, admin)
+GET  /api/images/scan-status        (progress of a running sweep)
+```
+
 ### GitOps endpoints
 
 ```