vibe-coding-qa 0.5.0__py3-none-any.whl

dashboard/backend/security.py

@@ -0,0 +1,158 @@
+"""Input validation, path safety, rate limiting and error hygiene.
+
+The dashboard is bound to localhost by default, but it still must not become a
+generic filesystem or network proxy. Everything a request can influence is
+validated here before it reaches the engine:
+
+* local repository paths must resolve to a directory inside an allow-listed root
+  (no path traversal, no symlink escape);
+* git sources must be well-formed and must never carry embedded credentials;
+* AI calls are size-bounded and rate-limited;
+* errors returned to the client are safe: no stack traces, no credentials, no
+  local absolute paths from internals.
+"""
+
+import re
+import threading
+import time
+from pathlib import Path
+
+from vibe_coding_qa.repo import is_git_url
+from vibe_coding_qa.scanners import redact_secrets
+
+
+class ValidationError(ValueError):
+    """Raised when a client-supplied value is rejected."""
+
+
+_GITHUB_REF = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_SSH_GITHUB_URL = re.compile(r"^git@github\.com:[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\.git)?$")
+
+
+def resolve_repo_path(source: str, allowed_roots: list[Path]) -> Path:
+    """Validate a local repository path against the allow-listed roots.
+
+    Rejects empty values, non-existent paths, non-directories, and any path that
+    (after resolving symlinks) is not inside one of ``allowed_roots``.
+    """
+    candidate = (source or "").strip()
+    if not candidate:
+        raise ValidationError("Repository path is required.")
+    if "\0" in candidate:
+        raise ValidationError("Repository path contains an invalid character.")
+    try:
+        resolved = Path(candidate).expanduser().resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise ValidationError(f"Repository path does not exist: {candidate}")
+    if not resolved.is_dir():
+        raise ValidationError(f"Repository path is not a directory: {candidate}")
+    for root in allowed_roots:
+        try:
+            root_resolved = Path(root).expanduser().resolve()
+        except (OSError, RuntimeError):
+            continue
+        if resolved == root_resolved or root_resolved in resolved.parents:
+            return resolved
+    raise ValidationError(
+        "Repository path is outside the allowed roots. Set VCQA_ALLOWED_REPO_ROOTS "
+        "to permit additional directories."
+    )
+
+
+def resolve_repo_file(root: Path, relative_path: str) -> Path:
+    """Resolve a repository-relative file and reject traversal or symlink escape."""
+    candidate = Path(relative_path)
+    if candidate.is_absolute():
+        raise ValidationError("The requested file path must be relative to the repository.")
+    try:
+        resolved_root = root.resolve(strict=True)
+        target = (resolved_root / candidate).resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise ValidationError("The requested file is not available in the repository.") from None
+    if target == resolved_root or not target.is_relative_to(resolved_root) or not target.is_file():
+        raise ValidationError("The requested file must be inside the repository.")
+    return target
+
+
+def validate_git_source(source: str) -> str:
+    """Validate a remote git source and reject embedded credentials.
+
+    Accepts ``owner/repo`` shorthand, an ``https://`` URL, or an SSH URL. A
+    ``user:password@`` userinfo segment is rejected outright: credentials must be
+    supplied out-of-band (``VCQA_GITHUB_TOKEN``) and never travel through the API.
+    """
+    candidate = (source or "").strip()
+    if not candidate:
+        raise ValidationError("Repository source is required.")
+    if "@" in candidate.split("://", 1)[-1].split("/", 1)[0] and candidate.startswith("http"):
+        raise ValidationError("Repository URLs must not contain embedded credentials.")
+    if _GITHUB_REF.match(candidate):
+        return candidate
+    if not is_git_url(candidate):
+        raise ValidationError("Source must be a local path, owner/repo, or a git URL.")
+    if candidate.startswith(("http://", "https://")):
+        from urllib.parse import urlsplit
+
+        parsed = urlsplit(candidate)
+        if parsed.username is not None or parsed.password is not None:
+            raise ValidationError("Repository URLs must not contain embedded credentials.")
+        if parsed.scheme != "https" or parsed.hostname != "github.com":
+            raise ValidationError("Remote repositories must use HTTPS on github.com.")
+        try:
+            port = parsed.port
+        except ValueError:
+            raise ValidationError("GitHub repository URL has an invalid port.") from None
+        if port not in (None, 443):
+            raise ValidationError("GitHub repository URLs must use the standard HTTPS port.")
+        if parsed.query or parsed.fragment or not re.fullmatch(
+            r"/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\.git)?/?", parsed.path
+        ):
+            raise ValidationError("GitHub URLs must point directly to an owner/repository.")
+    elif candidate.startswith("git@") and not _SSH_GITHUB_URL.fullmatch(candidate):
+        raise ValidationError("SSH repository URLs must use the git@github.com:owner/repository format.")
+    return candidate
+
+
+class RateLimiter:
+    """A simple thread-safe fixed-window rate limiter."""
+
+    def __init__(self, max_requests: int, window_seconds: float = 60.0):
+        self.max_requests = max(1, int(max_requests))
+        self.window_seconds = float(window_seconds)
+        self._lock = threading.Lock()
+        self._hits: dict[str, list[float]] = {}
+
+    def allow(self, key: str = "default") -> bool:
+        now = time.monotonic()
+        with self._lock:
+            stamps = [t for t in self._hits.get(key, []) if now - t < self.window_seconds]
+            if len(stamps) >= self.max_requests:
+                self._hits[key] = stamps
+                return False
+            stamps.append(now)
+            self._hits[key] = stamps
+            return True
+
+
+def bound_text(text: str | None, max_chars: int) -> str:
+    """Redact secrets and enforce a hard character budget before egress."""
+    value = redact_secrets(text or "")
+    if len(value) > max_chars:
+        value = value[:max_chars] + "\n...[truncated]"
+    return value
+
+
+def safe_error(exc: BaseException, fallback: str = "The operation failed.") -> str:
+    """Return a client-safe error string.
+
+    Known, deliberately raised messages (``ValidationError``/``KeyError``/
+    ``FileNotFoundError`` created by this app) are surfaced; anything else is
+    collapsed to a generic message so internal details never leak.
+    """
+    if isinstance(exc, KeyError):
+        return str(exc.args[0]) if exc.args else "The requested item was not found."
+    if isinstance(exc, ValidationError):
+        return str(exc)
+    if isinstance(exc, OSError) and getattr(exc, "strerror", None):
+        return f"I/O error: {exc.strerror}"
+    return fallback

