feat(scan): grade end-of-life findings by how close they are

--block-eol was binary: anything already past its end-of-life date failed the
build, and anything not yet past it was invisible. A runtime that died two years
ago and one that dies next quarter are not the same problem, and a gate that
cannot tell them apart gets switched off.

Each EOL date is now mapped to a synthetic severity by its horizon (retired,
within 30 days, this quarter, next quarter) using the organisation's own mapping
from its quality-gate policy. Those four eol*Severity columns have existed, with
sensible defaults, since the quality-gate table was created, and nothing has ever
read them -- because until organisations were seeded a policy row,
cli.quality-gate-get answered {"config": null} for every org alive and the CLI
never got as far as looking. A bucket set to "skip" produces nothing at all.

Blocking behaviour is deliberately unchanged. Only findings at or above the block
floor fail the build, and the floor defaults to critical, which is the retired
bucket's default severity -- so exactly what failed a build yesterday fails it
today, and everything closer to the horizon is reported rather than enforced.
Grading arrived with a CLI release, not with any org's decision to adopt it, and
a release that turned "your runtime dies next quarter" into a red build would
break CI for every customer who has ever passed --block-eol. --block-eol-severity
opts into more.

Author: 0x73746F66

.repo/policy-fetch.md

@@ -0,0 +1,94 @@
+# Policy Fetch
+
+Last Updated: 2026-07-14
+
+The CLI fetches three kinds of organisation policy from vdb-api. This document covers what each fetch does with the answer, and (the part worth reading) what `{"config": null}` used to mean and no longer does.
+
+Server side: [vdb-api/.repo/auth-and-tenancy.md](https://github.com/vulnetix/vdb-api/blob/main/.repo/auth-and-tenancy.md). Identity model: [vulnetix-authentic-aws/.repo/identity-model.md](https://github.com/vulnetix/vulnetix-authentic-aws/blob/main/.repo/identity-model.md).
+
+## The three fetches
+
+| Endpoint | Client method (`pkg/vdb/api_cli.go`) | Consumers |
+| --- | --- | --- |
+| `POST /v2/cli.quality-gate-get` | `CliQualityGateGet` | `applyOrgQualityGate` at scan time (`cmd/quality_gate_enforce.go`); `config get quality-gate` (`renderQualityGateGet`) |
+| `POST /v2/cli.package-firewall-get` | `CliPackageFirewallGet` | `config get package-firewall` (`renderPackageFirewallGet`) |
+| `POST /v2/cli.ai-firewall-baseline` | `CliAiFirewallBaseline` | `ai-firewall baseline`; composed into `ai-firewall apply` when `spec.baseline.enabled` |
+
+All three are read-only, all three carry an empty payload. The org is resolved from the authenticated request, and none of them creates anything server-side.
+
+The uuid in the API key identifies a **principal**. The policy that comes back belongs to that principal's **tenant**, resolved server-side by `TenantOrgID`. A Teams member and their owner run the same `vulnetix scan` and are gated by one policy, which is the entire point of the split.
+
+## Quality gate at scan time
+
+```mermaid
+sequenceDiagram
+    participant Scan as vulnetix scan
+    participant AQG as applyOrgQualityGate
+    participant API as vdb-api
+    participant SA as SaaS Postgres
+
+    Scan->>AQG: qualityGateOverridePointers{9 scan-time locals}
+    AQG->>AQG: auth.LoadCredentials()
+    alt no creds, or community tier
+        AQG-->>Scan: no-op, scan flags and builtin defaults stand
+    end
+    AQG->>API: POST /v2/cli.quality-gate-get (ApiKey = principal)
+    API->>API: TenantOrgID(principal) → tenant
+    API->>SA: SELECT ... FROM "CliQualityGateConfig" WHERE "orgUuid" = tenant
+    alt lookup fails
+        API-->>AQG: error
+        AQG-->>Scan: no-op, scan flags stand (verbose notes it)
+    end
+    SA-->>API: row (or none)
+    API-->>AQG: {"config": {...}} or {"config": null}
+
+    alt config == null
+        AQG-->>Scan: "no policy configured", scan flags stand
+    else config present
+        loop each of the 9 enforcement fields
+            AQG->>AQG: field null? → leave the caller's local alone
+            AQG->>AQG: field set?  → OVERWRITE the local; ORG POLICY ALWAYS WINS
+        end
+        AQG-->>Scan: locals now carry the org's enforcement
+    end
+```
+
+Two semantics are decided and should not be relitigated without a reason.
+
+**Org policy always wins.** A value the org has set overrides even an explicitly-passed CLI flag. `noteOverride` prints `--severity high superseded by org policy: critical` under `--verbose`. A security policy a developer can turn off with a flag is not a policy.
+
+**NULL means "not set", not "false".** `qgConfigBool` / `qgConfigInt` / `qgConfigString` each return a second boolean that is false when the field is absent or JSON `null`, and the caller then leaves its local untouched. This is what makes the seeded defaults safe: a freshly-provisioned org has all nine enforcement columns NULL, so its CI behaves exactly as it did before it had a policy row at all.
+
+## What `{"config": null}` used to mean
+
+It meant **every organisation**, and it meant that for the entire life of the product.
+
+Nothing ever seeded a `CliQualityGateConfig` row. Not `register`, not the OIDC callback, not the Stripe webhook. The three doors each did their own thing and none of them wrote a line of policy. So `POST /v2/cli.quality-gate-get` returned `{"config": null}` for every org that had ever existed, and `applyOrgQualityGate` took its "no policy configured" early return every single time. The four EOL-to-severity columns (`eolNextQuarterSeverity`, `eolThisQuarterSeverity`, `eolWithin30DaysSeverity`, `eolRetiredSeverity`), all with perfectly good defaults, were unreachable dead schema. The feature was wired end to end and could not fire.
+
+Since `ProvisionOrg` ([vdb-site/.repo/org-provisioning.md](https://github.com/vulnetix/vdb-site/blob/main/.repo/org-provisioning.md)), a new org is seeded at creation with the EOL buckets populated and the nine enforcement columns left NULL. So today:
+
+- **`{"config": null}`** means an org that predates the seeder and has not been backfilled. It is now the exception, not the rule.
+- **`{"config": {...}}` with every enforcement field null** means a seeded org that has not opted into enforcement. This is the normal state of a new org, and it is why an upgrade does not suddenly start failing builds that used to pass. Enforcement is a decision a human makes.
+- **`{"config": {...}}` with fields set** means an owner configured it, and it wins.
+
+The CLI needs no change for any of this: `renderQualityGateGet` already prints a "no policy configured" line for a nil config and "not set" for each null field, and `applyOrgQualityGate` already treats the two cases differently. What changed is which branch actually gets taken.
+
+## Package firewall
+
+`CliPackageFirewallGet` returns `{"config": {...}|null, "mirrors": [...]}`. For a nil config, `renderPackageFirewallGet` reports that no policy is configured and that the proxy defaults apply, which is now literally true: the proxy's in-memory defaults are the same open values the columns declare, and package-firewall no longer writes a row on a read ([package-firewall/.repo/org-policy-resolution.md](https://github.com/vulnetix/package-firewall/blob/main/.repo/org-policy-resolution.md)).
+
+A seeded org has a permissive config row (every threshold `0`, every block `false`) plus the mirrors package-firewall backfills for each ecosystem. The `mirrors` array is populated from the tenant's config row, so every member of an org sees the same mirror set.
+
+## AI firewall baseline
+
+`CliAiFirewallBaseline` fetches the server's recommended guardrail set. It is composed into `ai-firewall apply` when `spec.baseline.enabled` is true, and it **soft-fails on 404** unless `--baseline-required`. An older server simply may not have the endpoint.
+
+The same baseline is what vdb-site seeds onto a new org, and this is deliberate: vdb-site embeds the output of vdb-api's `cmd/baseline-export` rather than keeping a hand-copied second list, so "baseline 2026.07.1" cannot be one set of rules over the wire and a different set in the database. 23 guardrails, 21 enabled; `injection-delimiter-spoof` and `pii-phone` ship disabled because a guardrail that cries wolf teaches an organisation to switch the firewall off.
+
+The practical consequence for `apply`: on a freshly provisioned org, the guardrails the server reports as the baseline are already present as rows, so a first `apply` with the baseline composed in is close to a no-op rather than a bulk create. Guardrails reconcile by **name**, which is what makes that idempotent.
+
+## Related documents
+
+- [vdb-api/.repo/auth-and-tenancy.md](https://github.com/vulnetix/vdb-api/blob/main/.repo/auth-and-tenancy.md). How the API key becomes a tenant, and the 401/403/409/503 rules the CLI's retry logic sees.
+- [vdb-site/.repo/org-provisioning.md](https://github.com/vulnetix/vdb-site/blob/main/.repo/org-provisioning.md). What gets seeded and why the defaults are asymmetric.
+- [vulnetix-authentic-aws/.repo/identity-model.md](https://github.com/vulnetix/vulnetix-authentic-aws/blob/main/.repo/identity-model.md), the hub.

cmd/quality_gate_enforce.go

@@ -15,6 +15,7 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"github.com/vulnetix/cli/v3/internal/scan"
 	"github.com/vulnetix/cli/v3/pkg/auth"
 	"github.com/vulnetix/cli/v3/pkg/vdb"
 )
@@ -33,6 +34,12 @@ type qualityGateOverridePointers struct {
 	exploits               *string
 	severity               *string
 	scaAutofixStrategy     *string
+
+	// eolBuckets is the org's EOL-horizon-to-severity mapping. Unlike the nine
+	// fields above it is NOT nullable enforcement — the columns are NOT NULL and
+	// carry defaults — so it is not an override but a setting, and it is only read
+	// when --block-eol is in effect.
+	eolBuckets *scan.EOLSeverityBuckets
 }
 
 // applyOrgQualityGate fetches the authenticated org's quality-gate policy and
@@ -108,6 +115,26 @@ func applyOrgQualityGate(cmd *cobra.Command, p qualityGateOverridePointers) {
 		noteOverride(cmd, flag, callerVal, orgVal)
 	}
 
+	// The EOL severity buckets. These four columns have existed, with sensible
+	// defaults, since the quality-gate table was created — and nothing has ever
+	// read them, because until organisations were seeded a config row, this handler
+	// returned {"config": null} for every org on the platform and we never got this
+	// far. They grade an EOL horizon instead of treating every EOL alike.
+	if p.eolBuckets != nil {
+		if v, ok := qgConfigString(config, "eolRetiredSeverity"); ok {
+			p.eolBuckets.Retired = v
+		}
+		if v, ok := qgConfigString(config, "eolWithin30DaysSeverity"); ok {
+			p.eolBuckets.Within30Days = v
+		}
+		if v, ok := qgConfigString(config, "eolThisQuarterSeverity"); ok {
+			p.eolBuckets.ThisQuarter = v
+		}
+		if v, ok := qgConfigString(config, "eolNextQuarterSeverity"); ok {
+			p.eolBuckets.NextQuarter = v
+		}
+	}
+
 	applyBool("block-eol", "blockEol", p.blockEol)
 	applyBool("block-malware", "blockMalware", p.blockMalware)
 	applyBool("block-unpinned", "blockUnpinned", p.blockUnpinned)

cmd/scan.go

@@ -64,6 +64,29 @@ type GateBreach struct {
 	Message string // pre-formatted, ready to print
 }
 
+// orgEOLBuckets maps an end-of-life horizon to a severity. It starts at the same
+// defaults the CliQualityGateConfig columns declare, and applyOrgQualityGate
+// overwrites it with the org's own mapping when the scan is authenticated.
+//
+// Package-level for the same reason `verbose` is: the gate that consumes it sits
+// behind a thirty-argument positional signature, and threading a thirty-first
+// through it would obscure the change rather than clarify it.
+var orgEOLBuckets = scan.DefaultEOLSeverityBuckets()
+
+// eolBlockSeverity is the floor at which a graded EOL finding actually FAILS the
+// build, as opposed to merely being reported.
+//
+// It defaults to `critical`, which is the default severity of the `retired`
+// bucket — so by default exactly what failed a build before grading existed fails
+// it now: components already past their end-of-life date. Everything closer to the
+// horizon is reported and does not break anyone's pipeline.
+//
+// This default is deliberately conservative. Grading arrived with the CLI release,
+// not with an org's decision to adopt it, and a release that turns "your runtime
+// dies next quarter" into a red build would break CI for every customer who has
+// ever passed --block-eol.
+var eolBlockSeverity = "critical"
+
 // MultiPolicyBreachError is returned when one or more quality gates are breached.
 type MultiPolicyBreachError struct {
 	Breaches []GateBreach
@@ -401,6 +424,9 @@ func runScanWithFeatures(ctx context.Context, cmd *cobra.Command, noSAST, noSCA,
 
 	blockMalware, _ := cmd.Flags().GetBool("block-malware")
 	blockEOL, _ := cmd.Flags().GetBool("block-eol")
+	if v, _ := cmd.Flags().GetString("block-eol-severity"); v != "" {
+		eolBlockSeverity = strings.ToLower(strings.TrimSpace(v))
+	}
 	blockUnpinned, _ := cmd.Flags().GetBool("block-unpinned")
 	exploitThreshold, _ := cmd.Flags().GetString("exploits")
 	resultsOnly, _ := cmd.Flags().GetBool("results-only")
@@ -432,6 +458,7 @@ func runScanWithFeatures(ctx context.Context, cmd *cobra.Command, noSAST, noSCA,
 	// / community scans and orgs without a policy leave these values untouched.
 	applyOrgQualityGate(cmd, qualityGateOverridePointers{
 		blockEol:               &blockEOL,
+		eolBuckets:             &orgEOLBuckets,
 		blockMalware:           &blockMalware,
 		blockUnpinned:          &blockUnpinned,
 		cooldown:               &cooldownDays,
@@ -1795,34 +1822,71 @@ func runLocalScan(
 	}
 
 	// Gate 4: EOL — best-effort runtime version pin detection + VDB EOL API.
+	//
+	// GRADED for reporting, but the BLOCKING behaviour is unchanged. Each
+	// end-of-life date is mapped to a synthetic severity by how close it is
+	// (retired / within 30 days / this quarter / next quarter) using the org's own
+	// mapping, so a runtime that died two years ago and one that dies next quarter
+	// stop looking like the same problem. A bucket the org set to "skip" produces
+	// nothing at all.
+	//
+	// Only components AT OR ABOVE the block floor actually fail the build, and the
+	// floor defaults to `critical`, which is the `retired` bucket's default
+	// severity. So out of the box exactly what failed a build yesterday fails it
+	// today, and everything else is reported rather than enforced. Grading a
+	// next-quarter EOL into a red build would turn an upgrade of the CLI into a
+	// fleet-wide CI outage, and a gate that does that gets switched off — which
+	// protects nobody.
+	//
+	// An org opts into stricter blocking with --block-eol-severity (high, medium,
+	// low). Doing it through the org's quality-gate policy needs a column that does
+	// not exist yet; that is a follow-up, not a reason to ship a breaking default.
+	//
+	// This is what the four eol*Severity columns were always for. Nothing read them
+	// until organisations started being seeded a policy row — before that,
+	// cli.quality-gate-get answered {"config": null} for every org alive and the
+	// CLI never got as far as looking.
 	if blockEOL {
 		eolClient := newSearchClient()
 		pins := scan.DetectRuntimeVersionPins(rootPath)
-		var eolViolations []string
+		now := time.Now()
+
+		type eolItem struct {
+			label    string
+			severity string
+			horizon  scan.EOLHorizon
+		}
+		var graded []eolItem
+
+		grade := func(eolFrom, label string) {
+			horizon := scan.EOLHorizonOf(eolFrom, now)
+			severity, ok := orgEOLBuckets.SeverityFor(horizon)
+			if !ok {
+				return
+			}
+			graded = append(graded, eolItem{label: label, severity: severity, horizon: horizon})
+		}
+
 		for _, pin := range pins {
 			resp, err := eolClient.EOLRelease(pin.Product, pin.Release)
 			if err != nil {
 				continue // silently skip: unknown product / network error
 			}
-			if resp.Release.IsEol {
-				eolViolations = append(eolViolations, fmt.Sprintf("%s %s (%s)", pin.Product, pin.RawVersion, pin.SourceFile))
+			eolFrom := ""
+			if resp.Release.EolFrom != nil {
+				eolFrom = *resp.Release.EolFrom
 			}
-		}
-		if len(eolViolations) > 0 {
-			breaches = append(breaches, GateBreach{
-				Gate:  "eol",
-				Count: len(eolViolations),
-				Message: fmt.Sprintf("--block-eol: %s end-of-life: %s",
-					pluralise("runtime", len(eolViolations)),
-					strings.Join(eolViolations, ", ")),
-			})
+			// An EOL feed that says "this is EOL" but gives no date still means EOL.
+			if eolFrom == "" && resp.Release.IsEol {
+				eolFrom = now.Format("2006-01-02")
+			}
+			grade(eolFrom, fmt.Sprintf("%s %s (%s)", pin.Product, pin.RawVersion, pin.SourceFile))
 		}
 
 		// Package-level EOL — from /v2/cli.sca PackageInsights (the server maps
 		// each package to its EolProduct/EolRelease and matches the installed
 		// version's release line). Packages with no EOL row are skipped.
 		seenPkgEol := map[string]bool{}
-		var eolPkgList []string
 		for _, p := range allPackages {
 			if p.Version == "" {
 				continue
@@ -1833,24 +1897,52 @@ func runLocalScan(
 			}
 			seenPkgEol[purl] = true
 			ins, ok := insightByPurl[purl]
-			if !ok || !ins.IsEOL {
+			if !ok {
 				continue
 			}
-			label := fmt.Sprintf("%s@%s (%s)", p.Name, p.Version, p.Ecosystem)
-			if ins.EOLFrom != "" {
-				label = fmt.Sprintf("%s@%s (%s, EOL since %s)", p.Name, p.Version, p.Ecosystem, ins.EOLFrom)
+			eolFrom := ins.EOLFrom
+			if eolFrom == "" && ins.IsEOL {
+				eolFrom = now.Format("2006-01-02")
 			}
-			eolPkgList = append(eolPkgList, label)
+			grade(eolFrom, fmt.Sprintf("%s@%s (%s)", p.Name, p.Version, p.Ecosystem))
 		}
-		if len(eolPkgList) > 0 {
+
+		// One breach per severity, so the report reads as a priority list rather
+		// than one undifferentiated pile. Only severities at or above the floor
+		// breach; the rest are reported and do not fail the build.
+		var approaching []eolItem
+		for _, severity := range []string{"critical", "high", "medium", "low"} {
+			var labels []string
+			for _, item := range graded {
+				if item.severity != severity {
+					continue
+				}
+				if !scan.SeverityMeetsThreshold(severity, eolBlockSeverity) {
+					approaching = append(approaching, item)
+
+					continue
+				}
+				labels = append(labels, item.label)
+			}
+			if len(labels) == 0 {
+				continue
+			}
 			breaches = append(breaches, GateBreach{
 				Gate:  "eol",
-				Count: len(eolPkgList),
-				Message: fmt.Sprintf("--block-eol: %s end-of-life: %s",
-					pluralise("package", len(eolPkgList)),
-					strings.Join(eolPkgList, ", ")),
+				Count: len(labels),
+				Message: fmt.Sprintf("--block-eol (%s): %s end-of-life: %s",
+					severity, pluralise("component", len(labels)), strings.Join(labels, ", ")),
 			})
 		}
+
+		// Approaching end-of-life. Not a breach — said plainly so it can be planned
+		// for, rather than discovered on the day it starts failing the build.
+		if len(approaching) > 0 && !resultsOnly {
+			fmt.Fprintf(os.Stderr, "\nApproaching end-of-life (not blocking; raise with --block-eol-severity):\n")
+			for _, item := range approaching {
+				fmt.Fprintf(os.Stderr, "  %-14s %s (%s)\n", item.horizon, item.label, item.severity)
+			}
+		}
 	}
 
 	// Gate 5: unpinned direct dependencies
@@ -4175,6 +4267,7 @@ func addScanFlags(cmd *cobra.Command) {
 	cmd.Flags().Bool("block-malware", false, "Exit with code 1 when any dependency is a known malicious package.")
 	cmd.Flags().Bool("no-malscan", false, "Skip the in-process malscan-engine pass over local dependency install dirs.")
 	cmd.Flags().Bool("block-eol", false, "Exit with code 1 when a runtime or package dependency is end-of-life. Runtimes: Go, Node.js, Python, Ruby. Package-level checks activate when VDB has EOL data (404s are silently skipped).")
+	cmd.Flags().String("block-eol-severity", "critical", "With --block-eol, the graded severity at which an end-of-life component fails the build (critical, high, medium, low). Components graded below it are reported, not blocked. The default blocks only what is already past its end-of-life date.")
 	cmd.Flags().Bool("block-unpinned", false, "Exit with code 1 when any direct dependency uses a version range (^, ~, >=) instead of an exact pin.")
 	cmd.Flags().String("exploits", "", "Exit with code 1 when exploit maturity reaches the threshold: poc (any public exploit), active (CISA/EU KEV / actively exploited), weaponized (in-the-wild only).")
 	cmd.Flags().Bool("results-only", false, "Only output when findings exist; completely silent when the scan is clean.")