vulnctl 0.1.0__py3-none-any.whl

vulnctl/__init__.py

@@ -0,0 +1,5 @@
+"""vulnctl — auditable, SSVC-based vulnerability prioritization."""
+
+from importlib.metadata import version
+
+__version__ = version("vulnctl")

vulnctl/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Intel-source adapters. Importing this package registers every bundled adapter."""
+
+from vulnctl.adapters import epss, exploits, ghsa, kev, nvd, osv
+
+__all__ = ["epss", "exploits", "ghsa", "kev", "nvd", "osv"]

vulnctl/adapters/base.py

@@ -0,0 +1,150 @@
+"""Source-adapter contract, registry, and shared fetch helpers (FRAMEWORK.md §3.2).
+
+Isolation rule (CLAUDE.md architecture rule 1): adapter modules may import
+only from here, ``vulnctl.cache``, and ``vulnctl.models`` — never each other,
+never the SSVC engine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from collections import deque
+from collections.abc import Awaitable, Iterable
+from datetime import timedelta
+from typing import ClassVar, TypeVar
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+
+from vulnctl.cache import Cache
+from vulnctl.models import (
+    EpssData,
+    ExploitData,
+    GhsaData,
+    KevData,
+    NvdData,
+    SourceMeta,
+    Unavailable,
+    VersionData,
+)
+
+T = TypeVar("T")
+
+#: Passed as TTL when running --offline: any cached row beats no data at all.
+OFFLINE_TTL = timedelta(days=36500)
+
+#: Refuse to parse response bodies larger than this — a compromised or
+#: misbehaving feed must not be able to exhaust memory during JSON parsing.
+#: (Largest legitimate body today is the ~3 MiB KEV catalog.)
+MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+
+
+def body_too_large(response: httpx.Response) -> bool:
+    """True if the response body exceeds :data:`MAX_RESPONSE_BYTES`."""
+    return len(response.content) > MAX_RESPONSE_BYTES
+
+
+AdapterData = EpssData | ExploitData | GhsaData | KevData | NvdData | VersionData
+
+
+class SourceResult(BaseModel):
+    """One adapter's answer for one CVE: the payload (or why it's missing) plus provenance."""
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    data: AdapterData | Unavailable
+    meta: SourceMeta
+
+
+class SourceAdapter(ABC):
+    """Base class for intel-source adapters.
+
+    Lifecycle per FRAMEWORK.md §3.2: check cache → fetch misses (bounded
+    concurrency, per-source rate limit) → validate strictly → write cache.
+    The ``httpx.AsyncClient`` is injected, never created per call.
+    """
+
+    name: ClassVar[str]
+    ttl: ClassVar[timedelta]
+    supports_offline: ClassVar[bool]
+
+    def __init__(self, client: httpx.AsyncClient, cache: Cache, *, offline: bool = False) -> None:
+        self._client = client
+        self._cache = cache
+        self._offline = offline
+
+    @abstractmethod
+    async def fetch(self, cve_ids: list[str]) -> dict[str, SourceResult]:
+        """Return a :class:`SourceResult` for every requested CVE ID."""
+
+    def _cache_ttl(self) -> timedelta:
+        return OFFLINE_TTL if self._offline else self.ttl
+
+
+_REGISTRY: dict[str, type[SourceAdapter]] = {}
+
+
+def register(cls: type[SourceAdapter]) -> type[SourceAdapter]:
+    """Class decorator adding an adapter to the registry (keyed by ``name``)."""
+    if cls.name in _REGISTRY:
+        raise ValueError(f"duplicate adapter name {cls.name!r}")
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def get_adapter(name: str) -> type[SourceAdapter]:
+    """Look up a registered adapter class by name."""
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        raise KeyError(f"no adapter registered under {name!r}") from None
+
+
+def all_adapters() -> list[type[SourceAdapter]]:
+    """All registered adapter classes, in registration order."""
+    return list(_REGISTRY.values())
+
+
+class RateLimit(BaseModel):
+    """At most ``requests`` calls per sliding ``window_seconds`` window."""
+
+    model_config = ConfigDict(strict=True, frozen=True, extra="forbid")
+
+    requests: int
+    window_seconds: float
+
+
+class RateLimiter:
+    """Async sliding-window rate limiter shared by an adapter's in-flight requests."""
+
+    def __init__(self, limit: RateLimit) -> None:
+        self._limit = limit
+        self._timestamps: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Block until a request slot is available inside the window."""
+        while True:
+            async with self._lock:
+                now = time.monotonic()
+                window = self._limit.window_seconds
+                while self._timestamps and now - self._timestamps[0] >= window:
+                    self._timestamps.popleft()
+                if len(self._timestamps) < self._limit.requests:
+                    self._timestamps.append(now)
+                    return
+                wait = window - (now - self._timestamps[0])
+            await asyncio.sleep(wait)
+
+
+async def bounded_gather(coros: Iterable[Awaitable[T]], *, limit: int) -> list[T]:
+    """``asyncio.gather`` capped at ``limit`` concurrent awaitables, order preserved."""
+    semaphore = asyncio.Semaphore(limit)
+
+    async def _run(coro: Awaitable[T]) -> T:
+        async with semaphore:
+            return await coro
+
+    return await asyncio.gather(*(_run(c) for c in coros))

vulnctl/adapters/epss.py

@@ -0,0 +1,158 @@
+"""FIRST EPSS adapter: exploitation probability + percentile per CVE.
+
+API: https://api.first.org/data/v1/epss (batched via comma-separated ``cve``
+param; numeric fields arrive as *strings* and are converted explicitly before
+strict model construction). TTL 24h.
+
+Offline: ``vulnctl/data/epss_snapshot.csv.gz`` — a dated capture of ~50
+well-known CVEs in ``cve,epss,percentile,date`` form (header comment records
+the snapshot date). A malformed response row degrades that CVE to
+``Unavailable(not_found)`` with detail; it never crashes the run.
+"""
+
+from __future__ import annotations
+
+import csv
+import gzip
+from datetime import UTC, date, datetime, time, timedelta
+from functools import cache as memoize
+from importlib import resources
+from typing import Any
+
+import httpx
+from pydantic import ValidationError
+
+from vulnctl.adapters.base import SourceAdapter, SourceResult, body_too_large, register
+from vulnctl.models import EpssData, SourceMeta, Unavailable, UnavailableReason
+
+API_URL = "https://api.first.org/data/v1/epss"
+_BATCH_SIZE = 100  # the API caps rows per response at its `limit` param
+
+
+@memoize
+def _load_snapshot() -> dict[str, EpssData]:
+    path = resources.files("vulnctl.data").joinpath("epss_snapshot.csv.gz")
+    with path.open("rb") as f:
+        text = gzip.decompress(f.read()).decode("utf-8")
+    lines = [line for line in text.splitlines() if not line.startswith("#")]
+    snapshot: dict[str, EpssData] = {}
+    for row in csv.DictReader(lines):
+        parsed = _parse_row(row)
+        if parsed is not None:
+            snapshot[parsed[0]] = parsed[1]
+    return snapshot
+
+
+def _parse_row(row: Any) -> tuple[str, EpssData] | None:
+    """Convert one API/CSV row into (cve_id, EpssData); None if malformed."""
+    if not isinstance(row, dict):
+        return None
+    try:
+        cve_id = str(row["cve"]).upper()
+        data = EpssData(
+            score=float(row["epss"]),
+            percentile=float(row["percentile"]),
+            date=date.fromisoformat(str(row["date"])),
+        )
+    except (KeyError, TypeError, ValueError, ValidationError):
+        return None
+    return cve_id, data
+
+
+@register
+class EpssAdapter(SourceAdapter):
+    """Cache-through EPSS lookups, batched ``_BATCH_SIZE`` CVEs per request."""
+
+    name = "epss"
+    ttl = timedelta(hours=24)
+    supports_offline = True
+
+    async def fetch(self, cve_ids: list[str]) -> dict[str, SourceResult]:
+        results: dict[str, SourceResult] = {}
+        misses: list[str] = []
+        for cve_id in cve_ids:
+            cached = self._cached_result(cve_id)
+            if cached is not None:
+                results[cve_id] = cached
+            else:
+                misses.append(cve_id)
+
+        if self._offline:
+            results.update(self._from_snapshot(misses))
+        else:
+            for start in range(0, len(misses), _BATCH_SIZE):
+                batch = misses[start : start + _BATCH_SIZE]
+                results.update(await self._fetch_batch(batch))
+        return results
+
+    def _cached_result(self, cve_id: str) -> SourceResult | None:
+        entry = self._cache.get_entry(self.name, cve_id, self._cache_ttl())
+        if entry is None:
+            return None
+        try:
+            data = EpssData.model_validate_json(entry.payload)
+        except ValidationError:
+            return None  # cache row written by an incompatible version: refetch
+        return SourceResult(data=data, meta=self._meta(entry.fetched_at, cache_hit=True))
+
+    def _from_snapshot(self, cve_ids: list[str]) -> dict[str, SourceResult]:
+        snapshot = _load_snapshot()
+        results: dict[str, SourceResult] = {}
+        for cve_id in cve_ids:
+            data = snapshot.get(cve_id)
+            if data is not None:
+                # Snapshot rows carry their own score date; use it as fetched_at.
+                fetched_at = datetime.combine(data.date, time.min, tzinfo=UTC)
+                results[cve_id] = SourceResult(
+                    data=data, meta=self._meta(fetched_at, cache_hit=False)
+                )
+            else:
+                results[cve_id] = self._unavailable(
+                    UnavailableReason.OFFLINE, "not in cache or bundled EPSS snapshot"
+                )
+        return results
+
+    async def _fetch_batch(self, batch: list[str]) -> dict[str, SourceResult]:
+        try:
+            response = await self._client.get(
+                API_URL, params={"cve": ",".join(batch), "limit": str(len(batch))}
+            )
+            response.raise_for_status()
+            if body_too_large(response):
+                failure = self._unavailable(
+                    UnavailableReason.SOURCE_DOWN, "response exceeds size limit"
+                )
+                return dict.fromkeys(batch, failure)
+            payload = response.json()
+        except (httpx.HTTPError, ValueError) as exc:
+            failure = self._unavailable(UnavailableReason.SOURCE_DOWN, str(exc))
+            return dict.fromkeys(batch, failure)
+
+        results: dict[str, SourceResult] = {}
+        rows = payload.get("data") if isinstance(payload, dict) else None
+        for row in rows if isinstance(rows, list) else []:
+            parsed = _parse_row(row)
+            if parsed is None:
+                continue  # malformed row: the CVE degrades to not_found below
+            cve_id, data = parsed
+            if cve_id not in batch:
+                continue
+            self._cache.set(self.name, cve_id, data.model_dump_json())
+            results[cve_id] = SourceResult(
+                data=data, meta=self._meta(datetime.now(UTC), cache_hit=False)
+            )
+        for cve_id in batch:
+            if cve_id not in results:
+                results[cve_id] = self._unavailable(
+                    UnavailableReason.NOT_FOUND, "no usable EPSS row for this CVE"
+                )
+        return results
+
+    def _meta(self, fetched_at: datetime, *, cache_hit: bool) -> SourceMeta:
+        return SourceMeta(source=self.name, fetched_at=fetched_at, cache_hit=cache_hit)
+
+    def _unavailable(self, reason: UnavailableReason, detail: str) -> SourceResult:
+        return SourceResult(
+            data=Unavailable(reason=reason, detail=detail),
+            meta=self._meta(datetime.now(UTC), cache_hit=False),
+        )

vulnctl/adapters/exploits.py

@@ -0,0 +1,83 @@
+"""Exploit-presence adapter: public exploit indicators per CVE.
+
+Snapshot-only for v0.1. Exploit-DB, Metasploit, and nuclei publish bulk
+indexes, not per-CVE query APIs, so the adapter answers from the bundled
+``vulnctl/data/exploit_index.json.gz`` (built by
+``scripts/build_exploit_index.py``) in both online and offline modes — a live
+refresh is v0.2 work. ``supports_offline`` is therefore ``True`` and no
+network call is ever made.
+
+Matching is exact CVE ID only (CLAUDE.md / ROADMAP #19): fuzzy title matching
+would produce false positives, and a false "exploit present" flips the
+``exploitation`` resolver from ``none`` to ``poc``, poisoning the verdict.
+
+A CVE absent from the index returns an *empty* ``ExploitData()`` — a real
+"no known public exploit as of the snapshot date" answer, not
+``Unavailable``. That lets the resolver conclude ``exploitation = none`` (when
+KEV also has it unlisted) instead of degrading to a default. The trade-off is
+snapshot staleness: a brand-new exploit is invisible until the index is
+rebuilt.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+from datetime import UTC, date, datetime, time, timedelta
+from functools import cache as memoize
+from importlib import resources
+from typing import Any
+
+from vulnctl.adapters.base import SourceAdapter, SourceResult, register
+from vulnctl.models import ExploitData, SourceMeta
+
+
+@memoize
+def _load_index() -> tuple[date, dict[str, ExploitData]]:
+    """Return (snapshot date, CVE→ExploitData) from the bundled gzip. Memoized."""
+    path = resources.files("vulnctl.data").joinpath("exploit_index.json.gz")
+    with path.open("rb") as f:
+        payload = json.loads(gzip.decompress(f.read()).decode("utf-8"))
+    generated = _parse_date(payload.get("generated"))
+    index: dict[str, ExploitData] = {}
+    raw = payload.get("cves")
+    for cve_id, entry in raw.items() if isinstance(raw, dict) else []:
+        if isinstance(entry, dict):
+            index[cve_id.upper()] = ExploitData(
+                edb_ids=_str_list(entry.get("edb_ids")),
+                msf_modules=_str_list(entry.get("msf_modules")),
+                nuclei_templates=_str_list(entry.get("nuclei_templates")),
+            )
+    return generated, index
+
+
+def _parse_date(value: Any) -> date:
+    if isinstance(value, str):
+        try:
+            return date.fromisoformat(value)
+        except ValueError:
+            pass
+    return datetime.now(UTC).date()
+
+
+def _str_list(value: Any) -> list[str]:
+    return [v for v in value if isinstance(v, str)] if isinstance(value, list) else []
+
+
+@register
+class ExploitsAdapter(SourceAdapter):
+    """Exact-match exploit-presence lookups from the bundled index."""
+
+    name = "exploits"
+    ttl = timedelta(days=1)  # unused: snapshot-only, no cache/network for v0.1
+    supports_offline = True
+
+    async def fetch(self, cve_ids: list[str]) -> dict[str, SourceResult]:
+        generated, index = _load_index()
+        fetched_at = datetime.combine(generated, time.min, tzinfo=UTC)
+        meta = SourceMeta(source=self.name, fetched_at=fetched_at, cache_hit=False)
+        # An absent CVE is a real empty answer, never Unavailable (see module docstring).
+        return {
+            cve_id: SourceResult(data=index.get(cve_id.upper(), ExploitData()), meta=meta)
+            for cve_id in cve_ids
+        }

vulnctl/adapters/ghsa.py

@@ -0,0 +1,220 @@
+"""GitHub Security Advisories adapter (REST Global Advisories API).
+
+REST rather than GraphQL: the GraphQL endpoint rejects anonymous requests
+outright, while ``GET /advisories`` works unauthenticated (60 req/h) — and
+SPEC.md NFR-2 requires zero mandatory credentials. ``VULNCTL_GITHUB_TOKEN``
+(env only, CLAUDE.md rule 6) raises the limit to 5,000 req/h. There is no
+client-side rate limiter — pacing 60 req/h would stall runs; instead a
+403/429 answer degrades that CVE to ``Unavailable(rate_limited)`` with no
+retries, and the 24h cache keeps repeat runs cheap.
+
+Lookup by ID kind: CVE IDs via ``?cve_id=`` (a JSON *list*; empty →
+``not_found``; the first GitHub-reviewed entry is used — the API orders by
+relevance); GHSA IDs via ``/advisories/{ghsa_id}`` (404 → ``not_found``).
+Any other ID kind (PYSEC-…, GO-…) is ``not_found`` without a request —
+GitHub cannot answer for those.
+
+Version ranges are normalized to the exact format the OSV adapter emits
+(purl-style label + ``<4.17.21``-style ranges) so the pipeline's keep-both
+merge can compare the two sources without false conflicts.
+
+No bundled snapshot: offline mode answers from cache only
+(``supports_offline = False``); misses degrade to ``Unavailable(offline)``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+from pydantic import ValidationError
+
+from vulnctl.adapters.base import (
+    SourceAdapter,
+    SourceResult,
+    body_too_large,
+    bounded_gather,
+    register,
+)
+from vulnctl.cache import Cache
+from vulnctl.models import GhsaData, SourceMeta, Unavailable, UnavailableReason, VersionData
+
+API_URL = "https://api.github.com/advisories"
+TOKEN_ENV = "VULNCTL_GITHUB_TOKEN"
+
+_CVE_RE = re.compile(r"CVE-\d{4}-\d{4,}", re.IGNORECASE)
+_GHSA_RE = re.compile(r"GHSA(-[23456789cfghjmpqrvwx]{4}){3}", re.IGNORECASE)
+_CONCURRENCY = 8
+
+#: GHSA ecosystem names → purl types, matching the labels OSV records carry.
+_PURL_TYPES = {
+    "npm": "npm",
+    "pip": "pypi",
+    "rubygems": "gem",
+    "maven": "maven",
+    "nuget": "nuget",
+    "composer": "composer",
+    "go": "golang",
+    "rust": "cargo",
+    "erlang": "hex",
+    "pub": "pub",
+    "swift": "swift",
+}
+
+
+def _purl_label(package: Any) -> str | None:
+    if not isinstance(package, dict):
+        return None
+    name = package.get("name")
+    if not isinstance(name, str) or not name:
+        return None
+    ecosystem = str(package.get("ecosystem") or "generic").lower()
+    purl_type = _PURL_TYPES.get(ecosystem, ecosystem)
+    if purl_type == "maven":
+        name = name.replace(":", "/")  # group:artifact → group/artifact purl form
+    return f"pkg:{purl_type}/{name}"
+
+
+def _normalize_range(range_text: str) -> str:
+    """``">= 3.0.0, < 3.9.2"`` → ``">=3.0.0 <3.9.2"`` (the OSV adapter's format)."""
+    clauses = [clause.strip().replace(" ", "") for clause in range_text.split(",")]
+    return " ".join(clause for clause in clauses if clause)
+
+
+def _parse_versions(vulnerabilities: Any) -> VersionData:
+    affected: list[str] = []
+    fixed: list[str] = []
+    for entry in vulnerabilities if isinstance(vulnerabilities, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        label = _purl_label(entry.get("package"))
+        range_text = entry.get("vulnerable_version_range")
+        if isinstance(range_text, str) and range_text:
+            normalized = _normalize_range(range_text)
+            affected.append(f"{label} {normalized}" if label else normalized)
+        patched = entry.get("first_patched_version")
+        if isinstance(patched, str) and patched:
+            fixed.append(f"{label} {patched}" if label else patched)
+    return VersionData(affected=list(dict.fromkeys(affected)), fixed=list(dict.fromkeys(fixed)))
+
+
+def _parse_advisory(advisory: Any) -> GhsaData | None:
+    """One advisory object → GhsaData; None if the shape is unusable."""
+    if not isinstance(advisory, dict) or not isinstance(advisory.get("ghsa_id"), str):
+        return None
+    severity = advisory.get("severity")
+    summary = advisory.get("summary")
+    return GhsaData(
+        ghsa_id=advisory["ghsa_id"],
+        severity=severity if isinstance(severity, str) and severity else "unknown",
+        summary=summary if isinstance(summary, str) else "",
+        versions=_parse_versions(advisory.get("vulnerabilities")),
+    )
+
+
+def _pick_advisory(payload: list[Any]) -> Any:
+    """Prefer the first GitHub-reviewed advisory; fall back to the first entry."""
+    for entry in payload:
+        if isinstance(entry, dict) and entry.get("github_reviewed_at") is not None:
+            return entry
+    return payload[0]
+
+
+@register
+class GhsaAdapter(SourceAdapter):
+    """Cache-through GitHub advisory lookups, anonymous or token-keyed."""
+
+    name = "ghsa"
+    ttl = timedelta(hours=24)
+    supports_offline = False
+
+    def __init__(self, client: httpx.AsyncClient, cache: Cache, *, offline: bool = False) -> None:
+        super().__init__(client, cache, offline=offline)
+        token = os.environ.get(TOKEN_ENV)
+        self._headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if token:
+            self._headers["Authorization"] = f"Bearer {token}"
+
+    async def fetch(self, cve_ids: list[str]) -> dict[str, SourceResult]:
+        results: dict[str, SourceResult] = {}
+        misses: list[str] = []
+        for cve_id in cve_ids:
+            if not (_CVE_RE.fullmatch(cve_id) or _GHSA_RE.fullmatch(cve_id)):
+                results[cve_id] = self._unavailable(
+                    UnavailableReason.NOT_FOUND, "GitHub answers only CVE or GHSA IDs"
+                )
+                continue
+            cached = self._cached_result(cve_id)
+            if cached is not None:
+                results[cve_id] = cached
+            else:
+                misses.append(cve_id)
+
+        if self._offline:
+            for cve_id in misses:
+                results[cve_id] = self._unavailable(
+                    UnavailableReason.OFFLINE, "GHSA has no bundled snapshot; cache miss"
+                )
+        elif misses:
+            fetched = await bounded_gather(
+                (self._fetch_one(cve_id) for cve_id in misses), limit=_CONCURRENCY
+            )
+            results.update(zip(misses, fetched, strict=True))
+        return results
+
+    def _cached_result(self, cve_id: str) -> SourceResult | None:
+        entry = self._cache.get_entry(self.name, cve_id, self._cache_ttl())
+        if entry is None:
+            return None
+        try:
+            data = GhsaData.model_validate_json(entry.payload)
+        except ValidationError:
+            return None  # cache row written by an incompatible version: refetch
+        return SourceResult(data=data, meta=self._meta(entry.fetched_at, cache_hit=True))
+
+    async def _fetch_one(self, cve_id: str) -> SourceResult:
+        if _CVE_RE.fullmatch(cve_id):
+            url, params = API_URL, {"cve_id": cve_id}
+        else:
+            url, params = f"{API_URL}/{cve_id}", {}
+        try:
+            response = await self._client.get(url, params=params, headers=self._headers)
+        except httpx.HTTPError as exc:
+            return self._unavailable(UnavailableReason.SOURCE_DOWN, str(exc))
+        if response.status_code == 404:
+            return self._unavailable(UnavailableReason.NOT_FOUND, "no GitHub advisory")
+        if response.status_code in (403, 429):
+            return self._unavailable(UnavailableReason.RATE_LIMITED, f"HTTP {response.status_code}")
+        if response.status_code != 200:
+            return self._unavailable(UnavailableReason.SOURCE_DOWN, f"HTTP {response.status_code}")
+        if body_too_large(response):
+            return self._unavailable(UnavailableReason.SOURCE_DOWN, "response exceeds size limit")
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            return self._unavailable(UnavailableReason.SOURCE_DOWN, f"invalid JSON: {exc}")
+
+        if isinstance(payload, list):  # the ?cve_id= endpoint
+            if not payload:
+                return self._unavailable(UnavailableReason.NOT_FOUND, "no GitHub advisory")
+            payload = _pick_advisory(payload)
+        data = _parse_advisory(payload)
+        if data is None:
+            return self._unavailable(UnavailableReason.SOURCE_DOWN, "unrecognized advisory shape")
+        self._cache.set(self.name, cve_id, data.model_dump_json())
+        return SourceResult(data=data, meta=self._meta(datetime.now(UTC), cache_hit=False))
+
+    def _meta(self, fetched_at: datetime, *, cache_hit: bool) -> SourceMeta:
+        return SourceMeta(source=self.name, fetched_at=fetched_at, cache_hit=cache_hit)
+
+    def _unavailable(self, reason: UnavailableReason, detail: str) -> SourceResult:
+        return SourceResult(
+            data=Unavailable(reason=reason, detail=detail),
+            meta=self._meta(datetime.now(UTC), cache_hit=False),
+        )