Vulnerabilities hub — connector architecture and source policy

Status: Proposed (ADR-039 rev-3 D13; effective with the consolidation sprints). Owner direction 2026-07-22: obsolete the no-value connectors, drop region-locked connectors from the core, and make the plugin contract the only extension point so source choices never touch the hub.

1. Principles (why this survives decades)

1. The hub core is source-agnostic. No connector-specific tables, columns, or migrations in core schemas. Connector state lives in generic ingest.source_state; documents are content-addressed; facts carry issuer identity. Adding or removing a connector never migrates the hub.
2. Connectors are versioned plugins (restart-time, signed bundles — the existing plugin SDK). A connector’s contract is: stream documents → emit normalized facts with D4 identity + provenance in one transaction, report generation open/close, be deterministic and fixture-testable offline.
3. Signal types outlive signal sources. The fact model keeps first-class attributes such as exploited-in-the-wild and exploit probability (EPSS) even when a specific catalog feeding them is dropped — a future source (regional exploited-vuln catalogs, a revived KEV plugin) lights the same attribute without any model change.
4. Mirror import/export are plugins on the same contract — an air-gapped estate’s mirror bundle is just another source; export is the inverse. This is the tested recovery path (re-ingest), which is why the hub needs no conventional backup.
5. Region-locked sources are optional plugins, never core. Default profiles ship global sources only; regional estates enable their tier explicitly.

2. Source tiers

Tier 0 — core (default profile, all anonymous public feeds or local mirror; no credentials)

CVE (MITRE), NVD, OSV, EPSS (relocated here from the Scanner schema — see the consolidation review §3), KEV (CISA Known Exploited Vulnerabilities — returned to Tier 0 at ADR-039 rev-12: the round-20 review proved exploited-in-the-wild is load-bearing for the default-on RO release gate + Findings risk aggregation, no other Tier-0 source feeds it, and the catalog is credential-free; owner 2026-07-23: “don’t accept loss — we seek to be the best one”; program SPRINT_20260723_003), the distro family (Alpine, Amazon, Arch, Debian, Fedora, Gentoo, RedHat, SUSE, Ubuntu), vendor CSAF/VEX feeds with unique content (RedHat, SUSE/Rancher, Ubuntu, Oracle CSAF), OCI OpenVEX attestations, StellaOps mirror import.

Tier 1 — regional/optional plugins (kept, off by default; enable per estate)

RU-BDU and RU-NKCKI (deployed today; part of the sovereign/GOST market posture), JVN (JP), KISA (KR), CERT-Bund (DE), CERT-FR, CCCS (CA), ICS-CISA / ICS-Kaspersky, and the remaining vendor/national feeds not listed in Tier 0 or §3. Each remains a self-contained plugin with fixtures; none may add core schema.

Tier 3 — removed (code dropped; documented here for future re-add via the plugin contract)

Removal is complete deletion of the connector projects, their tests, fixtures, config (devops/etc/plugins/concelier/connectors/{ghsa,vndr-msrc}.yaml, …; kev.yaml stays — Tier 0), bundle entries, and doc references — not a disable flag. Re-adding any of them later is a plugin drop-in, which is the point of §1.1.

Consequence recorded: with Tier 0 fully credential-free, re-ingest (the fresh-rebuild recovery path) has no external credential dependency.

3. Connector conformance requirements (tested)

• Deterministic normalization: same document bytes → same fact identities/revision hashes.
• Fact + provenance + outbox in one transaction; generation open/close markers correct.
• Offline fixture suite per connector; no live network in tests.
• Disjoint applicability from one document produces distinct facts (D4 fixture applies to every connector).
• Capacity contract participation (P7): per-source quotas, budget pause honored.
• License gate (§2.6 of AGENTS.md) re-verified per retained connector at consolidation time.

4. Normalization carry-over audit (dig 2026-07-22)

Evidence-based scoping of the DC-01/DC-02 work in SPRINT_20260722_004:

• The advisory side is largely done. StellaOps.Concelier.Models.AffectedVersionRange (rangeKind, introducedVersion, fixedVersion, lastAffectedVersion, rangeExpression) with deterministic comparers and ToNormalizedVersionRule() already is the DC-01 applicability structure; mappers across the families emit it (verified in CVE, NVD, OSV, GHSA, RedHat, Fedora, Gentoo, Alpine, Debian, SUSE, Cccs, CertBund, CertCc, ICS-CISA, KISA, RU-BDU, Adobe, Apple, StellaOpsMirror — and the removed Cisco/KEV). Live proof: all 1,709,145 advisory_affected rows carry a version_range(690,456 also carry versions_fixed). The hub work here is: carry the model, wrap it in the DC-02 canonical hasher, and run a per-connector verification pass — not a rebuild.
• The VEX side is the real gap (DC-24). vex.claims persists no applicability columns at all, and vexhub.statements.versions is null for almost every row — the current pipeline discards exactly the range information whose absence made the old retention identity destructive. VEX applicability extraction (CSAF product_version_range/version branches, OpenVEX version events) is first-class normalization work in SPRINT_20260722_004 VULN-C2.
• Comparators to reuse (never re-invent): the shared src/__Libraries/StellaOps.VersionComparison library (e.g. DebianVersionComparer) plus Concelier’s Merge/Comparers (Nevra, ApkVersionComparer) and Normalization/Distro — 004’s design consolidates these behind the DC-01 scheme registry.
• Enrichment vs applicability: score/flag sources (EPSS probabilities, exploited-in-the-wild flags) are fact attributes, never applicability facts — they carry no ranges by nature and must not be forced into the range model.