primarysource 0.1.0__py3-none-any.whl

primarysource/cursor.py

@@ -0,0 +1,82 @@
+"""The two cursors of PLAN.md §5.11 as the plain collections use them.
+
+- A **list** (search, outline, browse, grep, docs) takes a 0-based `start` and prints `next: start=<n>`
+  (`render.next_start`), exactly the value to pass back. `window` cuts the page and makes that value.
+- A **read** prints `next: <ref>`, a ref string that `read` accepts back: the scope that was read with `¶<n>`
+  naming the first unit of the next page. So a `¶n` read starts at unit n and continues, within `max_tokens`,
+  to the end of the scope the ref names; one unit alone is what `cite` gives. `read_next` makes that ref.
+
+A whole document is a scope too, and its units are counted the same way, so `doc¶n` continues a document read.
+The core grammar refuses `¶` without a section (`refs.RefGrammar`), so `split_doc_para` takes it off first.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from primarysource.budget import Page
+from primarysource.errors import LibError
+from primarysource.render import next_start
+
+_DOC_PARA = re.compile(r"(?P<head>[^§#¶]+?)\s*¶\s*(?P<para>\d+)\s*")
+_TRAILING_PARA = re.compile(r"(?P<head>[^¶]+?)\s*¶\s*(?P<para>\d+)\s*")
+
+
+def window[T](rows: Sequence[T], start: int, limit: int) -> tuple[Sequence[T], str]:
+    """Rows `start .. start+limit` (0-based) and the `next:` value: `start=<n>`, or "" on the last page."""
+    if start < 0:
+        raise LibError(f"start is a 0-based offset, not {start}", "pass the start= value of the last next: line")
+    if limit < 1:
+        raise LibError(f"limit must be 1 or more, not {limit}", "")
+    end = start + limit
+    return rows[start:end], next_start(end if end < len(rows) else None)
+
+
+def split_doc_para(text: str) -> tuple[str, int | None]:
+    """`doc¶n` as (`doc`, n); any other text as (text, None), for the collection's own parser to read."""
+    if "§" in text or "::" in text or "#" in text:
+        return text, None
+    match = _DOC_PARA.fullmatch(text)
+    if match is None:
+        return text, None
+    para = int(match["para"])
+    if para < 1:
+        raise LibError(f"not a ref: {text!r}", "¶ is 1-based")
+    return match["head"].strip(), para
+
+
+def split_para(text: str) -> tuple[str, int | None]:
+    """A trailing `¶n` as (the rest, n), for a collection whose own ref grammar has no `¶` (`usbids:1d6b¶40`,
+    `nist:cavp/...#[P-256]¶3`); any other text as (text, None)."""
+    match = _TRAILING_PARA.fullmatch(text)
+    if match is None:
+        return text, None
+    para = int(match["para"])
+    if para < 1:
+        raise LibError(f"not a ref: {text!r}", "¶ is 1-based")
+    return match["head"].strip(), para
+
+
+def first_unit(para: int | None, total: int, what: str, ref: str) -> int:
+    """The 1-based unit a read starts at: `para`, or 1. A `para` past the end is an error naming the range."""
+    if para is None:
+        return 1
+    if para > total:
+        raise LibError(f"{ref}: the span has {total} {what}", f"use ¶1 to ¶{total}" if total else "")
+    return para
+
+
+def read_next(scope: str, page: Page) -> str:
+    """The `next:` value of a read: `<scope>¶<n>` where the next page starts, or "" when the scope is done."""
+    return f"{scope}¶{page.next_start}" if page.next_start is not None else ""
+
+
+def para_label(para: int | None, page: Page) -> int | str | None:
+    """What a read's citation names: None for a whole scope read from its start, `¶n` for one unit, `¶a-b` for a
+    page that starts inside the scope or holds several units of a `¶` read."""
+    if para is None and (page.first <= 1 or not page.units):
+        return None
+    if page.first == page.last:
+        return page.first
+    return f"{page.first}-{page.last}"

primarysource/cve/__init__.py

