cc-ci-orchestrator/cc-ci-plan/advisory-scan.SPEC.md

Advisory scan — specification

What cc-ci-plan/advisory-scan.py does, step by step, and why each step exists. This documents the implementation as it stands (2026-08-10); if you change the code, change this file in the same commit.

Role. A deterministic, per-recipe CVE detector run as a pre-step of /recipe-upgrade (step 2a). It is strictly additive: it never replaces the release-note reading the upgrade agent already does. The CVE count reported for a recipe is the union of what the agent read and what this scan found; the scan may never lower a count established by reading.

Why it exists. gitea 1.27.1 fixed CVE-2026-60004 and CVE-2026-59774 (both CVSS 9.8). The weekly report printed gitea's CVE count as 1, then none. The upgrade agent had read the GitHub release notes, which name neither — both were announced only in the vendor's blog security section — and the report then derived security content from those notes plus model knowledge, which predates the CVEs. Nothing in the pipeline queried an advisory source. This scan closes that hole.

---

Inputs

advisory-scan.py <recipe> [--from <version>] [--to <version>] [--json] [--registry DIR]

Input	Meaning
<recipe>	Recipe name; selects cc-ci-plan/upstream/<recipe>.md (the per-recipe URL registry)
--from / --to	The primary app image's version window being upgraded across
--registry	Registry dir; also CCCI_UPSTREAM_REGISTRY
GITHUB_TOKEN / GITHUB_TOKEN_FILE	Read-only token; rate limit only (60/hr anonymous → 5000/hr). Default file /srv/cc-ci/.github-token, mode 600. Public advisories need no scopes.

Exit code is always 0 — this is informational. Failures are reported, never raised.

---

Step 1 — Collect source URLs from the registry

Read cc-ci-plan/upstream/<recipe>.md and extract every http(s)://… URL.

