feat(vuln-id): backfill + reconciliation management commands

Maffooch · claude · Maffooch · commit ff473c6a9c38 · 2026-07-22T12:00:36.000-06:00
- migrate_vulnerability_ids: wraps dojo.vulnerability_id.backfill.run_backfill
  (the same routine 0286 runs); --window-size; PostgreSQL-guarded; prints per-step
  row counts; idempotent/resumable so big tenants pre-run it before the deploy.
- verify_vulnerability_ids: read-only reconciliation, nonzero exit on any drift so
  it can gate a ring flip. Per sampled finding (--sample, default 1000): every
  legacy (finding, id) pair has a reference; extra references allowed only when
  cve-only-derived (string == finding.cve); the order-0 reference == cve. Plus
  legacy-row / entity / reference / orphan-entity counts, both table names printed
  with roles. --json for machine output.

Tests (fixture-free): migrate backfills legacy-only findings to entities/refs with
order 0 == cve and is a no-op on re-run; verify passes on consistent data and
raises SystemExit on a legacy row with no matching reference.

Verified on the dev DB: migrate_vulnerability_ids runs clean and idempotent;
verify_vulnerability_ids exits 0.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/dojo/management/commands/migrate_vulnerability_ids.py b/dojo/management/commands/migrate_vulnerability_ids.py
@@ -0,0 +1,40 @@
+import logging
+
+from django.core.management.base import BaseCommand
+from django.db import connection
+
+from dojo.vulnerability_id.backfill import DEFAULT_WINDOW_SIZE, run_backfill
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+
+    """
+    Backfill the VulnerabilityId entity + FindingVulnerabilityReference tables from the legacy
+    dojo_vulnerability_id table and dojo_finding.cve.
+
+    Idempotent and resumable (insert-only + ON CONFLICT DO NOTHING), so it is safe to run
+    repeatedly: large tenants can pre-run it on the previous release, then it is an instant
+    catch-up during the deploy-time migration. Shares dojo.vulnerability_id.backfill.run_backfill
+    with migration 0286.
+    """
+
+    help = "Idempotently backfill the vulnerability-id entity + reference tables (PostgreSQL only)."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--window-size",
+            type=int,
+            default=DEFAULT_WINDOW_SIZE,
+            help=f"finding_id window size for the reference build (default {DEFAULT_WINDOW_SIZE}).",
+        )
+
+    def handle(self, *args, **options):
+        if connection.vendor != "postgresql":
+            self.stderr.write(f"Vulnerability-id backfill is PostgreSQL only; nothing to do on {connection.vendor}.")
+            return
+        counts = run_backfill(logger=logger, window_size=options["window_size"])
+        for step, count in counts.items():
+            self.stdout.write(f"{step}: {count}")
+        self.stdout.write(self.style.SUCCESS("Vulnerability ID backfill complete."))
diff --git a/dojo/management/commands/verify_vulnerability_ids.py b/dojo/management/commands/verify_vulnerability_ids.py
@@ -0,0 +1,113 @@
+import json
+import logging
+
+from django.core.management.base import BaseCommand
+from django.db.models import Q
+
+from dojo.models import Finding, FindingVulnerabilityReference, Vulnerability_Id, VulnerabilityId
+
+logger = logging.getLogger(__name__)
+
+# Both stores, with their roles — printed so operators know exactly what is being compared.
+LEGACY_TABLE = "dojo_vulnerability_id"          # legacy per-finding rows (authoritative for writes)
+ENTITY_TABLE = "dojo_vulnerabilityid"           # normalized VulnerabilityId registry
+REFERENCE_TABLE = "dojo_findingvulnerabilityreference"  # ordered Finding -> VulnerabilityId links
+
+
+class Command(BaseCommand):
+
+    """
+    Read-only reconciliation of the legacy vulnerability-id store against the entity/reference
+    store. Exits nonzero on any discrepancy, so it can gate a ring flip.
+
+    Checks per sampled finding: (1) every legacy (finding, id) pair has a matching reference;
+    extra references are tolerated ONLY when they are cve-only-derived (string == finding.cve);
+    (2) the order-0 reference string equals finding.cve wherever cve is set. Plus row / entity /
+    reference / orphan-entity counts.
+    """
+
+    help = "Verify the legacy vulnerability-id store matches the entity/reference store (nonzero exit on drift)."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--sample",
+            type=int,
+            default=1000,
+            help="Number of findings to spot-check for pair parity / order-0 (default 1000).",
+        )
+        parser.add_argument("--json", action="store_true", dest="as_json", help="Emit the report as JSON.")
+
+    def handle(self, *args, **options):
+        sample = options["sample"]
+        discrepancies = []
+
+        counts = {
+            f"legacy_rows ({LEGACY_TABLE})": Vulnerability_Id.objects.count(),
+            f"entities ({ENTITY_TABLE})": VulnerabilityId.objects.count(),
+            f"references ({REFERENCE_TABLE})": FindingVulnerabilityReference.objects.count(),
+            "orphan_entities": VulnerabilityId.objects.filter(finding_references__isnull=True).count(),
+        }
+
+        sampled = (
+            Finding.objects
+            .filter(
+                # Reverse relation query names: legacy FK -> "vulnerability_id", entity refs ->
+                # "vulnerability_references" (the "_set" form is the attribute accessor, not a lookup).
+                Q(vulnerability_id__isnull=False)
+                | Q(vulnerability_references__isnull=False)
+                | (Q(cve__isnull=False) & ~Q(cve="")),
+            )
+            .distinct()
+            .order_by("id")
+            .prefetch_related("vulnerability_id_set", "vulnerability_references__vulnerability")[:sample]
+        )
+
+        checked = 0
+        for finding in sampled:
+            checked += 1
+            legacy_strings = {row.vulnerability_id for row in finding.vulnerability_id_set.all()}
+            references = list(finding.vulnerability_references.all())
+            reference_strings = {ref.vulnerability.vulnerability_id for ref in references}
+
+            missing = legacy_strings - reference_strings
+            if missing:
+                discrepancies.append(f"finding {finding.id}: legacy ids missing a reference: {sorted(missing)}")
+
+            extras = reference_strings - legacy_strings
+            unexpected = {value for value in extras if value != finding.cve}
+            if unexpected:
+                discrepancies.append(f"finding {finding.id}: references with no legacy row (not cve-derived): {sorted(unexpected)}")
+
+            if finding.cve:
+                primary = next((ref for ref in references if ref.order == 0), None)
+                primary_string = primary.vulnerability.vulnerability_id if primary else None
+                if primary_string != finding.cve:
+                    discrepancies.append(
+                        f"finding {finding.id}: order-0 reference {primary_string!r} != cve {finding.cve!r}",
+                    )
+
+        report = {
+            "counts": counts,
+            "findings_checked": checked,
+            "discrepancies": discrepancies,
+            "ok": not discrepancies,
+        }
+
+        if options["as_json"]:
+            self.stdout.write(json.dumps(report, indent=2))
+        else:
+            self.stdout.write("Vulnerability ID store reconciliation")
+            for label, value in counts.items():
+                self.stdout.write(f"  {label}: {value}")
+            self.stdout.write(f"  findings checked: {checked}")
+            if discrepancies:
+                self.stdout.write(self.style.ERROR(f"  {len(discrepancies)} discrepancies:"))
+                for line in discrepancies:
+                    self.stdout.write(self.style.ERROR(f"    - {line}"))
+            else:
+                self.stdout.write(self.style.SUCCESS("  no discrepancies"))
+
+        if discrepancies:
+            # Nonzero exit for CI / ring-flip gating.
+            msg = f"{len(discrepancies)} vulnerability-id reconciliation discrepancies"
+            raise SystemExit(msg)
diff --git a/unittests/test_vulnerability_id.py b/unittests/test_vulnerability_id.py
@@ -8,6 +8,7 @@
 entity rows (orphans are retained).
 """
 from django.contrib.auth import get_user_model
+from django.core.management import call_command
 from django.test import TestCase, override_settings
 from django.utils.timezone import now
 
@@ -188,3 +189,47 @@ def test_filter_seam_parity(self):
                 set(finding_ids_with_vulnerability_ids("CVE-P-1", lookup="exact")),
                 {self.finding.pk},
             )
+
+
+class TestVulnerabilityIdCommands(VulnerabilityIdDualWriteTestCase):
+
+    """
+    migrate_vulnerability_ids backfills entities/references from legacy rows (idempotently);
+    verify_vulnerability_ids passes when the stores agree and exits nonzero on drift.
+    """
+
+    def test_migrate_command_backfills_idempotently(self):
+        finding = self._make_finding("cmd-migrate")
+        finding.cve = "CVE-CMD-1"
+        finding.save()
+        # Legacy rows WITHOUT entity references (bypassing the dual-write seam, i.e. pre-migration).
+        Vulnerability_Id.objects.create(finding=finding, vulnerability_id="CVE-CMD-1")
+        Vulnerability_Id.objects.create(finding=finding, vulnerability_id="CVE-CMD-2")
+        self.assertEqual(FindingVulnerabilityReference.objects.filter(finding=finding).count(), 0)
+
+        call_command("migrate_vulnerability_ids")
+
+        # cve-match lands at order 0.
+        self.assertEqual(self._refs(finding), {0: "CVE-CMD-1", 1: "CVE-CMD-2"})
+        self.assertTrue(VulnerabilityId.objects.filter(vulnerability_id="CVE-CMD-1").exists())
+
+        # Idempotent re-run: no change.
+        call_command("migrate_vulnerability_ids")
+        self.assertEqual(self._refs(finding), {0: "CVE-CMD-1", 1: "CVE-CMD-2"})
+        self.assertEqual(FindingVulnerabilityReference.objects.filter(finding=finding).count(), 2)
+
+    def test_verify_command_passes_when_consistent(self):
+        finding = self._make_finding("cmd-verify-ok")
+        save_vulnerability_ids(finding, ["CVE-V-1", "CVE-V-2"])
+        finding.save()
+        # Consistent stores => no SystemExit.
+        call_command("verify_vulnerability_ids")
+
+    def test_verify_command_fails_on_discrepancy(self):
+        finding = self._make_finding("cmd-verify-bad")
+        finding.cve = "CVE-BAD-1"
+        finding.save()
+        # Legacy row with no matching entity reference => a discrepancy.
+        Vulnerability_Id.objects.create(finding=finding, vulnerability_id="CVE-BAD-1")
+        with self.assertRaises(SystemExit):
+            call_command("verify_vulnerability_ids")
