Sprint 018 — Vulnerability Intelligence: TIDB Gap Analysis

• Capability: Vulnerability Knowledge & Risk Correlation Intelligence
• Sprint: 018 · Wave 12
• Status: Ratified
• Companion: Architecture & Reference

1. Scope of analysis

This report inventories the Target Intelligence Database (TIDB) surface that the vulnerability intelligence capability reads and writes, identifies what already exists (reused unchanged), what is extended, and what is created new, and fixes the migration + registry steps needed so the canonical vulnerability knowledge, matches, risk assessments and history are first-class TIDB citizens — never memory-only.

2. Existing TIDB surface reused unchanged (no writes)

These are read-only inputs: the vulnerability capability folds them into correlation and exposure context; it never mutates them.

3. Existing TIDB surface extended (schema additions)

None of the existing tables require column additions or constraint changes. The Wave 12 canonical knowledge, correlation and risk inventory is carried by new tables (below), which is the least-risk path: no migration of populated rows, no breaking changes, and the registry’s name-based auto-mapping (<Name>Model ↔ <Name>) keeps the existing entities untouched.

4. New TIDB entities required (created)

All new entities derive from TidbEntity and get mirrored ORM models in infrastructure/db/sql/tidb_models/vulnerability_models.py. Names follow the <Entity>Model ↔ <Entity> convention so the generic registry derives repositories automatically. Envelope fields (id, created_at, updated_at, first_seen, last_seen, version, revision, schema_version, deleted_at, meta) are present on every table.

4.1 Vulnerability → tidb_vulnerabilities

Canonical vulnerability record (CVE projection with full knowledge context).

4.2 CVERecord → tidb_cve_records

Knowledge-layer CVE projection (vendor/product, CVSS v3/v4, KEV/PoC flags).

4.3 CWERecord → tidb_cwe_records

Canonical CWE with hierarchy.

4.4 Cpe → tidb_cpes

Canonical CPE 2.3 identifier.

4.5 Purl → tidb_purls

Canonical Package URL.

4.6 Vendor / Product → tidb_vendors / tidb_products

Canonical vendor/product references with aliases and CPE hints.

4.7 Version / VersionRange → tidb_versions / tidb_version_ranges

Canonical version records and version intervals with inclusive/exclusive bounds.

4.8 Advisory → tidb_advisories

Normalized vendor security advisories (advisory id, vendor, title, CVE ids, severity, release date, URL, affected product descriptors).

4.9 CvssRecord → tidb_cvss_records

Normalized CVSS (version, vector, base score, severity, parsed metrics).

4.10 EpssRecord → tidb_epss_records

Normalized EPSS (probability, percentile, predicted date).

4.11 KevRecord → tidb_kev_records

CISA KEV membership (in_kev, date added, due date, vendor, product).

4.12 ExploitabilityIndicator → tidb_exploitability_indicators

Safe exploit-availability metadata (availability, indicators, public-exploit/ metasploit/exploit-db/github-poc/known-exploited flags, references).

4.13 AffectedProduct → tidb_affected_products

Affected product / version-range per CVE (vendor, product, CPE, ranges, versions, fixed versions, platform).

4.14 FixedVersion → tidb_fixed_versions

Version that fixes a CVE for a product.

4.15 VulnerabilityMatch → tidb_vulnerability_matches

The technology→vulnerability correlation result with explicit match state.

4.16 RiskAssessment → tidb_risk_assessments

Deterministic risk assessment (score, priority, factor breakdown, formula version, calculated at, match/asset/CVE provenance).

4.17 AssetRisk → tidb_asset_risks

Aggregated asset risk (max score/priority, band counts, KEV count, knowledge version, assessed at).

4.18 VulnerabilityEvidence → tidb_vulnerability_evidence

Evidence fragment per match (evidence type, value, source, confidence, detail).

4.19 HistoricalVulnerabilityState → tidb_historical_vulnerability_states

Immutable per-asset vulnerability snapshot (CVE ids, top risk, band counts, knowledge version, recorded at).

4.20 KnowledgeSource → tidb_knowledge_sources

Knowledge-source freshness (last refreshed, record count, effective date, schema version, analysis version, stale flag, last error).

4.21 KnowledgeRefresh → tidb_knowledge_refreshes

Refresh run observability record (sources, status, records, duration, summary, error).

5. Migration plan

• Migration file: alembic/versions/ec9883419830_vulnerability_intelligence_tables.py
• down_revision = 7ea0dbfc111d (current head — cloud/saas intelligence)
• Creates 23 tables with the full 10-column TidbModelMixin envelope.
• Applied and rolled back cleanly (alembic upgrade head / alembic downgrade round-trip verified).
• Indexes use the ix_tidb_<table>_<col> naming convention; composite indexes get explicit names.

6. Registry + repository wiring

• Add <Name>Model to tidb_models/__init__.py __all__ — this is the only registry step; the name-derived registry auto-maps <Name>Model ↔ <Name>.
• Entities exported from domain/entities/tidb/__init__.py.
• Generic SqlCrudRepository / InMemoryCrudRepository and RowMapper handle persistence with zero per-entity code.
• In-memory factory enables the out-of-the-box, zero-service mode.

7. Verification steps (gates)

1. python -m alembic upgrade head — applies the migration.
2. python -m alembic downgrade base then upgrade head — round-trips.
3. python -m pytest tests/architecture — no regression (API baseline in sync).
4. python -m pytest tests/unit -k vulnerability — entity + repository tests.
5. python -m pytest tests/integration/test_vulnerability_platform.py — SQL write/read round-trip via the assembled platform.
6. python -m pytest tests/security/test_vulnerability_security.py — boundary + contamination tests.
7. python -m pytest tests/acceptance/test_vulnerability_acceptance.py — end-to-end persistence.
8. python -m ruff check src tests/unit tests/integration tests/acceptance tests/security tests/performance — clean.