Trailing markdown punctuation is stripped (` ' " * . , ; : > )). The registry is markdown, so URLs appear inside backticks and quotes; capturing the punctuation produced fetches of https://docs.n8n.io/release-notes/\`` which 404, and made immich and n8n render ?` for no real reason.

Registry hygiene matters. The scan can only look where the registry points. Two classes of defect have been found and fixed by running it: a wrong URL (pgautoupgrade/pgautoupgrade, which 404s — the repo is pgautoupgrade/docker-pgautoupgrade) and a missing one (gitea's CVEs are announced at blog.gitea.com, which the registry didn't list). When a vendor publishes security notes somewhere the registry lacks, add it.

Step 2 — Query the sources

Three source classes, each recording its own status so "checked, none found" is never confused with "not checked".

2a. GitHub Security Advisories — PRIMARY

For every github.com/<owner>/<repo> URL in the registry: GET /repos/<owner>/<repo>/security-advisories.

Captured per advisory: cve_id, ghsa_id, severity, summary, published_at, and all vulnerabilities[] entries' vulnerable_version_range + patched_versions (joined with ;).

• All entries, not just the first. An advisory carries one entry per patched release line — n8n patches three (1.123.32, 2.17.4, 2.18.1). Reading only vulnerabilities[0] silently dropped the line a deployment was actually on, and misclassified CVE-2026-42231/42232 as out-of-window.
• Pagination via the Link rel="next" cursor, to exhaustion (cap 20 hops). This endpoint returns at most 100 rows and ignores ?page= — it re-returns the same rows, which silently truncates busy projects. discourse has 286 advisories; a single page cannot even cover one upgrade window.
• HTTP 404 ⇒ no-advisories-published — a benign absence (many sidecar images publish none), not a failure. Conflating the two pushed nearly every recipe to ? and destroyed the signal.

This source is primary because it carries severity and version ranges, making "fixed by this upgrade" computable rather than guessed.

2b. Vendor release / security pages

Every other registry URL is fetched, HTML-stripped, and scanned for CVE-\d{4}-\d{4,7}, keeping ±160 characters of context per hit.

URLs containing <, >, {, }, VERSION, or vX.Y.Z are skipped as templates — they are human documentation (…/changelog/v<VERSION>/), not fetchable, and counting them as failures is wrong.

This is the source that would have caught gitea: the vendor blog names both CVEs, the GitHub release page names neither.

2c. OSV.dev — supplementary

Only when the recipe has an entry in OSV_PACKAGES (ecosystem + package) and a version is given.

Measured, not assumed. For the two gitea CVEs, OSV 404'd on both and returned only Go dependency advisories for the package; NVD's API had them by neither CPE, CVE id, nor keyword. Advisory databases lag the vendor, which is why 2a and 2b lead and this is supplementary.

Step 3 — Union

All findings merge into one CVE map: id → {sources[], severity, ghsa, vulnerable_range, patched, published_at, context}. A CVE seen by several sources keeps them all.

Step 4 — Classify against the upgrade window

Two invariants govern this step, both learned from a wrong answer in production.

A. The window belongs to ONE image. Only advisories from the primary source (the first github-advisories: source, i.e. the app repo the registry lists first) are classified. Sidecar advisories are recorded as unclassified so they stay visible without inflating the count. Why: discourse once reported 133, of which 34 were redis CVEs — including CVE-2021-21309, patched in redis 6.0.11 in 2021 — counted purely because 6.0.11 sits numerically inside discourse's 3.5.3 → 2026.7.1 range.

B. Never emit a number you cannot justify. If neither method below can order the window, the count is null / UNKNOWN, never 0. A 0 in a security column asserts safety.

4a. By patched version (preferred — exact)

patched_versions is a range expression (">= 2.18.1"), possibly several joined by ;. Extract every version-looking token; the advisory is fixed-by-this-upgrade if any patched version p satisfies from < p <= to, using a loose numeric key (leading integers per dot-part).

4b. By advisory publish date (fallback — temporal)

Used only when 4a cannot be trusted: a version-scheme change, detected as the leading version component jumping by ≥ SCHEME_JUMP (100) — e.g. semver 3.5.3 → calver 2026.7.1.

Version strings are unorderable across such a jump (2025.12.2 compares "newer" than 3.5.3 while shipping earlier), but release dates always order. So:

1. Resolve --from and --to to git tag dates on the primary repo (tries v<version> then <version>; annotated tag → tagger date, else commit date).
2. An advisory counts as fixed when date_from < published_at <= date_to.

Both the method and the resolved window appear in the output. This reproduces, automatically, the hand count that established discourse 3.5.3 (2025-12-30) → 2026.7.1 (2026-07-31) = 123 CVEs.

Assumption: the vendor publishes advisories at fix time (true for discourse). The count includes first-party plugin advisories where the vendor files them on the same repo — which is why a plugin-rich project scores far higher than a monolith, not a statement about relative security.

4c. Otherwise

count_known = false, cve_count_fixed = null, and the markdown headline reads "CVEs fixed by this upgrade: UNKNOWN — the scan could NOT determine a count" with an explicit "This is NOT zero".

Step 5 — Output

Markdown (default) for pasting into the per-recipe upgrade log, or --json.

Field	Meaning
cve_count_fixed	Count, or null when undeterminable
count_known	Distinguishes "counted zero" from "could not count"
classified_by	patched version ranges or advisory publish date (version scheme changed)
date_window	The resolved date window, when 4b was used
fixed_by_this_upgrade[]	CVE ids, with severity / GHSA / fixed-in per id
unclassified[]	Seen but not attributable to this window (incl. other images)
sources[]	Every source with its own status
sources_failed[]	Genuine failures only
sources_benign[]	no-advisories-published, skipped: template URL

---

How consumers must read it

/recipe-report renders the cve column from the union of this scan and the agent's own reading:

• a clean scan → its number, including 0;
• failed sources, or UNKNOWN → ?, never none — a blank reads as "clean", which is exactly how two CVSS-9.8 gitea RCEs were published as none;
• no upgrade this run → 0, not ? — nothing an upgrade could have fixed;
• benign notes → never ?.

? must stay rare: it means we tried and could not tell, not we did not look. A rash of ? is a bug to raise in the report's Addendum, not a normal outcome — every instance so far traced to a defect in this tool or stale registry data.

Known limits

1. One window per scan. Sidecar bumps (redis, postgres) are not counted; they appear as unclassified. Per-image windows would be the natural extension.
2. Date-based counts are temporal, not exact — they assume publish-at-fix-time.
3. Registry-bound. Unlisted vendor security pages are invisible; the scan cannot know what it was never pointed at.
4. Rate limit without a token is 60/hr — a full weekly sweep will exhaust it and degrade to failed sources (visibly, but degraded).