feat(scan): judge each CVE against the installed version

[maksimtech]

Audit finding PR-01 (critical) of 2026-10-17, first step: the scan judges CVEs against the installed version.

What was wrong

A scan found the CVEs that name a product and could not say which affect what is installed. The README said "tells you which vulnerabilities affect it". For Notepad++ the recorded NVD answer holds 21 CVEs; for 8.5.0, 11 of them concern other versions or another product, and all 21 were listed and ranked as work to do.

affected.py already knew how to answer (since 2026-09-28) and was deliberately not wired in, waiting for the watchlist columns of "the versionradar design, §5". That text was never committed and could not be found anywhere (E:\Dev, WSL, git history, notes).

What changes

• docs/DESIGN.md: the design the code referred to, rebuilt from what affected.py, inventory.py and test_priority_wiring.py already committed to. §5 covers the columns, the three verdicts, what the scan prints, what is stored and the order of work (01a, 01b, 01c). The three references in the code now point to it.

• Watchlist: five nullable columns with no default (cpe, vendor, product_id, installed_version, channel), migrated into existing databases.

• patchradar add <name> --version <v> --cpe <cpe>:

  • updates an existing entry;
  • refuses a version affected.py cannot order;
  • refuses a malformed CPE. notepad++ is refused with NVD's notepad\+\+ shown, because NVD would match nothing and the scan would read as clean.
  • The CPE is never guessed from the name (cpe.py).

• affected.judge: affected, not affected or not evaluable, from the record's own NVD configurations, which nvd._parse_item now keeps (an empty list while NVD has not analysed the CVE). "Cannot tell" never becomes "not affected". This covers:

  • no configurations;
  • a CVE from MSRC or KEV alone;
  • a version from another scheme.

  Range.comparable separates "outside the range" from "cannot be ordered", and closed_by is factored out of summarise.

• scan:

  • the table lists affected and not evaluable CVEs, with a Verdict column; --all adds not affected;
  • one line gives the split, one says what an update closes;
  • the NVD caveat is always printed;
  • entries without a version are scanned by name as before, and named at the end;
  • the total keeps its meaning (CVEs found by name).

• list shows version and CPE.

• Not in this PR, per DESIGN §5.6:

  • storing the verdict, judging KEV entries via NVD, and the API (PR-01b);
  • the web UI and import (PR-01c).

Tests (strict TDD)

• New files:
  • test_cpe.py;
  • test_watchlist_versions.py, with a hand-written pre-migration database;
  • test_affected_verdict.py, on the recorded Notepad++ NVD payload. It agrees with summarise: 10 affected and 11 not affected at 8.5.0, five fixes at 8.9.5;
  • test_scan_versioned.py, a full CLI scan against the same recording replayed with respx: MSRC 404, the KEV conftest catalogue. Derived variants (configurations removed, payload reduced to the affected ten) are declared in each test.
• All seen failing before the code. Guards added after the first green run (unbounded comparable, --all with nothing hidden, caveat on an empty answer, 5 of 5, set nothing) each kill their mutant: 26/26 mutants killed.
• test_cli_escaping.py: add called as a function now passes its new options. The list test no longer stubs get_watchlist: the hostile row is written straight into the test database, the way an older version left it.
• Full suite on Windows: 2169 passed. ruff and mypy clean.

🤖 Generated with Claude Code

[codspeed]

Merging this PR will not alter performance

⚠️ 11 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• test_init_db
• test_nvd_fetch_cves
• test_add_to_watchlist
• test_get_watchlist
• test_api_stats
• test_api_watchlist
• test_api_cve_detail
• test_get_cves_by_software
• test_api_cves_filtered
• test_get_cves
• …and 1 more

✅ 17 untouched benchmarks

---

_{Comparing feat/a-scan-that-knows-the-installed-version (df6f195) with main (a66861a)}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!