dashboard/backend/services/__init__.py

@@ -0,0 +1,7 @@
+"""Application services: the layer between the HTTP API and the engine."""
+
+from .repositories import RepositoryService
+from .scans import ScanRunner
+from .dashboard import DashboardService
+
+__all__ = ["RepositoryService", "ScanRunner", "DashboardService"]

dashboard/backend/services/dashboard.py

@@ -0,0 +1,172 @@
+"""Overview and activity aggregation.
+
+Everything here is derived from persisted scans and findings — there are no
+placeholder values. When a repository has never been scanned the API reports
+``has_data = false`` and empty series instead of inventing numbers.
+"""
+
+from ..config import Settings
+from ..persistence.store import Store
+
+
+class DashboardService:
+    def __init__(self, store: Store, settings: Settings):
+        self.store = store
+        self.settings = settings
+
+    # -------------------------------------------------------------- overview
+    def overview(self, repository_id: int | None = None) -> dict:
+        scans = self.store.latest_completed_scans()
+        if repository_id is not None:
+            scans = [s for s in scans if s["repository_id"] == repository_id]
+
+        latest = scans[0] if scans else None
+
+        severity = {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0}
+        categories: dict[str, int] = {}
+        for scan in scans:
+            for key, value in self.store.severity_counts(scan_id=scan["id"]).items():
+                severity[key] = severity.get(key, 0) + value
+            for module, value in self.store.module_counts(scan_id=scan["id"]).items():
+                categories[module] = categories.get(module, 0) + value
+
+        history_scans = self.store.recent_scans(limit=20)
+        if repository_id is not None:
+            history_scans = [s for s in history_scans if s["repository_id"] == repository_id]
+        history_scans = list(reversed(history_scans))
+
+        score_history = []
+        findings_trend = []
+        test_history = []
+        for scan in history_scans:
+            counts = self.store.severity_counts(scan_id=scan["id"])
+            at = scan.get("completed_at") or scan.get("created_at")
+            label = scan.get("repository_name") or f"repository {scan['repository_id']}"
+            score_history.append({
+                "scan_id": scan["id"],
+                "repository_id": scan["repository_id"],
+                "repository": label,
+                "at": at,
+                "score": scan.get("overall_score"),
+                "gate": scan.get("gate"),
+                "critical": scan.get("critical_count") or 0,
+                "high": scan.get("high_count") or 0,
+            })
+            findings_trend.append({
+                "scan_id": scan["id"],
+                "repository_id": scan["repository_id"],
+                "at": at,
+                "critical": counts.get("critical", 0),
+                "high": counts.get("high", 0),
+                "medium": counts.get("medium", 0),
+                "low": counts.get("low", 0),
+            })
+            test_history.append({
+                "scan_id": scan["id"],
+                "repository_id": scan["repository_id"],
+                "at": at,
+                "executed": scan.get("tests_executed"),
+                "passed": scan.get("tests_passed"),
+                "failed": scan.get("tests_failed"),
+                "skipped": scan.get("tests_skipped"),
+                "status": scan.get("test_status"),
+            })
+
+        repositories = self.store.list_repositories()
+        if repository_id is not None:
+            repositories = [r for r in repositories if r["id"] == repository_id]
+        repository_health = []
+        for repo in repositories:
+            latest_scan = repo.get("latest_scan") or {}
+            repository_health.append({
+                "repository_id": repo["id"],
+                "name": repo["name"],
+                "source_type": repo["source_type"],
+                "main_language": repo.get("main_language"),
+                "framework_count": len(repo.get("frameworks") or []),
+                "score": latest_scan.get("overall_score"),
+                "gate": latest_scan.get("gate"),
+                "critical": latest_scan.get("critical_count") or 0,
+                "high": latest_scan.get("high_count") or 0,
+                "open_findings": self.store.open_finding_count(repo["id"]),
+                "last_scan_at": latest_scan.get("completed_at"),
+            })
+
+        summary = {
+            "overall_score": latest.get("overall_score") if latest else None,
+            "critical": (latest.get("critical_count") or 0) if latest else 0,
+            "high": (latest.get("high_count") or 0) if latest else 0,
+            "total_open": self.store.open_finding_count(repository_id),
+            "tests_executed": latest.get("tests_executed") if latest else None,
+            "tests_passed": latest.get("tests_passed") if latest else None,
+            "gate": latest.get("gate") if latest else None,
+            "repository_count": len(repositories),
+            "latest_scan_duration_ms": latest.get("duration_ms") if latest else None,
+        }
+
+        return {
+            "summary": summary,
+            "severity_breakdown": severity,
+            "category_breakdown": categories,
+            "score_history": score_history,
+            "findings_trend": findings_trend,
+            "test_history": test_history,
+            "repository_health": repository_health,
+            "has_data": bool(scans),
+        }
+
+    # -------------------------------------------------------------- activity
+    def activity(self, limit: int = 30) -> dict:
+        items: list[dict] = []
+
+        for scan in self.store.recent_scans(limit=limit):
+            items.append({
+                "kind": "scan",
+                "title": f"Scan {scan['status']} · {scan.get('repository_name', '')}".strip(),
+                "detail": _scan_detail(scan),
+                "at": scan.get("completed_at") or scan.get("created_at"),
+                "repository_id": scan["repository_id"],
+                "scan_id": scan["id"],
+                "severity": None,
+            })
+
+        findings, _ = self.store.list_findings(limit=limit)
+        for finding in findings:
+            items.append({
+                "kind": "finding",
+                "title": f"{finding['severity'].upper()} · {finding['rule']}",
+                "detail": f"{finding['file']}:{finding['line']} — {finding.get('message') or ''}".strip(),
+                "at": finding.get("created_at"),
+                "repository_id": finding["repository_id"],
+                "scan_id": finding["scan_id"],
+                "finding_id": finding["id"],
+                "severity": finding["severity"],
+            })
+
+        for proposal in self.store.list_proposals()[:limit]:
+            items.append({
+                "kind": "remediation",
+                "title": f"Remediation {proposal['status']}",
+                "detail": f"{proposal.get('file') or ''} — {proposal.get('rationale') or ''}".strip(),
+                "at": proposal.get("updated_at") or proposal.get("created_at"),
+                "repository_id": proposal.get("repository_id"),
+                "scan_id": None,
+                "finding_id": proposal.get("finding_id"),
+                "severity": None,
+            })
+
+        items.sort(key=lambda item: item.get("at") or "", reverse=True)
+        return {"items": items[:limit]}
+
+
+def _scan_detail(scan: dict) -> str:
+    parts = []
+    if scan.get("overall_score") is not None:
+        parts.append(f"score {scan['overall_score']}")
+    if scan.get("gate"):
+        parts.append(f"gate {scan['gate']}")
+    parts.append(f"critical {scan.get('critical_count') or 0}")
+    parts.append(f"high {scan.get('high_count') or 0}")
+    if scan.get("total_findings") is not None:
+        parts.append(f"findings {scan['total_findings']}")
+    return " · ".join(parts)