@@ -0,0 +1,5 @@
+"""The `cve` collection (moved in from cvelib): structured vulnerability data, local and citable."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

primarysource/cve/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

primarysource/cve/cli.py

@@ -0,0 +1,144 @@
+"""`primarysource cve ...`: the same answers as the MCP tools, as the same text; `--json` prints `service`'s dict.
+
+A failure prints the `error:`, `hint:` and `action:` lines of a `LibError` on stderr and exits 2 (PLAN.md §5.10)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from primarysource.errors import LibError
+
+from . import __version__, config, service, views
+from .sync import sync as run_sync
+
+
+def _print_json(payload: object) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="primarysource cve", description="Local vulnerability corpus and MCP server."
+    )
+    parser.add_argument("--version", action="version", version=f"primarysource cve {__version__}")
+    parser.add_argument("--json", action="store_true", help="print the raw JSON answer")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    commands.add_parser("path", help="show CVELIB_HOME and the index path")
+
+    info = commands.add_parser("info", help="corpus status, or a card for one CVE")
+    info.add_argument("ref", nargs="?", default="")
+
+    search = commands.add_parser("search", help="full-text search")
+    search.add_argument("query", nargs="+")
+    search.add_argument("--limit", type=int, default=8)
+    search.add_argument("--start", type=int, default=0)
+    search.add_argument("--kev", action="store_true")
+    search.add_argument("--kernel", action="store_true")
+    search.add_argument("--year", type=int, default=0)
+
+    read = commands.add_parser("read", help="one CVE, merged across sources (CVE-Y-N or CVE-Y-N§section)")
+    read.add_argument("ref")
+    read.add_argument("--max-tokens", type=int, default=2000)
+
+    kev = commands.add_parser("kev", help="CISA KEV status for a CVE, or the catalog newest first")
+    kev.add_argument("ref", nargs="?", default="")
+    kev.add_argument("--vendor", default="")
+    kev.add_argument("--since", default="")
+    kev.add_argument("--limit", type=int, default=20)
+    kev.add_argument("--start", type=int, default=0)
+
+    kernel = commands.add_parser("kernel", help="does this CVE affect this kernel version")
+    kernel.add_argument("ref")
+    kernel.add_argument("version")
+
+    kernel_list = commands.add_parser("kernel-list", help="every kernel CNA CVE that affects a version")
+    kernel_list.add_argument("version")
+    kernel_list.add_argument("--kev", action="store_true")
+    kernel_list.add_argument("--path", default="")
+    kernel_list.add_argument("--limit", type=int, default=25)
+    kernel_list.add_argument("--start", type=int, default=0)
+
+    sync = commands.add_parser("sync", help="fetch the sources and update the index")
+    sync.add_argument(
+        "--source", default=",".join(config.SOURCES), help="comma list of: " + ", ".join(config.SOURCES)
+    )
+    sync.add_argument("--kernel-tree", type=Path, help="ingest an existing vulns.git checkout instead of fetching")
+    sync.add_argument("--cvelist-zip", type=Path, help="ingest a local CVE List release zip instead of fetching")
+    sync.add_argument("--force", action="store_true", help="ignore the free-space check and any ETag")
+    sync.add_argument("--full", action="store_true", help="take the CVE List baseline even if a delta would do")
+
+    commands.add_parser("mcp", help="run the MCP server on stdio")
+    return parser
+
+
+def _show(args: argparse.Namespace, payload: dict[str, Any], view: Callable[[dict[str, Any]], str]) -> None:
+    if args.json:
+        _print_json(payload)
+    else:
+        print(view(payload), end="")
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    command = args.command
+    if command == "path":
+        if args.json:
+            _print_json({"home": str(config.home()), "index": str(config.index_path()), "env": "CVELIB_HOME"})
+        else:
+            print(views.path(str(config.home()), str(config.index_path())), end="")
+    elif command == "info":
+        _show(args, service.info(args.ref), views.info)
+    elif command == "search":
+        payload = service.search(" ".join(args.query), args.limit, args.start, args.kev, args.kernel, args.year)
+        _show(args, payload, views.search)
+    elif command == "read":
+        _show(args, service.read(args.ref, args.max_tokens), views.read)
+    elif command == "kev":
+        _show(args, service.kev(args.ref, args.vendor, args.since, args.limit, args.start), views.kev)
+    elif command == "kernel":
+        _show(args, service.kernel_check(args.ref, args.version), views.kernel_check)
+    elif command == "kernel-list":
+        payload = service.kernel_list(args.version, args.kev, args.path, args.limit, args.start)
+        _show(args, payload, views.kernel_list)
+    elif command == "sync":
+        results = run_sync(
+            [item.strip() for item in args.source.split(",") if item.strip()],
+            args.kernel_tree,
+            args.cvelist_zip,
+            args.force,
+            args.full,
+        )
+        for name, outcome in results.items():
+            print(f"{name}: {outcome}")
+        return 1 if any(value.startswith("FAILED") for value in results.values()) else 0
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    # Record text holds characters a Windows console's code page has no room for; a command whose job is to print
+    # it must not die on one.
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    args = _parser().parse_args(argv)
+    if args.command == "mcp":
+        from .mcp import main as serve
+
+        try:
+            serve()
+        except ImportError as error:
+            print(error, file=sys.stderr)
+            return 2
+        return 0
+    try:
+        return _dispatch(args)
+    except LibError as error:
+        print(error.as_text(), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

primarysource/cve/collection.py

@@ -0,0 +1,20 @@
+"""The CVE collection as primarysource sees it. Importing this needs nothing beyond the core."""
+
+from __future__ import annotations
+
+from primarysource.model import Unit
+from primarysource.refs import RefGrammar
+from primarysource.registry import Collection
+
+# cvelib's refs: CVE-2024-14027, CVE-2024-14027§references, CVE-2024-14027§references¶21. The section is one of a
+# fixed set of lower-case names (service.SECTIONS); ¶n is the nth item of a list section (reference, affected
+# entry, kernel range), not a paragraph of prose. The tools already carry the cve_ prefix.
+COLLECTION = Collection(
+    name="cve",
+    title="CVE records merged with the Linux kernel CNA, CISA KEV and FIRST EPSS, synced by the user",
+    prefix="cve_",
+    unit=Unit.BLOCK,
+    grammar=RefGrammar(r"CVE-\d{4}-\d{4,}", r"[a-z]+"),
+    server="primarysource.cve.mcp:build",
+    cli="primarysource.cve.cli:main",
+)

primarysource/cve/config.py

@@ -0,0 +1,58 @@
+"""Where the corpus lives and where it comes from.
+
+The corpus never lives in the working directory: MCP clients start servers from wherever they like, so a
+cwd-relative home would point every session at a different, empty library.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from primarysource.home import collection_home
+
+from . import __version__
+
+USER_AGENT = f"primarysource-cve/{__version__} (local vulnerability corpus sync)"
+
+KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
+EPSS_URL = "https://epss.empiricalsecurity.com/epss_scores-current.csv.gz"
+KERNEL_REPO_URL = "https://git.kernel.org/pub/scm/linux/security/vulns.git"
+CVELIST_RELEASE_API = "https://api.github.com/repos/CVEProject/cvelistV5/releases/latest"
+CVELIST_DELTA_LOG = "https://raw.githubusercontent.com/CVEProject/cvelistV5/main/cves/deltaLog.json"
+
+KERNEL_ORG_ID = "f4215fc3-5b6b-47ff-a258-f7189bd81038"
+CISA_ADP_SHORT_NAME = "CISA-ADP"
+
+SOURCES = ("cvelist", "kernel", "kev", "epss")
+
+# Age, in days, past which `info` and every tool call a source stale. Chosen per source's own cadence.
+STALE_DAYS = {"cvelist": 3, "kernel": 7, "kev": 7, "epss": 3}
+
+
+def home() -> Path:
+    """Where the corpus lives (PLAN.md §5.8). The first that applies: `$CVELIB_HOME` (an explicit setting from
+    before the move keeps working), `$PRIMARYSOURCE_CVE_HOME`, `$PRIMARYSOURCE_HOME/cve`, an existing `~/.cvelib`,
+    then the per-user `primarysource/cve`. Point one at a large disk: the corpus is a few GB. Nothing is created."""
+    explicit = any(os.environ.get(name) for name in ("CVELIB_HOME", "PRIMARYSOURCE_CVE_HOME", "PRIMARYSOURCE_HOME"))
+    legacy = Path.home() / ".cvelib"
+    if not explicit and legacy.is_dir():
+        return legacy
+    return collection_home("cve", "cvelib").expanduser()
+
+
+def index_path() -> Path:
+    return home() / "index.sqlite"
+
+
+def raw_dir() -> Path:
+    return home() / "raw"
+
+
+def kernel_repo_dir() -> Path:
+    return home() / "repos" / "kernel-vulns"
+
+
+def min_free_bytes() -> int:
+    """Free space a sync must leave behind. CVELIB_MIN_FREE_GB overrides the 2 GB default."""
+    return int(float(os.environ.get("CVELIB_MIN_FREE_GB") or "2") * 1024**3)

primarysource/cve/errors.py

@@ -0,0 +1,16 @@
+"""The one exception type for every state with a known remedy: a `LibError` (primarysource/errors.py).
+
+A tool that answers "no results" when the real state is "the corpus was never synced" sends an agent to conclude a
+CVE does not exist. Each such state raises `CvelibError` with the command that fixes it in `action` (what a human
+must run, e.g. `primarysource cve sync --source kev`) and the call to make next in `hint`. The CLI prints its
+`error:`, `hint:` and `action:` lines with exit status 2; the MCP server returns the same lines as an `isError`
+result (PLAN.md §5.10).
+"""
+
+from __future__ import annotations
+
+from primarysource.errors import LibError
+
+
+class CvelibError(LibError):
+    """A `LibError` raised by the cve collection; the name is kept so the code that raises it reads as it did."""

primarysource/cve/kernel.py

@@ -0,0 +1,232 @@
+"""Does a kernel CVE apply to one version? Read from the kernel CNA's `.dyad` files.
+
+A `.dyad` line is `vulnerable:git:fixed:git`, one per place the bug was introduced and (maybe) fixed:
+
+    6.6.51:c031...:6.6.133:9a3a...    bug arrived in 6.6.51, fixed in 6.6.133 on that stable branch
+    6.11:c3a5...:6.13:a718...         bug arrived in mainline 6.11, fixed in mainline 6.13
+    6.10.10:8d58...:0:0               arrived in 6.10.10, no fix on that branch
+
+The trap is the last form. A `0` fix means unfixed *on that start version's own branch*, which is often a stable
+branch that died long ago (`5.14.15:...:0:0`). Counting it as "unfixed everywhere" flags every later kernel. The rule
+here is `kconfigscope/tools/cve_reach.py` plus one correction: a bug whose introduction on the version's own branch
+comes *after* the last fix there (`6.18.51:...:0:0` beside a fix at 6.18.50) is still present.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .errors import CvelibError
+
+Version = tuple[int, ...]
+
+ZERO: Version = (0,)
+DEFAULT_RC_NOTE = "A release candidate is treated as the release it leads to."
+
+
+def parse_version(text: str) -> Version:
+    """`6.18.62`, `v6.18`, `4.4-rc1`, `6.18.20-1-lts`: the numeric dotted head of a kernel version string."""
+    head = text.strip().lower().removeprefix("v").split("-", 1)[0].split("+", 1)[0]
+    parts = head.split(".")
+    if not head or not all(part.isdigit() for part in parts):
+        raise CvelibError(f"not a kernel version: {text!r}", "Give a dotted version such as 6.18.62 or 6.12.")
+    numbers = [int(part) for part in parts]
+    # 6.18.0 and 6.18 are the same release; keeping one spelling makes tuple comparison correct.
+    while len(numbers) > 1 and numbers[-1] == 0:
+        numbers.pop()
+    return tuple(numbers)
+
+
+def version_caveats(text: str) -> list[str]:
+    """What the caller's version string implies that this data cannot speak to."""
+    notes: list[str] = []
+    suffix = text.strip().lower().removeprefix("v").split("-", 1)
+    if len(suffix) == 2 and suffix[1].startswith("rc"):
+        notes.append(DEFAULT_RC_NOTE)
+    elif len(suffix) == 2 and suffix[1]:
+        notes.append(
+            f"The suffix '-{suffix[1]}' looks like a distribution or local build. kernel.org data knows mainline "
+            "and stable releases, not distribution backports: check the distribution's own tracker too."
+        )
+    return notes
+
+
+@dataclass(frozen=True)
+class Pair:
+    """One dyad line. `start` of `(0,)` means the introducing commit is unknown; `fix` of `(0,)` means no fix."""
+
+    start: Version
+    start_git: str
+    fix: Version
+    fix_git: str
+
+    @property
+    def text(self) -> str:
+        return f"{_show(self.start)} -> {_show(self.fix)}"
+
+
+def _show(version: Version) -> str:
+    return "0" if version == ZERO else ".".join(str(part) for part in version)
+
+
+def parse_dyad(text: str) -> list[Pair]:
+    """Every `vulnerable:git:fixed:git` line. Comments and malformed lines are skipped, not guessed at."""
+    pairs: list[Pair] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or line.count(":") != 3:
+            continue
+        start, start_git, fix, fix_git = line.split(":")
+        try:
+            pairs.append(Pair(parse_version(start), start_git, parse_version(fix), fix_git))
+        except CvelibError:
+            continue
+    return pairs
+
+
+@dataclass(frozen=True)
+class Verdict:
+    affected: bool
+    reason: str
+    detail: str
+    evidence: tuple[str, ...]
+
+
+def _is_mainline(version: Version) -> bool:
+    return len(version) <= 2
+
+
+def explain(pairs: list[Pair], version: Version) -> Verdict:
+    """Whether the bug is present in `version`, preferring the fix on that version's own stable branch."""
+    branch = version[:2]
+
+    # A range opened on this branch and still open here is decisive: it survives an earlier fix on the branch.
+    # A `0` entry is weaker than a stated fix: dyad emits one for each introducing commit it could not pair, so a fix
+    # on this branch at or after that entry's start closes it. Only a start *after* every such fix reopens the bug.
+    branch_fixes = [pair.fix for pair in pairs if pair.fix != ZERO and pair.fix[:2] == branch and pair.fix <= version]
+    for pair in pairs:
+        same_branch_start = pair.start != ZERO and pair.start[:2] == branch and not _is_mainline(pair.start)
+        if not same_branch_start or pair.start > version:
+            continue
+        if pair.fix == ZERO:
+            if not any(fix >= pair.start for fix in branch_fixes):
+                detail = f"no fix on {_show(branch)}.x since {_show(pair.start)}"
+                return Verdict(True, "unfixed_on_branch", detail, (pair.text,))
+        elif pair.fix[:2] == branch and pair.fix > version:
+            return Verdict(True, "open_range", f"fixed on this branch only in {_show(pair.fix)}", (pair.text,))
+
+    # Then the fix on this branch, which is what decides almost every longterm kernel.
+    fixes_here = [pair for pair in pairs if pair.fix != ZERO and pair.fix[:2] == branch and pair.fix <= version]
+    if fixes_here:
+        best = max(fixes_here, key=lambda pair: pair.fix)
+        return Verdict(False, "fixed_on_branch", f"fixed on this branch in {_show(best.fix)}", (best.text,))
+
+    dead_zero: list[Pair] = []
+    open_pairs: list[Pair] = []
+    for pair in pairs:
+        if pair.start == ZERO and pair.fix == ZERO:
+            continue  # says nothing at all
+        if pair.start > version:
+            continue
+        if pair.fix == ZERO:
+            if _is_mainline(pair.start) or pair.start[:2] == branch:
+                open_pairs.append(pair)
+            else:
+                dead_zero.append(pair)
+        elif pair.fix > version:
+            open_pairs.append(pair)
+
+    if open_pairs:
+        pair = open_pairs[0]
+        if pair.fix == ZERO:
+            detail = f"unfixed from mainline {_show(pair.start)}"
+        elif pair.start == ZERO:
+            detail = f"introduction unknown; first fix past this version is {_show(pair.fix)}"
+        else:
+            detail = (
+                f"present since {_show(pair.start)}, no fix on {_show(branch)}.x, fixed later in {_show(pair.fix)}"
+            )
+        return Verdict(True, "open_range", detail, tuple(item.text for item in open_pairs[:4]))
+
+    if dead_zero:
+        return Verdict(
+            False,
+            "dead_branch_zero_ignored",
+            "the only open entries are '0' fixes on other stable branches, which say nothing about this one",
+            tuple(pair.text for pair in dead_zero[:4]),
+        )
+    if pairs and all(pair.start > version for pair in pairs if pair.start != ZERO):
+        return Verdict(False, "introduced_later", "every recorded introduction is newer than this version", ())
+    return Verdict(False, "fixed_before_version", "every recorded range closes at or before this version", ())
+
+
+def affects(pairs: list[Pair], version: Version) -> bool:
+    return explain(pairs, version).affected
+
+
+def fixed_in_by_branch(pairs: list[Pair]) -> dict[str, str]:
+    """`{"6.6": "6.6.133", "6.12": "6.12.77", "6.13": "6.13"}`, the earliest fix recorded on each branch."""
+    best: dict[Version, Version] = {}
+    for pair in pairs:
+        if pair.fix == ZERO:
+            continue
+        branch = pair.fix[:2]
+        if branch not in best or pair.fix < best[branch]:
+            best[branch] = pair.fix
+    return {_show(branch): _show(best[branch]) for branch in sorted(best)}
+
+
+def unfixed_starts(pairs: list[Pair]) -> list[str]:
+    return sorted({_show(pair.start) for pair in pairs if pair.fix == ZERO and pair.start != ZERO})
+
+
+WILDCARD_VERSIONS = {"", "*", "0", "n/a", "unspecified", "unknown", "-"}
+KERNEL_PRODUCTS = {"linux", "kernel", "linux kernel", "linux_kernel"}
+
+
+def is_kernel_product(entry: dict[str, object]) -> bool:
+    vendor = str(entry.get("vendor") or "").lower()
+    product = str(entry.get("product") or "").lower()
+    # Real spellings outside the kernel CNA include ("n/a", "Kernel") and ("Linux", "Linux Kernel").
+    anonymous = vendor in {"", "n/a"}
+    if product in {"linux kernel", "linux_kernel"}:
+        return True
+    if product == "kernel":
+        return "linux" in vendor or anonymous
+    return product == "linux" and "linux" in vendor
+
+
+def fallback_ranges(affected: list[dict[str, object]], version: Version) -> tuple[list[str], int]:
+    """Evaluate a non-kernel-CNA record's ranges for `version`.
+
+    Returns `(matches, usable)`. A record with no upper bound and a wildcard start (the usual NVD and early MITRE
+    kernel record) carries no usable range: such a record is noise, and it contributes nothing here.
+    """
+    matches: list[str] = []
+    usable = 0
+    for entry in affected:
+        if not is_kernel_product(entry):
+            continue
+        for item in entry.get("versions") or []:  # type: ignore[attr-defined]
+            if not isinstance(item, dict) or item.get("status") != "affected":
+                continue
+            start_text = str(item.get("version") or "").strip().lower()
+            upper = str(item.get("lessThan") or item.get("lessThanOrEqual") or "").strip()
+            inclusive = bool(item.get("lessThanOrEqual"))
+            if upper in {"", "*"} or upper.endswith(".*"):
+                upper = ""
+            if start_text in WILDCARD_VERSIONS and not upper:
+                continue
+            try:
+                start = parse_version(start_text) if start_text not in WILDCARD_VERSIONS else ZERO
+                end = parse_version(upper) if upper else None
+            except CvelibError:
+                continue
+            usable += 1
+            if end is None:
+                if start == version:
+                    matches.append(f"{start_text}")
+                continue
+            if start <= version and (version < end or (inclusive and version == end)):
+                matches.append(f"{start_text or '0'} -> {upper}")
+    return matches, usable