Make the CVE scan runnable unattended, reporting only what changed

[NickJosevski]

Companion to Modern-Deployments#4,
which adds the Scan Calamari for CVEs runbook. That runbook cannot run until these changes
land — it invokes this script straight from main.

The runbook has now had real runs against it — results below.

Why

scan.sh reproduced a customer scan on demand, but only helped someone who thought to run it.
Two independent things change the answer:

1. The artifact changes — a new build bundles a new .NET runtime.
2. The world changes — a CVE is published against an artifact that has not moved.
   Nothing in this repo changes.

Only a schedule catches the second, and it is the one that bites: CVE-2026-44788 was absent
from the audit source at 10:45 and present by 15:00 on the same day.

The part that makes it an alert rather than a report

Running nightly and posting the output is useless — the same 1 medium CVE every morning is
something everyone mutes by week two. So the script now takes --previous-state, compares
against it, and exits 3 only when the set actually differs. Without it, exit 0 as before.

compare.py holds that logic; summarise.py collapses each version's raw scanner output
(the 43-matches-to-1-distinct fold this repo already documents).

Other changes

• Several versions per run. Customers run old versions; the supported release tips are
  what show up in reports, not main.
• --runner=docker|native. Containers by default so a local run needs no install. Inside
  an Octopus execution container the step is already in a container, so docker-in-docker is
  unavailable and the binaries are used from PATH.
• Colour only to a real terminal. Octopus captures stdout into a task log, where escape
  codes appeared verbatim.
• --octopus wires the above to output variables and run artifacts.
• Runtime drift against Microsoft's releases index, flagged independently of any CVE.

Drift is folded into the stored state, deliberately

A runtime that permanently trails the current patch would otherwise fire an identical alert
every night — the exact failure this design exists to avoid. It is stored, so it alerts when
it appears, then goes quiet.

Verified

The alerting contract was tested in both directions with synthetic scanner output, since a
real scan takes ~10 minutes:

Case	Expected	Result
First run, no previous state	exit 3, baseline reported	✅
Same input, previous state supplied	exit 0, silent	✅
A new CVE appears	exit 3, NEW: CVE-…	✅
CVE fixed + runtime patched	exit 3, gone: + runtime: 8.0.29 -> 8.0.30	✅

Case 2 is the important one: it stayed silent while a real drift condition was present,
which is what proves the folding works. The drift check is live — it fetched Microsoft's
index and correctly identified 8.0.29 as trailing 8.0.30.

Known gap

The native scanner installs are unpinned. For a scheduled job that is weaker than it
should be: a scanner upgrade and a genuine new CVE look identical in the diff. TRIVY_VERSION
/ GRYPE_VERSION pin them; baking both into a pinned execution container image is the real
fix and is worth doing before this runs unattended for long.

---

Verified on the real instance

Two consecutive runs against 2026.3.508, using the runbook in Modern-Deployments:

	Run A (no prior state)	Run B (state populated)
Scan	✅	✅
Notify Slack	✅ posted	⏭️ skipped
Save state	✅	✅
HasNewFindings	true	false

Run B logged no change: same distinct CVE set, same bundled runtime. Both directions of
the alerting contract now hold against real scanner output, not just fixtures.

Real result for 2026.3.508: 6 distinct identifiers and 8.0.29, which trails the current
8.0.30. The README recorded this same artifact as 1 medium CVE on 2026-08-01 — nothing
in Calamari changed in between. That is the "world changes" driver, observed rather than
argued.

Trap worth recording

An Octopus API key is created as read or write scoped. A read-scoped key
authenticates, passes every GET, and fails writes with
Missing permission: LibraryVariableSetEdit — indistinguishable from the account lacking
the role. It cost an afternoon of chasing teams and role scoping. If a write 403s while the
permissions API insists the permission is granted, check the key's scope first.