dashboard/backend/services/intel.py

@@ -0,0 +1,341 @@
+"""Architecture graph and dependency intelligence.
+
+Both are derived from static evidence: the repository profile, the resolved
+lockfiles, and the persisted findings of the latest scan. Nothing here is
+invented — when the data is missing the response says so.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from vibe_coding_qa.profile import analyze_repo
+from vibe_coding_qa.scanners.dependencies import osv_lookup, resolved_dependencies
+
+from ..persistence.store import Store
+from .paths import repository_dir
+
+_OSV_MAX_LOOKUPS = 40
+
+# Profiling a repository (``analyze_repo``) walks the working tree and is by far
+# the most expensive step behind the Architecture and Dependencies pages. The
+# source only changes when the repo is re-scanned or edited, so memoise the
+# result per working-tree root for a short window. Without this, every page load
+# re-profiled the whole repo from scratch, which left those pages hanging on
+# large repositories.
+_PROFILE_TTL_SECONDS = 600.0
+_PROFILE_CACHE_MAX = 32
+_profile_cache: dict[str, tuple[float, object]] = {}
+_profile_lock = threading.Lock()
+
+
+def _profile_cached(root: Path):
+    """``analyze_repo(root)`` with a bounded, time-based cache."""
+    key = str(root.resolve())
+    now = time.monotonic()
+    with _profile_lock:
+        cached = _profile_cache.get(key)
+        if cached is not None and now - cached[0] < _PROFILE_TTL_SECONDS:
+            return cached[1]
+    # Compute outside the lock so different repositories can profile concurrently.
+    profile = analyze_repo(root)
+    with _profile_lock:
+        _profile_cache[key] = (now, profile)
+        if len(_profile_cache) > _PROFILE_CACHE_MAX:
+            oldest = min(_profile_cache, key=lambda item: _profile_cache[item][0])
+            _profile_cache.pop(oldest, None)
+    return profile
+
+
+def _profile_dict(store: Store, repository: dict, root: Path | None) -> dict:
+    """The repository profile as a plain dict (AppProfile.to_dict shape).
+
+    Prefers the profile persisted when the repo was last scanned, so the page
+    renders instantly. Otherwise it profiles the working tree once (cached) and
+    persists the result, so every later load - including after a restart - is
+    instant too. Returns ``{}`` when nothing is available.
+    """
+    persisted = store.get_setting(f"profile:{repository['id']}")
+    if isinstance(persisted, dict) and persisted:
+        return persisted
+    if root is None:
+        return {}
+    try:
+        computed = _profile_cached(root).to_dict()
+    except Exception:  # noqa: BLE001
+        return {}
+    if computed:
+        try:
+            store.set_setting(f"profile:{repository['id']}", computed)
+        except Exception:  # noqa: BLE001
+            pass
+    return computed
+
+
+def _source_node_for(file: str, module: str) -> str:
+    """Map a finding's file to a node in the architecture graph."""
+    lowered = file.lower()
+    if lowered.endswith((".sql", ".prisma", ".graphql")):
+        return "database"
+    if "/migrations/" in f"/{lowered}" or lowered.startswith("migrations/"):
+        return "database"
+    if ".github/workflows" in lowered or lowered.endswith((".tf", "vercel.json", "netlify.toml", "dockerfile")):
+        return "deployment"
+    if lowered.endswith((".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx")) or lowered.startswith("tests/"):
+        return "tests"
+    if module == "database":
+        return "database"
+    if module == "infrastructure" or module == "dependencies":
+        return "deployment"
+    return "app"
+
+
+def build_architecture(store: Store, repository: dict) -> dict:
+    root = repository_dir(repository)
+    notes: list[str] = [
+        "The graph is derived from static file inspection and the latest scan; it is not a runtime "
+        "call graph.",
+    ]
+    nodes: list[dict] = []
+    edges: list[dict] = []
+
+    def add_node(node_id: str, kind: str, label: str, **extra) -> None:
+        if any(node["id"] == node_id for node in nodes):
+            return
+        nodes.append({"id": node_id, "kind": kind, "label": label,
+                      "files": extra.pop("files", []), "confidence": "static", "details": extra})
+
+    add_node("app", "application", repository["name"],
+             source=repository["source"], source_type=repository["source_type"])
+
+    architecture = _profile_dict(store, repository, root)
+    if not architecture and root is not None:
+        notes.append("The repository could not be profiled; only persisted data is shown.")
+
+    if root is None and repository["source_type"] != "local":
+        notes.append("This remote repository has not been scanned yet, so no working tree is available.")
+
+    for framework in repository.get("frameworks") or architecture.get("frameworks") or []:
+        node_id = f"framework:{framework}"
+        add_node(node_id, "framework", framework)
+        edges.append({"source": "app", "target": node_id, "kind": "uses"})
+
+    for database in repository.get("database_tech") or architecture.get("databases") or []:
+        node_id = f"database:{database}"
+        add_node(node_id, "database", database)
+        edges.append({"source": "app", "target": node_id, "kind": "stores-data"})
+
+    for provider in repository.get("auth_tech") or architecture.get("auth_providers") or []:
+        node_id = f"auth:{provider}"
+        add_node(node_id, "auth", provider)
+        edges.append({"source": "app", "target": node_id, "kind": "authenticates"})
+
+    for target in repository.get("deployment") or architecture.get("deployment") or []:
+        node_id = f"deployment:{target}"
+        add_node(node_id, "deployment", target)
+        edges.append({"source": "app", "target": node_id, "kind": "deployed-via"})
+
+    for runner in architecture.get("test_runners") or []:
+        node_id = "tests"
+        add_node(node_id, "tests", "Automated tests", runners=architecture.get("test_runners") or [])
+        edges.append({"source": "app", "target": node_id, "kind": "verified-by"})
+
+    for endpoint in (architecture.get("endpoints") or [])[:25]:
+        node_id = f"endpoint:{endpoint.get('file')}:{endpoint.get('line')}"
+        add_node(node_id, "endpoint", str(endpoint.get("path"))[:80], files=[endpoint.get("file")])
+        edges.append({"source": "app", "target": node_id, "kind": "exposes"})
+
+    # Attach the latest scan's findings to graph nodes by file.
+    findings_by_node: dict[str, list[dict]] = {}
+    latest = store.latest_completed_scan(repository["id"])
+    if latest:
+        findings = []
+        offset = 0
+        while True:
+            page, total = store.list_findings(scan_id=latest["id"], limit=200, offset=offset)
+            findings.extend(page)
+            if not page or len(findings) >= total:
+                break
+            offset += len(page)
+        for finding in findings:
+            node_id = _source_node_for(finding["file"], finding["module"])
+            if node_id != "app" and not any(node["id"] == node_id for node in nodes):
+                node_id = "app"
+            findings_by_node.setdefault(node_id, []).append({
+                "id": finding["id"],
+                "rule": finding["rule"],
+                "module": finding["module"],
+                "severity": finding["severity"],
+                "file": finding["file"],
+                "line": finding["line"],
+                "message": finding.get("message"),
+            })
+    else:
+        notes.append("No completed scan exists yet, so findings are not mapped onto the graph.")
+
+    return {
+        "repository_id": repository["id"],
+        "nodes": nodes,
+        "edges": edges,
+        "findings_by_node": findings_by_node,
+        "notes": notes,
+    }
+
+
+def _ecosystem_for(name: str, package_manager: str | None) -> str:
+    if package_manager in ("pip", "poetry", "pipenv"):
+        return "PyPI"
+    return "npm"
+
+
+def build_dependencies(store: Store, repository: dict, *, osv: bool) -> dict:
+    root = repository_dir(repository)
+    notes: list[str] = []
+    if root is None:
+        return {
+            "repository_id": repository["id"],
+            "package_manager": repository.get("package_manager"),
+            "lockfiles": [],
+            "dependencies": [],
+            "notes": ["No working tree is available for this repository on this host; scan it first."],
+            "osv_checked": False,
+        }
+
+    pdict = _profile_dict(store, repository, root)
+
+    direct: dict[str, str | None] = {}
+    for name, version in (pdict.get("dependencies") or {}).items():
+        direct[name] = None if version in ("*", "") else version
+
+    lockfiles = list(pdict.get("lockfiles") or [])
+    package_manager = pdict.get("package_manager")
+
+    resolved: dict[str, dict] = {}
+    try:
+        for ecosystem, name, version, lockfile in resolved_dependencies(root):
+            entry = resolved.setdefault(name, {"ecosystem": ecosystem, "version": version,
+                                               "lockfile": str(Path(lockfile).name)})
+            entry["version"] = version
+    except Exception:  # noqa: BLE001
+        notes.append("Lockfiles could not be parsed for resolved versions.")
+
+    names = sorted(set(direct) | set(resolved))
+    if len(names) > 500:
+        notes.append(f"Dependency list truncated to the first 500 of {len(names)} entries.")
+        names = names[:500]
+
+    advisories: dict[str, list[dict]] = {}
+    osv_checked = False
+    if osv and names:
+        targets = []
+        for name in names:
+            entry = resolved.get(name)
+            version = (entry or {}).get("version") or direct.get(name)
+            if not version:
+                continue
+            ecosystem = (entry or {}).get("ecosystem") or _ecosystem_for(name, package_manager)
+            targets.append((name, ecosystem, version))
+            if len(targets) >= _OSV_MAX_LOOKUPS:
+                notes.append(f"OSV lookups limited to the first {_OSV_MAX_LOOKUPS} dependencies.")
+                break
+        if targets:
+            osv_checked = True
+            failures = 0
+            with ThreadPoolExecutor(max_workers=4) as pool:
+                futures = {pool.submit(osv_lookup, ecosystem, name, version): name
+                           for name, ecosystem, version in targets}
+                for future in as_completed(futures):
+                    name = futures[future]
+                    try:
+                        advisories[name] = [_advisory(a) for a in future.result()]
+                    except Exception:  # noqa: BLE001
+                        failures += 1
+                        advisories[name] = []
+            if failures:
+                notes.append(f"{failures} OSV lookup(s) could not be completed; results are partial.")
+        else:
+            notes.append("No pinned or resolved dependency versions were found to check against OSV.")
+
+    dependencies = []
+    for name in names:
+        entry = resolved.get(name) or {}
+        version = entry.get("version") or direct.get(name)
+        found = advisories.get(name) or []
+        if found:
+            status = "advisory"
+        elif not version:
+            status = "unpinned"
+        else:
+            status = "ok"
+        dependencies.append({
+            "name": name,
+            "version": version,
+            "direct": name in direct,
+            "license": None,
+            "advisories": found,
+            "status": status,
+        })
+
+    return {
+        "repository_id": repository["id"],
+        "package_manager": package_manager,
+        "lockfiles": lockfiles,
+        "dependencies": dependencies,
+        "notes": notes,
+        "osv_checked": osv_checked,
+    }
+
+
+def _advisory(raw: dict) -> dict:
+    aliases = raw.get("aliases") or []
+    severity = ((raw.get("database_specific") or {}).get("severity") or "").lower() or None
+    return {
+        "id": raw.get("id"),
+        "aliases": aliases[:5],
+        "severity": severity,
+        "summary": (raw.get("summary") or "")[:300],
+        "url": f"https://osv.dev/vulnerability/{raw.get('id', '')}",
+        "modified": raw.get("modified"),
+    }
+
+
+def compare_scans(store: Store, base_id: int, head_id: int) -> dict:
+    """Diff two scans of the same repository by finding fingerprint."""
+    base = store.get_scan(base_id)
+    head = store.get_scan(head_id)
+    if base is None or head is None:
+        raise KeyError("Both scans must exist to compare them.")
+    if base["repository_id"] != head["repository_id"]:
+        raise KeyError("Only scans of the same repository can be compared.")
+
+    base_findings, _ = store.list_findings(scan_id=base_id, limit=2000)
+    head_findings, _ = store.list_findings(scan_id=head_id, limit=2000)
+    base_map = {f["fingerprint"]: f for f in base_findings}
+    head_map = {f["fingerprint"]: f for f in head_findings}
+
+    added = [head_map[k] for k in head_map.keys() - base_map.keys()]
+    resolved = [base_map[k] for k in base_map.keys() - head_map.keys()]
+
+    def summarise(items: list[dict]) -> list[dict]:
+        return [
+            {"rule": i["rule"], "severity": i["severity"], "file": i["file"], "line": i["line"],
+             "message": i.get("message")}
+            for i in sorted(items, key=lambda x: (x["severity"], x["file"], x["line"]))
+        ]
+
+    return {
+        "base_scan_id": base_id,
+        "head_scan_id": head_id,
+        "base_score": base.get("overall_score"),
+        "head_score": head.get("overall_score"),
+        "score_delta": (
+            (head.get("overall_score") or 0) - (base.get("overall_score") or 0)
+            if base.get("overall_score") is not None and head.get("overall_score") is not None else None
+        ),
+        "added": summarise(added),
+        "resolved": summarise(resolved),
+        "unchanged_count": len(base_map.keys() & head_map.keys()),
+    }