limbowatch 0.1.0a1__tar.gz

limbowatch-0.1.0a1/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+*.db
+*.sqlite
+.env
+.DS_Store
+
+# research caches (raw API responses, cloned lockfiles)
+research/**/.cache/
+# research intermediates: contain advisory text and author/credit data; never commit
+research/**/data/**/*.json
+!research/**/data/**/summary.json
+!research/**/data/**/followup-*.json
+
+# tracker runtime output (state lives on the tracker-data branch; site is built in CI)
+tracker/state/
+tracker/site/
+
+# Site build output (written by CI before docker build)
+deploy/site/public/

limbowatch-0.1.0a1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: limbowatch
+Version: 0.1.0a1
+Summary: Track published security advisories stuck in limbo (not yet reviewed into the databases scanners read)
+Project-URL: Homepage, https://limbo.watch
+Project-URL: Source, https://github.com/limbowatch/limbowatch
+Project-URL: Documentation, https://github.com/limbowatch/limbowatch/blob/main/docs/WATCHER.md
+Project-URL: Issues, https://github.com/limbowatch/limbowatch/issues
+Project-URL: Changelog, https://github.com/limbowatch/limbowatch/blob/main/CHANGELOG.md
+Project-URL: Tracker, https://limbo.watch/tracker/
+Author: Limbowatch contributors
+License-Expression: Apache-2.0
+Keywords: advisories,cyclonedx,dependencies,ghsa,osv,sarif,sca,security,supply-chain,vulnerabilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.8
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: univers>=30
+Description-Content-Type: text/markdown
+
+# limbowatch
+
+The library behind [Limbowatch](https://limbo.watch): it tracks security advisories **in limbo**, meaning published by maintainers on GitHub but not yet in GitHub's reviewed Advisory Database or OSV, so scanners that read those databases don't report them.
+
+Most people want the command line instead: `pip install limbowatch-cli`. See the [watcher guide](https://github.com/limbowatch/limbowatch/blob/main/docs/WATCHER.md).
+
+Advisory data: GitHub repository security advisories and the GitHub Advisory Database (CC BY 4.0), via the limbo feed (CC BY 4.0). Code: Apache-2.0.

limbowatch-0.1.0a1/README.md

@@ -0,0 +1,7 @@
+# limbowatch
+
+The library behind [Limbowatch](https://limbo.watch): it tracks security advisories **in limbo**, meaning published by maintainers on GitHub but not yet in GitHub's reviewed Advisory Database or OSV, so scanners that read those databases don't report them.
+
+Most people want the command line instead: `pip install limbowatch-cli`. See the [watcher guide](https://github.com/limbowatch/limbowatch/blob/main/docs/WATCHER.md).
+
+Advisory data: GitHub repository security advisories and the GitHub Advisory Database (CC BY 4.0), via the limbo feed (CC BY 4.0). Code: Apache-2.0.

limbowatch-0.1.0a1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "limbowatch"
+version = "0.1.0a1"
+description = "Track published security advisories stuck in limbo (not yet reviewed into the databases scanners read)"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+readme = "README.md"
+authors = [{ name = "Limbowatch contributors" }]
+keywords = ["security", "advisories", "vulnerabilities", "ghsa", "osv", "sca", "dependencies", "supply-chain", "sarif", "cyclonedx"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.8",
+    "sqlalchemy>=2.0",
+    "univers>=30",
+]
+
+[project.urls]
+Homepage = "https://limbo.watch"
+Source = "https://github.com/limbowatch/limbowatch"
+Documentation = "https://github.com/limbowatch/limbowatch/blob/main/docs/WATCHER.md"
+Issues = "https://github.com/limbowatch/limbowatch/issues"
+Changelog = "https://github.com/limbowatch/limbowatch/blob/main/CHANGELOG.md"
+Tracker = "https://limbo.watch/tracker/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/limbowatch"]

limbowatch-0.1.0a1/src/limbowatch/__init__.py

@@ -0,0 +1,3 @@
+"""Limbowatch: track published security advisories stuck in limbo."""
+
+__version__ = "0.1.0a1"

limbowatch-0.1.0a1/src/limbowatch/classify.py

@@ -0,0 +1,77 @@
+"""Classify an advisory from its facts. Pure: no I/O.
+
+Facts are independent (repo advisory, review, OSV, CVE, NVD) and change in any order, so the
+status is recomputed from scratch every time (PHASE0_PLAN §3).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+
+from limbowatch.ecosystems import reviewable
+from limbowatch.models import GITHUB_CNA, Assessment, CveLabel, Facts, RepoAdvisory, Status
+
+
+def status(f: Facts) -> Status:
+    if f.reviewed or f.in_osv:
+        return Status.REVIEWED
+    if f.repo_state == "withdrawn":
+        return Status.WITHDRAWN
+    if f.repo_state != "published":
+        return Status.NOT_PUBLISHED
+    if f.duplicate_of:
+        return Status.DUPLICATE
+    return Status.LIMBO
+
+
+def cve_label(f: Facts) -> CveLabel:
+    if f.cited_cve:
+        if f.cited_cve_state == "PUBLISHED":
+            return CveLabel.PUBLISHED_CITED
+        if f.cited_cve_state == "RESERVED":
+            return CveLabel.RESERVED
+        return CveLabel.OTHER
+    if f.uncited_cves:
+        return CveLabel.PUBLISHED_UNCITED
+    return CveLabel.NONE
+
+
+def assess(adv: RepoAdvisory, f: Facts) -> Assessment:
+    ecos = tuple(sorted({p.ecosystem for p in adv.packages} or {"other"}))
+    return Assessment(
+        ghsa_id=adv.ghsa_id,
+        status=status(f),
+        cve_label=cve_label(f),
+        likely_permanent=not any(reviewable(e) for e in ecos),
+        ecosystems=ecos,
+    )
+
+
+def facts_hash(f: Facts) -> str:
+    return hashlib.sha256(json.dumps(f.model_dump(mode="json"), sort_keys=True).encode()).hexdigest()
+
+
+def transitions(old: Facts | None, new: Facts, cnas: Mapping[str, str | None] | None = None) -> list[str]:
+    """Human-readable events between two fact snapshots (empty if nothing meaningful changed).
+
+    `cnas` maps uncited CVE IDs to their CNA, so GitHub's own CVEs aren't called another CNA's (F-067)."""
+    if old is None:
+        return ["first seen"]
+    ev = []
+    if status(old) != status(new):
+        ev.append(f"{status(old).value} -> {status(new).value}")
+    if old.cited_cve != new.cited_cve:
+        ev.append(f"cites {new.cited_cve or 'no CVE'} (was {old.cited_cve or 'none'})")
+    elif old.cited_cve_state != new.cited_cve_state and new.cited_cve:
+        ev.append(f"{new.cited_cve} {old.cited_cve_state or '?'} -> {new.cited_cve_state}")
+    added = sorted(set(new.uncited_cves) - set(old.uncited_cves))
+    github = [c for c in added if (cnas or {}).get(c) == GITHUB_CNA]
+    if github:
+        ev.append(f"new CVE from GitHub's CNA, not cited: {', '.join(github)}")
+    if other := [c for c in added if c not in github]:
+        ev.append(f"new CVE from another CNA: {', '.join(other)}")
+    if not old.duplicate_of and new.duplicate_of:
+        ev.append(f"duplicate of reviewed {', '.join(new.duplicate_of)}")
+    return ev

limbowatch-0.1.0a1/src/limbowatch/csvsafe.py

@@ -0,0 +1,18 @@
+"""Spreadsheet-safe CSV cells. Pure.
+
+Spreadsheets treat a cell starting with = + - @ as a formula. Advisory fields are typed by maintainers, so a
+cell starting with = gets a leading ', and so does one starting with + - @ that could call anything (a function,
+a link, DDE). npm scopes like `@scope/pkg; other` and numbers like -1 stay as entered.
+"""
+
+from __future__ import annotations
+
+import re
+
+_CALLS = re.compile(r"[()|!\"'&\[\]{}$\t\r\n]")  # what a formula needs to call a function, a link or DDE
+
+
+def cell(v: str) -> str:
+    if v[:1] in ("=", "\t", "\r") or (v[:1] in ("+", "-", "@") and _CALLS.search(v)):
+        return f"'{v}"
+    return v

limbowatch-0.1.0a1/src/limbowatch/ecosystems.py

@@ -0,0 +1,123 @@
+"""Ecosystem registry: GHSA ecosystem name -> OSV ecosystem, purl type, review support.
+
+Adding an ecosystem means adding one entry here (and, for version evaluation, a comparator in
+versions.py). Everything else looks ecosystems up through `info()`.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EcosystemInfo:
+    ghsa: str  # GHSA / GitHub Advisory Database ecosystem name
+    osv: str | None  # OSV ecosystem name (None: OSV has no equivalent)
+    purl_type: str | None
+    reviewable: bool  # GitHub reviews advisories for this ecosystem (FINDINGS F-015, F-023)
+    name_rule: str = r".+"  # what a well-formed package name looks like, after cleaning
+    name_style: str = ""  # "pep503" / "lower": the canonical spelling scanners compare; "url": a path, not a URL
+    depsdev: str | None = None  # deps.dev system, for mapping a package to its source repo
+
+
+_REGISTRY: dict[str, EcosystemInfo] = {
+    e.ghsa: e
+    for e in (
+        # Name rules follow each registry's documented naming (FINDINGS F-069)
+        EcosystemInfo("npm", "npm", "npm", True, r"(?:@[A-Za-z0-9~-][\w.~-]*/)?[A-Za-z0-9~-][\w.~-]*", depsdev="npm"),
+        EcosystemInfo("pip", "PyPI", "pypi", True, r"[a-z0-9]+(?:-[a-z0-9]+)*", "pep503", depsdev="pypi"),
+        EcosystemInfo(
+            "go", "Go", "golang", True, r"stdlib|toolchain|[a-z0-9.-]+\.[a-z]{2,}(?:/[\w.~+-]+)*", "url", depsdev="go"
+        ),
+        EcosystemInfo("rust", "crates.io", "cargo", True, r"[A-Za-z0-9_-]+", depsdev="cargo"),
+        EcosystemInfo("maven", "Maven", "maven", True, r"[\w.-]+:[\w.-]+", depsdev="maven"),
+        EcosystemInfo("nuget", "NuGet", "nuget", True, r"[\w.-]+", depsdev="nuget"),
+        EcosystemInfo(
+            "composer",
+            "Packagist",
+            "composer",
+            True,
+            r"[a-z0-9]([_.-]?[a-z0-9]+)*/[a-z0-9](([_.]|-{1,2})?[a-z0-9]+)*",
+            "lower",
+        ),
+        EcosystemInfo("rubygems", "RubyGems", "gem", True, r"[\w.-]+", depsdev="rubygems"),
+        EcosystemInfo("erlang", "Hex", "hex", True, r"[a-z][a-z0-9_]*"),
+        EcosystemInfo("actions", "GitHub Actions", "githubactions", True, r"[\w.-]+/[\w.-]+(?:/[\w./-]+)?", "url"),
+        EcosystemInfo("pub", "Pub", "pub", True, r"[a-z_][a-z0-9_]*"),
+        EcosystemInfo("swift", "SwiftURL", "swift", True, r"[a-z0-9.-]+\.[a-z]{2,}(?:/[\w.-]+){2,}", "url"),
+    )
+}
+
+
+def info(ghsa_ecosystem: str | None) -> EcosystemInfo:
+    """Registry entry; unknown, empty or free-text ecosystems are not reviewable."""
+    key = (ghsa_ecosystem or "").strip().lower()
+    return _REGISTRY.get(key) or EcosystemInfo(key or "other", None, None, False)
+
+
+def reviewable(ghsa_ecosystem: str | None) -> bool:
+    return info(ghsa_ecosystem).reviewable
+
+
+_BY_OSV = {e.osv: e for e in _REGISTRY.values() if e.osv}
+_BY_PURL = {e.purl_type: e for e in _REGISTRY.values() if e.purl_type}
+
+
+def by_osv(osv_ecosystem: str) -> EcosystemInfo | None:
+    """Registry entry for an OSV ecosystem name such as "PyPI" or "crates.io" (or "Debian:12")."""
+    return _BY_OSV.get(osv_ecosystem.split(":", 1)[0])
+
+
+def by_purl_type(purl_type: str) -> EcosystemInfo | None:
+    return _BY_PURL.get(purl_type.lower())
+
+
+# OSV's ecosystem list (https://osv-vulnerabilities.storage.googleapis.com/ecosystems.txt, 2026-10-31).
+# OSV-Scanner's offline mode fails the whole scan when an ecosystem it needs has no zip, so the feed
+# serves one for each, and the watcher's inventory step uses an empty one for each (F-074, F-078).
+OSV_ECOSYSTEMS = (
+    "AlmaLinux", "Alpaquita", "Alpine", "Android", "Azure Linux", "BellSoft Hardened Containers", "Bitnami", "CRAN",
+    "Chainguard", "CleanStart", "Debian", "Echo", "GHC", "GIT", "GSD", "GitHub Actions", "Go", "Hackage", "Hex",
+    "Julia", "Linux", "Mageia", "Maven", "MinimOS", "NuGet", "OSS-Fuzz", "Packagist", "Pub", "PyPI", "Red Hat",
+    "Red Hat Lightwell", "Rocky Linux", "Root", "RubyGems", "SUSE", "SwiftURL", "TuxCare", "UVI", "Ubuntu", "VSCode",
+    "Wolfi", "crates.io", "npm", "opam", "openEuler", "openSUSE",
+)  # fmt: skip
+
+
+@dataclass(frozen=True)
+class PackageName:
+    name: str  # the name to publish and match on
+    raw: str  # as the maintainer entered it
+    valid: bool  # well-formed for its ecosystem; an invalid name can't match any real package
+
+    @property
+    def cleaned(self) -> bool:
+        return self.name != self.raw
+
+
+_MD_LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)")
+
+
+def package_name(ghsa_ecosystem: str | None, raw: str | None) -> PackageName | None:
+    """A maintainer-entered package name, cleaned only where the result is certain (FINDINGS F-069).
+
+    Scanners compare names exactly (PyPI and Composer after canonicalizing their own side), so a
+    stray space, a URL or the wrong case means the advisory silently never matches. Names that still
+    don't fit the ecosystem's naming rule are flagged, never guessed at.
+    """
+    if raw is None or not raw.strip():
+        return None
+    e = info(ghsa_ecosystem)
+    s = _MD_LINK.sub(r"\1", raw).strip().strip("`'\"").strip()
+    if e.name_style == "url":
+        s = re.sub(r"^(?:git\+)?https?://", "", s).removesuffix("/").removesuffix(".git")
+        if e.ghsa == "actions":
+            s = s.removeprefix("github.com/")
+    elif e.name_style == "pep503":
+        if m := re.search(r"#egg=([\w.-]+)", s):
+            s = m.group(1)
+        s = re.sub(r"[-_.]+", "-", s).lower()
+    elif e.name_style == "lower":
+        s = s.lower()
+    return PackageName(s, raw, re.fullmatch(e.name_rule, s) is not None)

limbowatch-0.1.0a1/src/limbowatch/http.py

@@ -0,0 +1,229 @@
+"""The only module that builds HTTP requests.
+
+- Per-host concurrency limits, retries with exponential backoff, Retry-After.
+- GitHub primary and secondary rate limits; a request budget for the run (304s are free and
+  don't count, FINDINGS F-058).
+- Conditional requests: ETags are only valid for the token that obtained them (the response
+  varies by Authorization), so the client exposes a token fingerprint to store alongside them.
+- The token is never logged, printed or returned.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from limbowatch import __version__
+
+log = logging.getLogger(__name__)
+USER_AGENT = f"limbowatch/{__version__} (+https://limbo.watch)"
+GITHUB_API = "api.github.com"
+HOST_CONCURRENCY = {
+    GITHUB_API: 8,
+    "api.osv.dev": 16,
+    "cveawg.mitre.org": 16,
+    "services.nvd.nist.gov": 1,
+    "raw.githubusercontent.com": 8,
+    "api.deps.dev": 16,
+    "rubygems.org": 4,  # its API asks for at most about 10 requests a second
+}
+
+
+class BudgetExhausted(Exception):
+    """The run's GitHub request budget (or the primary rate limit) is used up."""
+
+
+class DeadlineReached(Exception):
+    """The run's wall-clock deadline has passed."""
+
+
+@dataclass
+class Response:
+    status: int
+    body: Any
+    etag: str | None = None
+    link: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status == 200
+
+
+@dataclass
+class Stats:
+    requests: dict[str, int] = field(default_factory=dict)
+    github_counted: int = 0
+    github_not_modified: int = 0
+    failures: int = 0
+
+
+class HttpClient:
+    def __init__(
+        self,
+        github_token: str | None = None,
+        *,
+        github_budget: int | None = None,
+        deadline: float | None = None,
+        nvd_api_key: str | None = None,
+        max_rate_limit_wait: float = 900.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Any = asyncio.sleep,
+    ) -> None:
+        self._token = github_token
+        self.token_fingerprint = hashlib.sha256(github_token.encode()).hexdigest()[:16] if github_token else "anonymous"
+        self.github_budget = github_budget
+        self.deadline = deadline
+        self._nvd_key = nvd_api_key
+        self._nvd_spacing = 0.7 if nvd_api_key else 6.5
+        self._nvd_last = 0.0
+        self._max_wait = max_rate_limit_wait
+        self._sleep = sleep
+        self._sems = {h: asyncio.Semaphore(n) for h, n in HOST_CONCURRENCY.items()}
+        self._default_sem = asyncio.Semaphore(8)
+        self._nvd_lock = asyncio.Lock()
+        self.stats = Stats()
+        self._client = httpx.AsyncClient(
+            timeout=60, follow_redirects=True, headers={"User-Agent": USER_AGENT}, transport=transport
+        )
+
+    async def __aenter__(self) -> HttpClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self._client.aclose()
+
+    def budget_left(self) -> int | None:
+        return None if self.github_budget is None else self.github_budget - self.stats.github_counted
+
+    def _check_deadline(self) -> None:
+        if self.deadline is not None and time.monotonic() > self.deadline:
+            raise DeadlineReached
+
+    async def get(self, url: str, *, etag: str | None = None, json_body: Any = None, raw: bool = False) -> Response:
+        """GET (or POST with `json_body`). Returns status 304 with no body when `etag` still matches.
+
+        With `raw`, the body is the response bytes (e.g. a zip), and `etag` is sent to any host.
+        """
+        self._check_deadline()
+        host = urlsplit(url).hostname or ""
+        is_gh = host == GITHUB_API
+        if is_gh and (left := self.budget_left()) is not None and left <= 0:
+            raise BudgetExhausted
+        headers: dict[str, str] = {}
+        if is_gh:
+            headers.update({"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28"})
+            if self._token:
+                headers["Authorization"] = f"Bearer {self._token}"
+            if etag:
+                headers["If-None-Match"] = etag
+        elif raw and etag:
+            headers["If-None-Match"] = etag
+        if host == "services.nvd.nist.gov":
+            if self._nvd_key:
+                headers["apiKey"] = self._nvd_key
+            async with self._nvd_lock:  # NVD: one request per spacing interval
+                wait = self._nvd_last + self._nvd_spacing - time.monotonic()
+                if wait > 0:
+                    await self._sleep(wait)
+                self._nvd_last = time.monotonic()
+        sem = self._sems.get(host, self._default_sem)
+        async with sem:
+            r = await self._send(url, headers, json_body, is_gh)
+        self.stats.requests[host] = self.stats.requests.get(host, 0) + 1
+        if r is None:
+            self.stats.failures += 1
+            return Response(-1, None)
+        if is_gh:
+            if r.status_code == 304:
+                self.stats.github_not_modified += 1
+            else:
+                self.stats.github_counted += 1
+        if r.status_code == 304:
+            return Response(304, None, etag=etag)
+        if raw:
+            return Response(r.status_code, r.content, etag=r.headers.get("etag"), link=r.headers.get("link"))
+        try:
+            body: Any = r.json()
+        except ValueError:
+            body = r.text
+        return Response(r.status_code, body, etag=r.headers.get("etag"), link=r.headers.get("link"))
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        auth: tuple[str, str],
+        json_body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Response:
+        """A request to an issue tracker (GitLab, Gitea): any method, a caller-supplied auth header.
+
+        The header value is a token; it's sent only to `url`'s host and never logged.
+        """
+        self._check_deadline()
+        host = urlsplit(url).hostname or ""
+        r: httpx.Response | None = None
+        async with self._sems.get(host, self._default_sem):
+            for attempt in range(5):
+                try:
+                    r = await self._client.request(method, url, headers={auth[0]: auth[1]}, json=json_body,
+                                                   params=params)  # fmt: skip
+                except httpx.HTTPError as e:
+                    log.warning("http error", extra={"host": host, "error": type(e).__name__, "attempt": attempt})
+                    await self._sleep(min(30, 2**attempt))
+                    continue
+                if r.status_code in (429, 502, 503, 504):
+                    await self._sleep(min(60, int(r.headers.get("retry-after", 2 ** (attempt + 1)))))
+                    continue
+                break
+        self.stats.requests[host] = self.stats.requests.get(host, 0) + 1
+        if r is None:
+            self.stats.failures += 1
+            return Response(-1, None)
+        try:
+            body: Any = r.json()
+        except ValueError:
+            body = r.text
+        return Response(r.status_code, body, etag=r.headers.get("etag"), link=r.headers.get("link"))
+
+    async def _send(self, url: str, headers: dict[str, str], json_body: Any, is_gh: bool) -> httpx.Response | None:
+        for attempt in range(6):
+            self._check_deadline()
+            try:
+                if json_body is None:
+                    r = await self._client.get(url, headers=headers)
+                else:
+                    r = await self._client.post(url, headers=headers, json=json_body)
+            except httpx.HTTPError as e:
+                log.warning("http error", extra={"url": url, "error": type(e).__name__, "attempt": attempt})
+                await self._sleep(min(60, 2**attempt))
+                continue
+            if is_gh and r.status_code in (403, 429):
+                if r.headers.get("x-ratelimit-remaining") == "0":
+                    await self._wait_for_reset(r)
+                    continue
+                if "retry-after" in r.headers or "secondary rate limit" in r.text.lower():
+                    await self._sleep(int(r.headers.get("retry-after", 60)) + 1)
+                    continue
+            if r.status_code in (429, 500, 502, 503, 504):
+                await self._sleep(min(60, int(r.headers.get("retry-after", 2 ** (attempt + 1)))))
+                continue
+            if is_gh and int(r.headers.get("x-ratelimit-remaining", "1000")) < 20:
+                await self._wait_for_reset(r)
+            return r
+        return None
+
+    async def _wait_for_reset(self, r: httpx.Response) -> None:
+        wait = max(5.0, float(r.headers.get("x-ratelimit-reset", time.time() + 60)) - time.time() + 5)
+        if wait > self._max_wait:
+            raise BudgetExhausted
+        log.info("github rate limit low; waiting", extra={"seconds": round(wait)})
+        await self._sleep(wait)

limbowatch-0.1.0a1/src/limbowatch/inventory/__init__.py

@@ -0,0 +1,5 @@
+"""The watcher's inventory: what a project depends on, and what can't be checked (Phase 4).
+
+Two backends: OSV-Scanner over a source tree (`osv_scanner`), or an SBOM (`sbom`). Both report every
+dependency they can't check as an `UnresolvedDependency` with a reason; nothing is dropped.
+"""