attackmap 0.4.26__tar.gz → 0.4.27__tar.gz

{attackmap-0.4.26/src/attackmap.egg-info → attackmap-0.4.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.4.26
+Version: 0.4.27
 Summary: AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints.
 Author: AttackMap Contributors
 Author-email: Matthew Davis <matthewd@matthewd.xyz>

{attackmap-0.4.26 → attackmap-0.4.27}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attackmap"
-version = "0.4.26"
+version = "0.4.27"
 description = "AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints."
 readme = "README.md"
 requires-python = ">=3.11"

{attackmap-0.4.26 → attackmap-0.4.27}/src/attackmap/cli.py

@@ -126,7 +126,9 @@ def _run_fleet(
         )
         if cve and scan.dependencies:
             try:
-                vulns, _cve_summary = query_vulnerabilities(scan.dependencies)
+                vulns, _cve_summary = query_vulnerabilities(
+                    scan.dependencies, progress=scan_progress
+                )
             finally:
                 scan_progress.done()
             scan.vulnerabilities = vulns
@@ -434,9 +436,13 @@ def analyze(
         )
     if cve and scan.dependencies:
         typer.echo(f"Checking {len(scan.dependencies)} dependencies against OSV.dev…")
-        scan_progress.stage(f"Checking {len(scan.dependencies)} dependencies against OSV.dev")
+        # query_vulnerabilities drives a determinate begin/advance bar itself
+        # (per unique package), so big lockfile trees show real progress + ETA
+        # instead of an indeterminate spinner.
         try:
-            vulns, cve_summary = query_vulnerabilities(scan.dependencies)
+            vulns, cve_summary = query_vulnerabilities(
+                scan.dependencies, progress=scan_progress
+            )
         finally:
             scan_progress.done()
         scan.vulnerabilities = vulns

{attackmap-0.4.26 → attackmap-0.4.27}/src/attackmap/cve.py

@@ -7,9 +7,16 @@ and doesn't belong in an offline-only scan.
 
 ## Design summary
 
-- **Endpoint**: ``POST https://api.osv.dev/v1/query`` per (ecosystem,
-  name, version). Full details in a single response; simpler cache
-  semantics than the batch + fetch-by-id combo.
+- **Endpoints**: ``POST https://api.osv.dev/v1/querybatch`` in chunks of
+  up to ``_BATCH_SIZE`` (ecosystem, name, version) tuples — one request
+  covers hundreds of packages instead of one request per package (a
+  lockfile-resolved monorepo can carry thousands of pinned deps; per-
+  package queries took ~15 minutes on such repos). The batch response
+  carries vulnerability IDs only, so full records are then fetched via
+  ``GET https://api.osv.dev/v1/vulns/{id}`` — but only for the handful
+  of packages that actually have advisories, memoized per run. A batch
+  result that paginates (``next_page_token``, rare) falls back to the
+  classic ``POST /v1/query`` for that one package.
 - **Concrete version resolution**: OSV needs a concrete version to
   match against affected ranges. Manifests carry range specs
   (``^4.16.0``, ``>=2.28,<3``, ``latest``); we extract a best-effort
@@ -48,6 +55,10 @@ logger = logging.getLogger(__name__)
 
 
 _OSV_QUERY_URL = "https://api.osv.dev/v1/query"
