dependency-scout 0.1.0__py3-none-any.whl

api/README.md

@@ -0,0 +1,28 @@
+# API
+
+**When do you need to touch this directory?** When adding support for a new webhook source (a new bot, a new event type, or a new code host's webhook format). For adding new triage logic, see [`checks/`](../checks/README.md) or [`workflows/`](../workflows/README.md) instead.
+
+This is the production entry point: a FastAPI application that receives webhooks from GitHub and GitLab, verifies their authenticity, parses the PR/MR metadata, and starts `PRActionWorkflow` asynchronously.
+
+## Endpoints
+
+| Endpoint | Platform | Event types handled |
+|---|---|---|
+| `POST /webhook` | GitHub | `pull_request`, `pull_request_review` |
+| `POST /webhook/github` | GitHub | Same (alias) |
+| `POST /webhook/gitlab` | GitLab | Merge Request Hook |
+
+## What happens on each request
+
+1. **Verify** — GitHub: HMAC-SHA256 signature check against `GITHUB_WEBHOOK_SECRET`. GitLab: token comparison against `GITLAB_WEBHOOK_SECRET`. Requests that fail verification get a 401.
+2. **Filter** — only Dependabot and Renovate bot events are processed; everything else returns 200 immediately.
+3. **Parse** — ecosystem, package name, old version, and new version are extracted from the PR title/body/branch name via `helpers/pr_parser.py`.
+4. **Start workflow** — `PRActionWorkflow` is started (or a signal is sent if already running) via the Temporal client. The HTTP response returns 200 immediately; the workflow runs asynchronously.
+
+## Running locally
+
+```bash
+uv run uvicorn api.webhook:app --reload
+```
+
+Requires a running Temporal server (`temporal server start-dev`) and the worker (`uv run python -m worker`). For end-to-end local testing without a real webhook, use `uv run dependency-scout triage <PR URL>` directly.

api/webhook.py

@@ -0,0 +1,391 @@
+"""
+FastAPI webhook receiver for GitHub and GitLab pull_request / merge_request events.
+
+GitHub: POST /webhook or /webhook/github
+  - Verifies HMAC-SHA256 signature (X-Hub-Signature-256 / GITHUB_WEBHOOK_SECRET)
+  - Handles pull_request and pull_request_review events
+
+GitLab: POST /webhook/gitlab
+  - Verifies simple token comparison (X-Gitlab-Token / GITLAB_WEBHOOK_SECRET)
+  - Handles Merge Request Hook events
+
+Both endpoints filter to Dependabot/Renovate bots, parse package + version from the
+MR title/body/branch, and start PRActionWorkflow asynchronously, returning 200 immediately.
+"""
+
+import hashlib
+import hmac
+import json
+import logging
+import os
+import re
+from contextlib import asynccontextmanager
+from datetime import timedelta
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from packaging.utils import canonicalize_name
+from temporalio.client import Client
+from temporalio.common import WorkflowIDReusePolicy
+from temporalio.contrib.pydantic import pydantic_data_converter
+
+from ecosystems import get_name_re
+from models import PRContext
+from helpers.bot_parsers import get_bot_parser
+from workflows.pr_action_workflow import PRActionWorkflow
+
+logger = logging.getLogger(__name__)
+
+_PR_ACTIONS = {"opened", "synchronize", "reopened"}
+_GL_MR_ACTIONS = {"open", "reopen", "update"}
+
+# Fallback for unknown ecosystems — strict enough to block injection attacks.
+_FALLBACK_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,213}$")
+
+# Version: semver-ish — digits, dots, hyphens, plus, tilde, caret, letters
+_VERSION_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+\-~^]{0,127}$")
+
+
+def _validate_parsed_package(ecosystem: str, package: str, old: str, new: str) -> str | None:
+    """Return an error reason string, or None if the input is valid."""
+    name_re = get_name_re(ecosystem) or _FALLBACK_NAME_RE
+    if not name_re.match(package):
+        return f"invalid package name: {package!r}"
+    for label, ver in (("old_version", old), ("new_version", new)):
+        if ver != "unknown" and not _VERSION_RE.match(ver):
+            return f"invalid {label}: {ver!r}"
+    return None
+
+
+_temporal_client: Client | None = None
+
+
+def _check_config() -> None:
+    """Warn at startup about missing or suspicious configuration."""
+    has_github_secret = os.environ.get("GITHUB_WEBHOOK_SECRET")
+    has_gitlab_secret = os.environ.get("GITLAB_WEBHOOK_SECRET")
+    if not has_github_secret:
+        logger.error(
+            "GITHUB_WEBHOOK_SECRET is not set — /webhook/github requests will return 500. "
+            'Generate one with: python -c "import secrets; print(secrets.token_hex(32))"'
+        )
+    if not has_gitlab_secret:
+        logger.info("GITLAB_WEBHOOK_SECRET not set — /webhook/gitlab endpoint is disabled.")
+    has_github = os.environ.get("GITHUB_TOKEN") or os.environ.get("GITHUB_APP_ID")
+    has_gitlab = os.environ.get("GITLAB_TOKEN")
+    if not has_github and not has_gitlab:
+        logger.warning(
+            "No platform credentials found (GITHUB_TOKEN, GITHUB_APP_ID, or GITLAB_TOKEN). "
+            "The Scout will run but cannot post PR/MR comments or take actions."
+        )
+    classifier = os.environ.get("CLASSIFIER", "")
+    if not classifier and not os.environ.get("ANTHROPIC_API_KEY"):
+        logger.info(
+            "No LLM configured (ANTHROPIC_API_KEY / CLASSIFIER not set) — using rule-based classifier."
+        )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global _temporal_client
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    _check_config()
+    _temporal_client = await Client.connect(
+        os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"),
+        namespace=os.environ.get("TEMPORAL_NAMESPACE", "default"),
+        data_converter=pydantic_data_converter,
+    )
+    logger.info(
+        "Connected to Temporal at %s (namespace=%s, task_queue=%s)",
+        os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"),
+        os.environ.get("TEMPORAL_NAMESPACE", "default"),
+        os.environ.get("TEMPORAL_TASK_QUEUE", "dependency-scout"),
+    )
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def _verify_github_signature(body: bytes, signature: str) -> None:
+    secret = os.environ.get("GITHUB_WEBHOOK_SECRET", "")
+    if not secret:
+        raise HTTPException(status_code=500, detail="GITHUB_WEBHOOK_SECRET not configured")
+    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise HTTPException(status_code=401, detail="Invalid signature")
+
+
+def _verify_gitlab_token(token: str) -> None:
+    secret = os.environ.get("GITLAB_WEBHOOK_SECRET", "")
+    if not secret:
+        raise HTTPException(status_code=500, detail="GITLAB_WEBHOOK_SECRET not configured")
+    if not hmac.compare_digest(secret, token):
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+
+async def _start_workflow(pr_context: PRContext) -> str:
+    """Start (or attach to an existing) PRActionWorkflow and return the workflow ID."""
+    assert _temporal_client is not None
+    workflow_id = f"pr-action-{pr_context.repo.replace('/', '-')}-{pr_context.pr_number}"
+    await _temporal_client.start_workflow(
+        PRActionWorkflow.run,
+        pr_context,
+        id=workflow_id,
+        task_queue=os.environ.get("TEMPORAL_TASK_QUEUE", "dependency-scout"),
+        id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY,
+        execution_timeout=timedelta(days=30),
+    )
+    return workflow_id
+
+
+@app.get("/healthz")
+async def healthz() -> dict:
+    return {"status": "ok", "temporal_connected": _temporal_client is not None}
+
+
+# ---------------------------------------------------------------------------
+# GitHub webhook — /webhook (legacy) and /webhook/github
+# ---------------------------------------------------------------------------
+
+
+async def _handle_github_payload(payload: dict, event: str) -> dict:
+    if event == "pull_request_review":
+        return await _handle_github_review(payload)
+
+    if event != "pull_request":
+        logger.debug("Ignored event type: %s", event)
+        return {"status": "ignored", "reason": "not a pull_request event"}
+
+    action = payload.get("action")
+    if action not in _PR_ACTIONS:
+        logger.debug("Ignored pull_request action: %s", action)
+        return {"status": "ignored", "reason": f"action={action}"}
+
+    pr_author = payload.get("pull_request", {}).get("user", {}).get("login", "")
+    bot_parser = get_bot_parser(pr_author)
+    if not bot_parser:
+        logger.debug("Ignored PR from non-bot author: %s", pr_author)
+        return {"status": "ignored", "reason": f"author={pr_author}"}
+
+    repo = payload["repository"]["full_name"]
+    pr_number = payload["pull_request"]["number"]
+    title = payload["pull_request"]["title"]
+    body_text = payload["pull_request"].get("body") or ""
+    head_ref = payload["pull_request"]["head"]["ref"]
+    parsed = bot_parser.parse(title, body_text, head_ref)
+    if not parsed:
+        logger.warning(
+            "Could not parse package/version from PR title — skipping %s#%s. Title: %r",
+            repo,
+            pr_number,
+            title,
+        )
+        return {"status": "ignored", "reason": "could not parse package/version from PR title"}
+
+    err = _validate_parsed_package(
+        parsed.ecosystem, parsed.package, parsed.old_version, parsed.new_version
+    )
+    if err:
+        logger.warning("Validation failed for %s#%s: %s", repo, pr_number, err)
+        return {"status": "ignored", "reason": err}
+
+    installation_id = payload.get("installation", {}).get("id") or None
+    head_sha = payload["pull_request"]["head"]["sha"]
+    package_name = (
+        canonicalize_name(parsed.package) if parsed.ecosystem == "pip" else parsed.package
+    )
+
+    pr_context = PRContext(
+        repo=repo,
+        pr_number=pr_number,
+        pr_author=pr_author,
+        installation_id=installation_id,
+        platform="github",
+        ecosystem=parsed.ecosystem,
+        package_name=package_name,
+        old_version=parsed.old_version,
+        new_version=parsed.new_version,
+        head_sha=head_sha,
+    )
+
+    workflow_id = await _start_workflow(pr_context)
+    logger.info(
+        "Started workflow %s for %s#%s (%s %s %s→%s)",
+        workflow_id,
+        repo,
+        pr_number,
+        parsed.ecosystem,
+        package_name,
+        parsed.old_version,
+        parsed.new_version,
+    )
+    return {"status": "started", "workflow_id": workflow_id}
+
+
+async def _handle_github_review(payload: dict) -> dict:
+    """Route a pull_request_review event to the waiting PRActionWorkflow.
+
+    The reviewer identity comes from the HMAC-verified GitHub payload, not from
+    a self-reported claim, so it can be trusted as the authoritative approver.
+    Only 'submitted' events with state 'approved' or 'changes_requested' are acted on.
+    """
+    if payload.get("action") != "submitted":
+        return {"status": "ignored", "reason": "not a submitted review"}
+
+    state = payload.get("review", {}).get("state", "").lower()
+    if state not in {"approved", "changes_requested"}:
+        logger.debug("Ignored review with state=%s", state)
+        return {"status": "ignored", "reason": f"review state={state}"}
+
+    reviewer = payload.get("review", {}).get("user", {}).get("login", "")
+    repo = payload["repository"]["full_name"]
+    pr_number = payload["pull_request"]["number"]
+    workflow_id = f"pr-action-{repo.replace('/', '-')}-{pr_number}"
+    decision = "approve" if state == "approved" else "reject"
+
+    try:
+        assert _temporal_client is not None
+        handle = _temporal_client.get_workflow_handle(workflow_id)
+        await handle.signal(PRActionWorkflow.submit_decision, args=[decision, reviewer])
+    except Exception:
+        logger.debug("No active workflow for %s#%s — review signal dropped", repo, pr_number)
+        return {"status": "ignored", "reason": "no active workflow for this PR"}
+
+    logger.info("Signalled %s with decision=%s from reviewer=%s", workflow_id, decision, reviewer)
+    return {"status": "signalled", "workflow_id": workflow_id, "decision": decision}
+
+
+@app.post("/webhook")
+async def webhook_legacy(
+    request: Request,
+    x_hub_signature_256: str = Header(...),
+    x_github_event: str = Header(...),
+) -> dict:
+    """Legacy GitHub webhook endpoint — kept for backward compatibility."""
+    body = await request.body()
+    _verify_github_signature(body, x_hub_signature_256)
+    return await _handle_github_payload(json.loads(body), x_github_event)
+
+
+@app.post("/webhook/github")
+async def webhook_github(
+    request: Request,
+    x_hub_signature_256: str = Header(...),
+    x_github_event: str = Header(...),
+) -> dict:
+    body = await request.body()
+    _verify_github_signature(body, x_hub_signature_256)
+    return await _handle_github_payload(json.loads(body), x_github_event)
+
+
+# ---------------------------------------------------------------------------
+# GitLab webhook — /webhook/gitlab
+# ---------------------------------------------------------------------------
+
+
+@app.post("/webhook/gitlab")
+async def webhook_gitlab(
+    request: Request,
+    x_gitlab_token: str = Header(...),
+    x_gitlab_event: str = Header(...),
+) -> dict:
+    _verify_gitlab_token(x_gitlab_token)
+    payload = json.loads(await request.body())
+
+    if x_gitlab_event == "Merge Request Hook":
+        return await _handle_gitlab_mr(payload)
+
+    logger.debug("Ignored GitLab event type: %s", x_gitlab_event)
+    return {"status": "ignored", "reason": f"event={x_gitlab_event}"}
+
+
+async def _handle_gitlab_mr(payload: dict) -> dict:
+    attrs = payload.get("object_attributes", {})
+    action = attrs.get("action", "")
+
+    # GitLab sends "approved" as an MR action — route it as a review signal
+    if action == "approved":
+        return await _handle_gitlab_approval(payload)
+
+    if action not in _GL_MR_ACTIONS:
+        logger.debug("Ignored GitLab MR action: %s", action)
+        return {"status": "ignored", "reason": f"action={action}"}
+
+    pr_author = payload.get("user", {}).get("username", "")
+    bot_parser = get_bot_parser(pr_author)
+    if not bot_parser:
+        logger.debug("Ignored MR from non-bot author: %s", pr_author)
+        return {"status": "ignored", "reason": f"author={pr_author}"}
+
+    repo = payload.get("project", {}).get("path_with_namespace", "")
+    pr_number = attrs.get("iid", 0)
+    title = attrs.get("title", "")
+    body_text = attrs.get("description", "") or ""
+    head_ref = attrs.get("source_branch", "")
+    parsed = bot_parser.parse(title, body_text, head_ref)
+    if not parsed:
+        logger.warning(
+            "Could not parse package/version from MR title — skipping %s!%s. Title: %r",
+            repo,
+            pr_number,
+            title,
+        )
+        return {"status": "ignored", "reason": "could not parse package/version from MR title"}
+
+    err = _validate_parsed_package(
+        parsed.ecosystem, parsed.package, parsed.old_version, parsed.new_version
+    )
+    if err:
+        logger.warning("Validation failed for %s!%s: %s", repo, pr_number, err)
+        return {"status": "ignored", "reason": err}
+
+    head_sha = (attrs.get("last_commit") or {}).get("id", "")
+    package_name = (
+        canonicalize_name(parsed.package) if parsed.ecosystem == "pip" else parsed.package
+    )
+
+    pr_context = PRContext(
+        repo=repo,
+        pr_number=pr_number,
+        pr_author=pr_author,
+        installation_id=None,
+        platform="gitlab",
+        ecosystem=parsed.ecosystem,
+        package_name=package_name,
+        old_version=parsed.old_version,
+        new_version=parsed.new_version,
+        head_sha=head_sha,
+    )
+
+    workflow_id = await _start_workflow(pr_context)
+    logger.info(
+        "Started workflow %s for %s!%s (%s %s %s→%s)",
+        workflow_id,
+        repo,
+        pr_number,
+        parsed.ecosystem,
+        package_name,
+        parsed.old_version,
+        parsed.new_version,
+    )
+    return {"status": "started", "workflow_id": workflow_id}
+
+
+async def _handle_gitlab_approval(payload: dict) -> dict:
+    """Route a GitLab MR approval event to the waiting PRActionWorkflow."""
+    reviewer = payload.get("user", {}).get("username", "")
+    repo = payload.get("project", {}).get("path_with_namespace", "")
+    pr_number = payload.get("object_attributes", {}).get("iid", 0)
+
+    workflow_id = f"pr-action-{repo.replace('/', '-')}-{pr_number}"
+
+    try:
+        assert _temporal_client is not None
+        handle = _temporal_client.get_workflow_handle(workflow_id)
+        await handle.signal(PRActionWorkflow.submit_decision, args=["approve", reviewer])
+    except Exception:
+        logger.debug("No active workflow for %s!%s — approval signal dropped", repo, pr_number)
+        return {"status": "ignored", "reason": "no active workflow for this MR"}
+
+    logger.info("Signalled %s with decision=approve from reviewer=%s", workflow_id, reviewer)
+    return {"status": "signalled", "workflow_id": workflow_id, "decision": "approve"}