+_OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch"
+_OSV_VULNS_URL = "https://api.osv.dev/v1/vulns/"
+# OSV accepts up to 1000 queries per batch call; stay comfortably under.
+_BATCH_SIZE = 500
 _OSV_ECOSYSTEM: dict[str, str] = {
     "pypi": "PyPI",
     "npm": "npm",
@@ -85,6 +96,7 @@ def query_vulnerabilities(
     cache_dir: Path | None = None,
     transport: Callable[[str, bytes], bytes] | None = None,
     clock: Callable[[], float] | None = None,
+    progress=None,
 ) -> tuple[list[Vulnerability], LookupSummary]:
     """Look up CVEs for each ``DependencyHint`` and return records.
 
@@ -98,9 +110,15 @@ def query_vulnerabilities(
         supply a per-test tmpdir here.
     transport
         Injectable network transport ``(url, body) -> response_bytes``.
-        Tests pass a stub; default is urllib.
+        Tests pass a stub; default is urllib. Detail lookups pass an
+        empty body (a GET in the default transport).
     clock
         Injectable ``time.time`` for deterministic cache-TTL tests.
+    progress
+        Optional duck-typed progress sink with ``begin(total, label)``
+        and ``advance(current)`` — the CLI passes its ``ScanProgress``
+        so a long lookup renders as a determinate bar, not a stalled
+        spinner.
     """
     cache = _resolve_cache_dir(cache_dir)
     cache.mkdir(parents=True, exist_ok=True)
@@ -111,6 +129,12 @@ def query_vulnerabilities(
     summary = LookupSummary()
     seen_keys: set[tuple[str, str, str, str]] = set()
 
+    # Pass 1 — resolve each hint to a concrete queryable version and dedupe
+    # to unique (ecosystem, name, version) packages. A lockfile monorepo can
+    # carry thousands of hints; querying per unique package (batched below)
+    # instead of per hint is what keeps --cve tractable.
+    entries: list[tuple[DependencyHint, tuple[str, str, str]]] = []
+    unique: dict[tuple[str, str, str], tuple[str, str, str]] = {}  # key -> (osv_eco, name, concrete)
     for dep in dependencies:
         osv_eco = _OSV_ECOSYSTEM.get(dep.ecosystem)
         if osv_eco is None:
@@ -125,21 +149,76 @@ def query_vulnerabilities(
         if concrete is None:
             summary.skipped_no_version += 1
             continue
-
         key = (dep.ecosystem, dep.name, concrete)
-        cache_path = cache / (_cache_key(*key) + ".json")
+        entries.append((dep, key))
+        unique.setdefault(key, (osv_eco, dep.name, concrete))
 
-        payload: dict | None = _read_cache(cache_path, now, ttl_seconds)
+    if progress is not None:
+        progress.begin(len(unique), label="Checking dependencies against OSV.dev")
+
+    # Pass 2 — serve unique packages from the cache where fresh.
+    payload_by_key: dict[tuple[str, str, str], dict] = {}
+    for key in unique:
+        cache_path = cache / (_cache_key(*key) + ".json")
+        payload = _read_cache(cache_path, now, ttl_seconds)
         if payload is not None:
+            payload_by_key[key] = payload
             summary.cached += 1
-        else:
-            payload = _fetch_osv(osv_eco, dep.name, concrete, transport, summary)
+            if progress is not None:
+                progress.advance(key[1])
+
+    # Pass 3 — batch-query the misses (one POST per _BATCH_SIZE packages),
+    # then fetch full advisory records only for the IDs that actually hit,
+    # memoized so a CVE shared by many packages is fetched once.
+    misses = [key for key in unique if key not in payload_by_key]
+    details_memo: dict[str, dict] = {}
+    for start in range(0, len(misses), _BATCH_SIZE):
+        chunk = misses[start : start + _BATCH_SIZE]
+        results = _fetch_osv_batch([unique[key] for key in chunk], transport, summary)
+        if results is None:
+            # Whole batch unreachable — same offline semantics as before,
+            # tallied per package so the summary line stays meaningful.
+            summary.skipped_offline += len(chunk)
+            if progress is not None:
+                for key in chunk:
+                    progress.advance(key[1])
+            continue
+        for key, result in zip(chunk, results):
+            osv_eco, name, concrete = unique[key]
+            payload: dict | None
+            if not isinstance(result, dict):
+                result = {}
+            if result.get("next_page_token"):
+                # A package with >1 page of advisories (rare): fall back to
+                # the classic single query, following ITS pagination too —
+                # exactly these high-advisory packages paginate there as well.
+                payload = _fetch_osv_paged(osv_eco, name, concrete, transport, summary)
+            else:
+                # Assemble the full advisory records for this package. If any
+                # detail fetch fails, the package must NOT be cached — a
+                # partial payload would suppress a known vulnerability for the
+                # whole cache TTL. Treat it as offline for this run instead.
+                payload = _assemble_details(result, details_memo, transport, summary)
             if payload is None:
-                continue  # skipped_offline / network_errors already tallied
-            _write_cache(cache_path, payload, now)
+                summary.skipped_offline += 1
+                if progress is not None:
+                    progress.advance(name)
+                continue
+            payload_by_key[key] = payload
+            _write_cache(cache / (_cache_key(*key) + ".json"), payload, now)
             summary.queried += 1
-            if transport is None:
-                time.sleep(_INTER_REQUEST_SLEEP_S)
+            if progress is not None:
+                progress.advance(name)
+        if transport is None and start + _BATCH_SIZE < len(misses):
+            time.sleep(_INTER_REQUEST_SLEEP_S)
+
+    # Pass 4 — fan the per-package payloads back out to every hint (dedup by
+    # (eco, name, version, id) keeps multi-lockfile repeats from double-emitting).
+    for dep, key in entries:
+        payload = payload_by_key.get(key)
+        if payload is None:
+            continue
+        concrete = key[2]
 
         for entry in payload.get("vulns") or []:
             vuln = _entry_to_vulnerability(entry, dep, concrete)
@@ -404,37 +483,151 @@ def _write_cache(path: Path, payload: dict, now: float) -> None:
         pass
 
 
-def _fetch_osv(
+def _fetch_osv_batch(
+    packages: list[tuple[str, str, str]],
+    transport: Callable[[str, bytes], bytes] | None,
+    summary: LookupSummary,
+) -> list[dict] | None:
+    """One ``POST /v1/querybatch`` for up to ``_BATCH_SIZE`` packages.
+
+    Returns the ``results`` list (aligned with ``packages`` by index — OSV
+    guarantees request order) or ``None`` on a network/shape failure, in
+    which case the whole chunk is treated as offline.
+    """
+    body = json.dumps(
+        {
+            "queries": [
+                {"package": {"name": name, "ecosystem": osv_eco}, "version": version}
+                for osv_eco, name, version in packages
+            ]
+        }
+    ).encode("utf-8")
+    raw = _http(_OSV_BATCH_URL, body, transport, summary)
+    if raw is None:
+        return None
+    try:
+        payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+    except json.JSONDecodeError:
+        summary.network_errors += 1
+        return None
+    results = payload.get("results") if isinstance(payload, dict) else None
+    if not isinstance(results, list) or len(results) != len(packages):
+        summary.network_errors += 1
+        return None
+    return results
+
+
+def _assemble_details(
+    result: dict,
+    details_memo: dict[str, dict],
+    transport: Callable[[str, bytes], bytes] | None,
+    summary: LookupSummary,
+) -> dict | None:
+    """Turn one batch result's ID references into full advisory records.
+
+    Returns ``None`` if any advertised detail could not be fetched — the
+    caller must then skip caching the package, because caching a partial
+    payload would suppress a known vulnerability for the whole TTL (P1).
+    """
+    full_entries = []
+    for ref in result.get("vulns") or []:
+        vuln_id = str(ref.get("id", "")) if isinstance(ref, dict) else ""
+        if not vuln_id:
+            continue  # shape anomaly, not a fetch failure — nothing to fetch
+        entry = details_memo.get(vuln_id)
+        if entry is None:
+            entry = _fetch_osv_vuln(vuln_id, transport, summary)
+            if entry is None:
+                return None
+            details_memo[vuln_id] = entry
+        full_entries.append(entry)
+    return {"vulns": full_entries} if full_entries else {}
+
+
+def _fetch_osv_paged(
     osv_ecosystem: str,
     name: str,
     version: str,
     transport: Callable[[str, bytes], bytes] | None,
     summary: LookupSummary,
 ) -> dict | None:
-    body = json.dumps(
-        {"package": {"name": name, "ecosystem": osv_ecosystem}, "version": version}
-    ).encode("utf-8")
+    """Classic ``POST /v1/query``, following ``next_page_token`` to the end.
+
+    Returns the union of all pages' ``vulns``, or ``None`` if any page fails
+    — never a partial result, for the same don't-cache-partials reason as
+    :func:`_assemble_details` (P2: single-query responses paginate too).
+    """
+    all_vulns: list[dict] = []
+    page_token: str | None = None
+    while True:
+        query: dict = {
+            "package": {"name": name, "ecosystem": osv_ecosystem},
+            "version": version,
+        }
+        if page_token:
+            query["page_token"] = page_token
+        raw = _http(_OSV_QUERY_URL, json.dumps(query).encode("utf-8"), transport, summary)
+        if raw is None:
+            return None
+        try:
+            payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+        except json.JSONDecodeError:
+            summary.network_errors += 1
+            return None
+        if not isinstance(payload, dict):
+            summary.network_errors += 1
+            return None
+        all_vulns.extend(payload.get("vulns") or [])
+        page_token = payload.get("next_page_token")
+        if not page_token:
+            break
+        if transport is None:
+            time.sleep(_INTER_REQUEST_SLEEP_S)
+    return {"vulns": all_vulns} if all_vulns else {}
+
+
+def _fetch_osv_vuln(
+    vuln_id: str,
+    transport: Callable[[str, bytes], bytes] | None,
+    summary: LookupSummary,
+) -> dict | None:
+    """Fetch one full advisory record via ``GET /v1/vulns/{id}``."""
+    raw = _http(_OSV_VULNS_URL + vuln_id, b"", transport, summary)
+    if raw is None:
+        return None
     try:
-        if transport is not None:
-            raw = transport(_OSV_QUERY_URL, body)
-        else:
-            request = urllib.request.Request(
-                _OSV_QUERY_URL,
-                data=body,
-                headers={"Content-Type": "application/json"},
-                method="POST",
-            )
-            with urllib.request.urlopen(request, timeout=_REQUEST_TIMEOUT_S) as response:
-                raw = response.read()
-    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        entry = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+    except json.JSONDecodeError:
         summary.network_errors += 1
-        summary.skipped_offline += 1
-        logger.debug("OSV network error for %s/%s@%s: %s", osv_ecosystem, name, version, exc)
         return None
+    return entry if isinstance(entry, dict) else None
+
+
+def _http(
+    url: str,
+    body: bytes,
+    transport: Callable[[str, bytes], bytes] | None,
+    summary: LookupSummary,
+) -> bytes | None:
+    """One HTTP exchange: POST when ``body`` is non-empty, GET otherwise.
+
+    The injectable ``transport`` sees ``(url, body)`` either way, so test
+    stubs dispatch on the URL.
+    """
     try:
-        return json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
-    except json.JSONDecodeError:
+        if transport is not None:
+            return transport(url, body)
+        request = urllib.request.Request(
+            url,
+            data=body or None,
+            headers={"Content-Type": "application/json"} if body else {},
+            method="POST" if body else "GET",
+        )
+        with urllib.request.urlopen(request, timeout=_REQUEST_TIMEOUT_S) as response:
+            return response.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
         summary.network_errors += 1
+        logger.debug("OSV network error for %s: %s", url, exc)
         return None
 
 

{attackmap-0.4.26 → attackmap-0.4.27/src/attackmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.4.26
+Version: 0.4.27
 Summary: AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints.
 Author: AttackMap Contributors
 Author-email: Matthew Davis <matthewd@matthewd.xyz>

{attackmap-0.4.26 → attackmap-0.4.27}/tests/test_cve.py

@@ -129,21 +129,49 @@ def _osv_vuln(
 
 
 def _stub_transport(responses_by_body_hint: dict[str, dict]):
-    """Return a transport that maps request bodies to canned responses.
+    """Return a transport speaking the OSV batch + detail protocol.
 
-    ``responses_by_body_hint`` keys are substrings we expect in the JSON
-    request body (usually the package name); values are the JSON dict
-    to return.
+    ``responses_by_body_hint`` keys are substrings matched against the
+    queried package name; values are classic ``/v1/query``-shaped dicts
+    (``{"vulns": [full entries]}``). The stub answers:
+
+    - ``POST /v1/querybatch`` → per-query ID references derived from the
+      matched canned payload,
+    - ``GET /v1/vulns/{id}`` → the full canned entry for that ID,
+    - ``POST /v1/query`` (pagination fallback) → the canned payload as-is.
     """
     calls: list[tuple[str, bytes]] = []
 
+    def _match(text: str) -> dict | None:
+        for hint, payload in responses_by_body_hint.items():
+            if hint in text:
+                return payload
+        return None
+
     def transport(url: str, body: bytes) -> bytes:
         calls.append((url, body))
-        body_text = body.decode("utf-8")
-        for hint, payload in responses_by_body_hint.items():
-            if hint in body_text:
-                return json.dumps(payload).encode("utf-8")
-        return json.dumps({"vulns": []}).encode("utf-8")
+        if url.endswith("/v1/querybatch"):
+            request = json.loads(body.decode("utf-8"))
+            results = []
+            for query in request["queries"]:
+                payload = _match(query["package"]["name"])
+                if payload and payload.get("vulns"):
+                    results.append(
+                        {"vulns": [{"id": v["id"], "modified": ""} for v in payload["vulns"]]}
+                    )
+                else:
+                    results.append({})
+            return json.dumps({"results": results}).encode("utf-8")
+        if "/v1/vulns/" in url:
+            vuln_id = url.rsplit("/", 1)[1]
+            for payload in responses_by_body_hint.values():
+                for entry in payload.get("vulns", []):
+                    if entry["id"] == vuln_id:
+                        return json.dumps(entry).encode("utf-8")
+            return json.dumps({}).encode("utf-8")
+        # Classic single query (the pagination fallback path).
+        payload = _match(body.decode("utf-8"))
+        return json.dumps(payload if payload else {"vulns": []}).encode("utf-8")
 
     return transport, calls
 
@@ -165,14 +193,14 @@ def test_query_returns_vulnerabilities_from_stubbed_response(tmp_path: Path) ->
 
 
 def test_query_dedups_repeated_vulns_across_deps(tmp_path: Path) -> None:
-    """Two DependencyHints for the same (eco, name, version) share the
-    same underlying OSV response — we only surface one Vulnerability."""
+    """Two DependencyHints for the same (eco, name, version) dedupe to one
+    unique package — queried once, surfaced once."""
     transport, calls = _stub_transport({"sample-pkg": {"vulns": [_osv_vuln()]}})
     deps = [_dep(), _dep()]  # same fingerprint twice
     vulns, summary = query_vulnerabilities(deps, cache_dir=tmp_path, transport=transport)
     assert len(vulns) == 1
-    # The second call hits the cache we just wrote.
-    assert summary.cached == 1
+    assert summary.queried == 1
+    assert summary.cached == 0
 
 
 def test_query_skips_deps_without_queryable_version(tmp_path: Path) -> None:
@@ -192,8 +220,9 @@ def test_query_uses_cache_on_second_call(tmp_path: Path) -> None:
     transport, calls = _stub_transport({"sample-pkg": {"vulns": [_osv_vuln()]}})
     dep = _dep()
     vulns1, s1 = query_vulnerabilities([dep], cache_dir=tmp_path, transport=transport)
+    first_run_calls = len(calls)  # one batch POST + one detail GET
     vulns2, s2 = query_vulnerabilities([dep], cache_dir=tmp_path, transport=transport)
-    assert len(calls) == 1  # transport called once, second run hit cache
+    assert len(calls) == first_run_calls  # second run hit the cache — no network
     assert s1.queried == 1 and s2.cached == 1
     # Vulns from the cached run should mirror the network run.
     assert [v.id for v in vulns2] == [v.id for v in vulns1]
@@ -204,12 +233,14 @@ def test_query_ignores_stale_cache_beyond_ttl(tmp_path: Path, monkeypatch: pytes
     dep = _dep()
     # First call at t=0.
     query_vulnerabilities([dep], cache_dir=tmp_path, transport=transport, clock=lambda: 0.0)
-    assert len(calls) == 1
-    # Second call 25 hours later with default 24h TTL — cache invalidated.
+    first_run_calls = len(calls)
+    assert first_run_calls > 0
+    # Second call 25 hours later with default 24h TTL — cache invalidated,
+    # so the network is hit again.
     monkeypatch.setenv("ATTACKMAP_OSV_CACHE_TTL_HOURS", "24")
     later = 25 * 3600.0
     query_vulnerabilities([dep], cache_dir=tmp_path, transport=transport, clock=lambda: later)
-    assert len(calls) == 2
+    assert len(calls) > first_run_calls
 
 
 def test_query_offline_transport_error_falls_back_gracefully(tmp_path: Path) -> None:
@@ -259,6 +290,146 @@ def test_query_extracts_affected_range_text(tmp_path: Path) -> None:
     assert vulns[0].affected_range == "affected: >= 0, fixed in 1.2.3"
 
 
+def test_query_batches_many_packages_into_few_requests(tmp_path: Path) -> None:
+    """The whole point of querybatch (#cve-batch): a big lockfile tree must
+    not produce one HTTP request per package. 700 unique clean packages →
+    2 batch POSTs (500 + 200) and zero detail fetches."""
+    from attackmap.cve import _BATCH_SIZE, _OSV_BATCH_URL
+
+    transport, calls = _stub_transport({})
+    deps = [_dep(name=f"pkg-{i}") for i in range(_BATCH_SIZE + 200)]
+    vulns, summary = query_vulnerabilities(deps, cache_dir=tmp_path, transport=transport)
+    assert vulns == []
+    assert summary.queried == _BATCH_SIZE + 200
+    batch_calls = [c for c in calls if c[0] == _OSV_BATCH_URL]
+    assert len(batch_calls) == 2
+    assert len(calls) == 2  # no detail fetches for clean packages
+
+
+def test_query_fetches_shared_vuln_details_once(tmp_path: Path) -> None:
+    """Two packages hit by the same advisory ID → one /v1/vulns/{id} fetch
+    (memoized per run), both packages still emit their Vulnerability."""
+    from attackmap.cve import _OSV_VULNS_URL
+
+    shared = _osv_vuln("GHSA-shared-1")
+    transport, calls = _stub_transport({"pkg-a": {"vulns": [shared]}, "pkg-b": {"vulns": [shared]}})
+    deps = [_dep(name="pkg-a"), _dep(name="pkg-b")]
+    vulns, summary = query_vulnerabilities(deps, cache_dir=tmp_path, transport=transport)
+    assert summary.queried == 2
+    assert {v.package_name for v in vulns} == {"pkg-a", "pkg-b"}
+    detail_calls = [c for c in calls if c[0].startswith(_OSV_VULNS_URL)]
+    assert len(detail_calls) == 1
+
+
+def test_query_failed_detail_fetch_is_not_cached(tmp_path: Path) -> None:
+    """Codex P1: if the batch names an advisory but its /v1/vulns/{id} fetch
+    fails, the package must NOT be cached — a cached partial/empty payload
+    would suppress a known vulnerability for the whole TTL. The next run
+    (connectivity restored) must query again and surface the vuln."""
+    from attackmap.cve import _OSV_VULNS_URL
+
+    good_transport, _ = _stub_transport({"sample-pkg": {"vulns": [_osv_vuln()]}})
+
+    def flaky_transport(url: str, body: bytes) -> bytes:
+        if url.startswith(_OSV_VULNS_URL):
+            raise OSError("transient network error")
+        return good_transport(url, body)
+
+    vulns1, s1 = query_vulnerabilities([_dep()], cache_dir=tmp_path, transport=flaky_transport)
+    assert vulns1 == []
+    assert s1.queried == 0
+    assert s1.skipped_offline == 1
+
+    # Connectivity restored: no stale cache entry may mask the advisory.
+    vulns2, s2 = query_vulnerabilities([_dep()], cache_dir=tmp_path, transport=good_transport)
+    assert [v.id for v in vulns2] == ["GHSA-test-1234"]
+    assert s2.queried == 1
+    assert s2.cached == 0
+
+
+def test_query_fallback_follows_single_query_pagination(tmp_path: Path) -> None:
+    """Codex P2: the single-query fallback must follow /v1/query's OWN
+    next_page_token — the high-advisory packages that enter this branch
+    paginate there too. All pages' vulns are merged; nothing is dropped."""
+    from attackmap.cve import _OSV_BATCH_URL, _OSV_QUERY_URL
+
+    page1 = {"vulns": [_osv_vuln("GHSA-page1-1")], "next_page_token": "page2"}
+    page2 = {"vulns": [_osv_vuln("GHSA-page2-1")]}
+
+    def transport(url: str, body: bytes) -> bytes:
+        if url == _OSV_BATCH_URL:
+            return json.dumps(
+                {"results": [{"vulns": [{"id": "GHSA-page1-1", "modified": ""}], "next_page_token": "tok"}]}
+            ).encode("utf-8")
+        if url == _OSV_QUERY_URL:
+            request = json.loads(body.decode("utf-8"))
+            return json.dumps(page2 if request.get("page_token") == "page2" else page1).encode("utf-8")
+        raise AssertionError(f"unexpected URL {url}")
+
+    vulns, summary = query_vulnerabilities([_dep()], cache_dir=tmp_path, transport=transport)
+    assert sorted(v.id for v in vulns) == ["GHSA-page1-1", "GHSA-page2-1"]
+    assert summary.queried == 1
+
+    # And the complete (both-pages) payload is what got cached.
+    vulns_cached, s2 = query_vulnerabilities(
+        [_dep()], cache_dir=tmp_path, transport=transport
+    )
+    assert sorted(v.id for v in vulns_cached) == ["GHSA-page1-1", "GHSA-page2-1"]
+    assert s2.cached == 1
+
+
+def test_query_paginated_batch_result_falls_back_to_single_query(tmp_path: Path) -> None:
+    """A batch result carrying next_page_token (rare: >1 page of advisories
+    for one package) falls back to the classic full /v1/query for it."""
+    from attackmap.cve import _OSV_BATCH_URL, _OSV_QUERY_URL
+
+    calls: list[tuple[str, bytes]] = []
+    full_payload = {"vulns": [_osv_vuln("GHSA-paged-1")]}
+
+    def transport(url: str, body: bytes) -> bytes:
+        calls.append((url, body))
+        if url == _OSV_BATCH_URL:
+            return json.dumps(
+                {"results": [{"vulns": [{"id": "GHSA-paged-1", "modified": ""}], "next_page_token": "tok"}]}
+            ).encode("utf-8")
+        if url == _OSV_QUERY_URL:
+            return json.dumps(full_payload).encode("utf-8")
+        raise AssertionError(f"unexpected URL {url}")
+
+    vulns, summary = query_vulnerabilities([_dep()], cache_dir=tmp_path, transport=transport)
+    assert [v.id for v in vulns] == ["GHSA-paged-1"]
+    assert any(c[0] == _OSV_QUERY_URL for c in calls)
+
+
+def test_query_reports_determinate_progress(tmp_path: Path) -> None:
+    """The progress sink sees begin(total=unique packages) and one advance
+    per package — cache hits and network results alike."""
+
+    class _FakeProgress:
+        def __init__(self) -> None:
+            self.begun: tuple[int, str] | None = None
+            self.advanced: list[str] = []
+
+        def begin(self, total: int, label: str = "") -> None:
+            self.begun = (total, label)
+
+        def advance(self, current: str = "") -> None:
+            self.advanced.append(current)
+
+    transport, _ = _stub_transport({"pkg-a": {"vulns": [_osv_vuln()]}})
+    deps = [_dep(name="pkg-a"), _dep(name="pkg-b"), _dep(name="pkg-b")]  # 2 unique
+    sink = _FakeProgress()
+    query_vulnerabilities(deps, cache_dir=tmp_path, transport=transport, progress=sink)
+    assert sink.begun is not None and sink.begun[0] == 2
+    assert len(sink.advanced) == 2
+
+    # A warm-cache rerun advances through every package instantly.
+    sink2 = _FakeProgress()
+    query_vulnerabilities(deps, cache_dir=tmp_path, transport=transport, progress=sink2)
+    assert sink2.begun is not None and sink2.begun[0] == 2
+    assert len(sink2.advanced) == 2
+
+
 # ---------------------------------------------------------------------------
 # Finding emission via threat_model.generate_findings
 # ---------------------------------------------------------------------------