checks/README.md

@@ -0,0 +1,76 @@
+# Checks
+
+**When do you need a new check?** When there's a new external data source you want to run on every bump — if you find yourself thinking "I wish the classifier knew about X."
+
+Each check calls an external API or does a computation, then returns a structured result. The workflow runs all 11 in parallel and collects the results; checks do the actual work. For PR side-effect functions (comment, merge, close), see [`pr_actions/`](../pr_actions/README.md).
+
+## Triage checks
+
+These eleven checks run in parallel for every package bump. All degrade gracefully — if one fails or its API key is missing, the workflow continues with the remaining results.
+
+| File | Activity name | Returns | External service | API key |
+|---|---|---|---|---|
+| `metadata.py` | `activities.metadata.fetch` | `MetadataChecks` | Package registry (via ecosystem provider) | None |
+| `osv.py` | `activities.osv.check` | `OSVChecks` | [OSV.dev](https://osv.dev) vulnerability database | None |
+| `socket.py` | `activities.socket.score` | `SocketChecks` | [Socket.dev](https://socket.dev) supply chain scoring | `SOCKET_API_KEY` |
+| `package_diff.py` | `activities.package_diff.compute` | `PackageDiffChecks` | Package registry (archive download) | `GITHUB_TOKEN` (optional, for artifact-vs-source comparison) |
+| `maintainer.py` | `activities.maintainer.history` | `MaintainerChecks` | Package registry (via ecosystem provider) | None |
+| `release_age.py` | `activities.release_age.check` | `ReleaseAgeChecks` | Package registry (via ecosystem provider) | None |
+| `attestation.py` | `activities.attestation.check` | `AttestationChecks` | Package registry provenance endpoint | None |
+| `release_notes.py` | `activities.release_notes.check` | `ReleaseChecks` | GitHub / GitLab API | `GITHUB_TOKEN` / `GITLAB_TOKEN` (optional) |
+| `version_lineage.py` | `activities.version_lineage.check` | `VersionLineageChecks` | Package registry | None |
+| `depsdev.py` | `activities.depsdev.fetch` | `DepsDevChecks` | [deps.dev](https://deps.dev) | None |
+| `scorecard.py` | `activities.scorecard.fetch` | `ScorecardChecks` | [OpenSSF Scorecard](https://securityscorecards.dev) | None |
+
+`package_diff.compute` downloads and extracts the full package archive — it's the slowest check and runs on a longer timeout than the rest. It calls `activity.heartbeat()` at each phase (download → extract → artifact/source comparison) so Temporal can detect worker crashes mid-run rather than waiting for the full timeout to expire.
+
+## Check naming convention
+
+Each check function is registered under a string name (e.g. `"activities.metadata.fetch"`) that the workflow uses to schedule it. The name in `@activity.defn(name=...)` must match exactly what appears in `_CHECK_REGISTRY` in `workflows/package_triage_workflow.py`.
+
+This codebase uses string names deliberately: `_CHECK_REGISTRY` is a data structure mapping field names to check names and result types, making it easy to add or reorder checks without touching workflow control flow. The trade-off is that name mismatches are caught at runtime rather than import time — see [CLAUDE.md](../CLAUDE.md) for the full convention.
+
+## Attack signature patterns
+
+The [`signatures/`](signatures/README.md) subdirectory contains the YAML pattern files used by `package_diff.py` to detect suspicious code in package archives — network calls, obfuscation, persistence mechanisms, and dangerous file types. Add a new pattern there; no Python required.
+
+## Worker auto-discovery
+
+The worker (`worker.py`) automatically discovers and registers every check function found in `checks/*.py` and `pr_actions/*.py`. **You do not need to manually register new checks** — just put the file in this directory and restart the worker.
+
+## Adding a new triage check
+
+**Step 1 — create the check**
+
+```python
+# checks/mycheck.py
+from temporalio import activity
+from models import MyChecks
+
+@activity.defn(name="activities.mycheck.fetch")
+async def fetch(ecosystem: str, package: str, old_version: str, new_version: str) -> MyChecks:
+    ...
+    return MyChecks(...)
+```
+
+**Step 2 — add a model**
+
+Add `MyChecks` to `models/__init__.py` as a `BaseModel` subclass, and add it as a field on `PackageChecks`.
+
+**Step 3 — register in the workflow**
+
+Add a row to `_CHECK_REGISTRY` in `workflows/package_triage_workflow.py`:
+
+```python
+("mycheck", "activities.mycheck.fetch", MyChecks, False),
+```
+
+The fourth element is `True` if the check is slow (like `package_diff`) and needs a longer timeout.
+
+**Step 4 — write tests and regenerate fixtures**
+
+Add tests under `tests/`. The worker will auto-discover your new check file — no manual registration needed. Then regenerate the Temporal replay fixtures since the workflow history changed:
+
+```bash
+uv run python tests/generate_fixtures.py
+```

checks/attestation.py

@@ -0,0 +1,20 @@
+from ecosystems import get_provider
+from models import AttestationChecks
+from helpers.cache import ActivityCache
+from temporalio import activity
+
+_cache: ActivityCache = ActivityCache()  # SLSA provenance is immutable once signed
+
+
+@activity.defn(name="activities.attestation.check")
+async def check(
+    ecosystem: str, package: str, old_version: str, new_version: str
+) -> AttestationChecks:
+    """Check whether the registry can cryptographically prove the package was built by a trusted CI pipeline, using Sigstore/SLSA provenance records.
+
+    Returns an ``AttestationChecks`` with flags indicating whether provenance exists and whether it was issued by a recognized build system."""
+    key = (ecosystem, package, old_version, new_version)
+    return await _cache.get_or_compute(
+        key,
+        lambda: get_provider(ecosystem).fetch_attestations(package, old_version, new_version),
+    )

checks/classifier.py

@@ -0,0 +1,17 @@
+from temporalio import activity
+
+from classifiers import RuleBasedClassifier, get_classifier
+from models import PackageChecks, Verdict
+
+
+@activity.defn(name="activities.classifier.classify")
+async def classify(signals: PackageChecks) -> Verdict:
+    """Feed all collected package signals into the configured classifier and return a GREEN, YELLOW, or RED verdict with a rationale.
+
+    Uses an LLM classifier when one is configured; falls back to deterministic rules otherwise."""
+    clf = get_classifier()
+    if isinstance(clf, RuleBasedClassifier):
+        activity.logger.info("No LLM configured — using rule-based classifier")
+    else:
+        activity.logger.info("Using classifier: %s", type(clf).__name__)
+    return await clf.classify(signals)

checks/custom_checks.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from temporalio import activity
+
+from models import CheckContext
+
+
+@activity.defn(name="activities.custom_checks.run_all")
+async def run_all(ctx: CheckContext) -> dict[str, Any]:
+    """Discovers and runs all dependency_scout.checks entry-point functions in parallel."""
+    try:
+        from importlib.metadata import entry_points
+
+        eps = list(entry_points(group="dependency_scout.checks"))
+    except Exception:
+        return {}
+
+    if not eps:
+        return {}
+
+    async def _run_one(ep) -> tuple[str, Any]:
+        try:
+            fn = ep.load()
+            result = await fn(ctx)
+            return ep.name, result
+        except Exception as exc:  # noqa: BLE001
+            activity.logger.warning("Custom check %r failed: %r — skipped", ep.name, exc)
+            return ep.name, None
+
+    pairs = await asyncio.gather(*(_run_one(ep) for ep in eps))
+    return {name: result for name, result in pairs if result is not None}

checks/depsdev.py

@@ -0,0 +1,52 @@
+"""Activity: fetch deprecation status from deps.dev (https://api.deps.dev)."""
+
+from urllib.parse import quote
+
+from temporalio import activity
+
+from models import DepsDevChecks
+from helpers.cache import ActivityCache
+from helpers.http import get_client
+
+_cache: ActivityCache = ActivityCache(ttl_seconds=86400)  # deprecation changes rarely; 24h TTL
+
+_ECOSYSTEM_MAP = {
+    "pip": "pypi",
+    "npm": "npm",
+    "rubygems": "rubygems",
+    "maven": "maven",
+    "nuget": "nuget",
+}
+
+
+@activity.defn(name="activities.depsdev.fetch")
+async def fetch(ecosystem: str, package: str, old_version: str, new_version: str) -> DepsDevChecks:
+    """Query the deps.dev API for the new version and return whether it has been marked deprecated, along with the deprecation reason if one is provided."""
+    key = (ecosystem, package, new_version)
+    return await _cache.get_or_compute(key, lambda: _do_fetch(ecosystem, package, new_version))
+
+
+async def _do_fetch(ecosystem: str, package: str, new_version: str) -> DepsDevChecks:
+    system = _ECOSYSTEM_MAP.get(ecosystem)
+    if system is None:
+        return DepsDevChecks()
+
+    encoded_package = quote(package, safe="")
+    encoded_version = quote(new_version, safe="")
+    url = f"https://api.deps.dev/v3alpha/systems/{system}/packages/{encoded_package}/versions/{encoded_version}"
+
+    try:
+        client = get_client()
+        resp = await client.get(url, timeout=15.0)
+
+        if resp.status_code != 200:
+            return DepsDevChecks()
+
+        data = resp.json()
+        is_deprecated = data.get("isDeprecated", False)
+        deprecated_reason = data.get("deprecatedReason") or None
+
+        return DepsDevChecks(is_deprecated=is_deprecated, deprecated_reason=deprecated_reason)
+    except Exception as exc:
+        activity.logger.warning(f"deps.dev fetch failed for {package}@{new_version}: {exc!r}")
+        return DepsDevChecks()

checks/maintainer.py

@@ -0,0 +1,20 @@
+from ecosystems import get_provider
+from models import MaintainerChecks
+from helpers.cache import ActivityCache
+from temporalio import activity
+
+_cache: ActivityCache = ActivityCache()  # publishing history is immutable
+
+
+@activity.defn(name="activities.maintainer.history")
+async def history(
+    ecosystem: str, package: str, old_version: str, new_version: str
+) -> MaintainerChecks:
+    """Compare the list of maintainers who published the old version against those who published the new version.
+
+    Returns a ``MaintainerChecks`` indicating whether any new uploaders appeared, which can signal an account takeover."""
+    key = (ecosystem, package, old_version, new_version)
+    return await _cache.get_or_compute(
+        key,
+        lambda: get_provider(ecosystem).fetch_maintainer(package, old_version, new_version),
+    )

checks/metadata.py

@@ -0,0 +1,18 @@
+from ecosystems import get_provider
+from helpers.cache import ActivityCache
+from models import MetadataChecks
+from temporalio import activity
+
+_cache: ActivityCache = ActivityCache(ttl_seconds=3600)  # weekly downloads refresh daily; 1h TTL
+
+
+@activity.defn(name="activities.metadata.fetch")
+async def fetch(ecosystem: str, package: str, old_version: str, new_version: str) -> MetadataChecks:
+    """Fetch registry metadata for the package, including weekly download counts, whether the bump is a major version change, and the package description.
+
+    Returns a ``MetadataChecks`` populated from the ecosystem registry (e.g. PyPI, npm)."""
+    key = (ecosystem, package, old_version, new_version)
+    return await _cache.get_or_compute(
+        key,
+        lambda: get_provider(ecosystem).fetch_metadata(package, old_version, new_version),
+    )