devsecure-intelligence 0.1.0__py3-none-any.whl

devsecure_intelligence/__init__.py

@@ -0,0 +1,29 @@
+"""Python client for the DevSecure Intelligence API: rank CVEs by real-world risk (RPS from CVSS,
+EPSS and CISA KEV), with the reason for every rank. Docs: https://intelligence.devsecure.io/docs"""
+
+__version__ = "0.1.0"
+
+from .client import DEFAULT_BASE_URL, Client, extract_cve_ids, normalise_cve_id, rank_key  # noqa: E402
+from .errors import (  # noqa: E402
+    AuthenticationError,
+    DevSecureError,
+    NotFoundError,
+    PlanError,
+    QuotaExceededError,
+    RateLimitError,
+)
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    "Client",
+    "extract_cve_ids",
+    "normalise_cve_id",
+    "rank_key",
+    "DevSecureError",
+    "AuthenticationError",
+    "PlanError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaExceededError",
+]

devsecure_intelligence/__main__.py

@@ -0,0 +1,3 @@
+from .cli import entry
+
+entry()

devsecure_intelligence/cli.py

@@ -0,0 +1,233 @@
+"""``devsecure``: the DevSecure Intelligence API from the terminal.
+
+    devsecure cve CVE-2024-3400
+    devsecure prioritize trivy.json grype.json --fail-on high
+    trivy image -f json app:1.2 | devsecure prioritize - --json
+    devsecure movers --window 24h --type kev_added,priority_change
+    devsecure kev --limit 10
+
+Exit codes: 0 done, 1 ``--fail-on`` matched, 2 usage or API error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List, Mapping, Optional, Sequence, TextIO
+
+from . import __version__
+from .client import Client, extract_cve_ids
+from .errors import DevSecureError
+
+BAND_LABEL = {
+    "critical_priority": "Critical",
+    "high_priority": "High",
+    "medium_priority": "Medium",
+    "low_priority": "Low",
+    "informational": "Info",
+    "unknown": "Unknown",
+}
+# --fail-on: this band or more urgent fails; "kev" fails on any CISA KEV CVE whatever its band.
+FAIL_BANDS = {
+    "critical": {"critical_priority"},
+    "high": {"critical_priority", "high_priority"},
+    "medium": {"critical_priority", "high_priority", "medium_priority"},
+}
+
+
+def _table(rows: Sequence[Sequence[Any]], header: Sequence[str], out: TextIO) -> None:
+    cells = [[str(c) for c in header]] + [["" if c is None else str(c) for c in r] for r in rows]
+    widths = [max(len(r[i]) for r in cells) for i in range(len(header))]
+    for r in cells:
+        # The last column (a reason or name) isn't padded, so long text doesn't push trailing spaces.
+        out.write("  ".join(c.ljust(w) for c, w in zip(r[:-1], widths)) + ("  " if len(r) > 1 else "") + r[-1] + "\n")
+
+
+def _kev_listed(item: Mapping[str, Any]) -> bool:
+    kev = (item.get("evidence") or {}).get("kev") or {}
+    return bool(kev.get("listed"))
+
+
+def failing(ranked: Sequence[Mapping[str, Any]], fail_on: Sequence[str]) -> List[Mapping[str, Any]]:
+    """The CVEs that trip any of the --fail-on rules."""
+    bands = set().union(*(FAIL_BANDS[f] for f in fail_on if f in FAIL_BANDS)) if fail_on else set()
+    on_kev = "kev" in fail_on
+    return [r for r in ranked if r.get("priority_band") in bands or (on_kev and _kev_listed(r))]
+
+
+def _read_inputs(paths: Sequence[str], stdin: TextIO) -> str:
+    parts = []
+    for p in paths:
+        if p == "-":
+            parts.append(stdin.read())
+        else:
+            with open(p, encoding="utf-8", errors="replace") as f:
+                parts.append(f.read())
+    return "\n".join(parts)
+
+
+def cmd_cve(client: Client, args: argparse.Namespace, out: TextIO) -> int:
+    # No key: the public record (limited per IP) still answers.
+    data = client.cve(args.cve_id) if client.api_key else client.public_cve(args.cve_id)
+    if args.json:
+        json.dump(data, out, indent=2)
+        out.write("\n")
+        return 0
+    d = data.get("data", data)
+    rps = d.get("rps") or {}
+    kev = d.get("kev") or (d.get("signals") or {}).get("kev") or {}
+    expl = d.get("explanation") or {}
+    out.write(f"{d.get('cve_id')}  {BAND_LABEL.get(str(rps.get('band')), rps.get('band'))}  RPS {rps.get('score')}")
+    out.write(f"  (set by {rps.get('band_basis')})\n" if rps.get("band_basis") else "\n")
+    out.write(f"CISA KEV: {'yes' if kev.get('in_catalog') else 'no'}\n")
+    if expl.get("summary"):
+        out.write(f"{expl['summary']}\n")
+    as_of = data.get("data_as_of") or d.get("data_as_of")
+    if as_of:
+        out.write(f"Data as of {as_of}\n")
+    return 0
+
+
+def cmd_prioritize(client: Client, args: argparse.Namespace, out: TextIO, stdin: TextIO) -> int:
+    text = _read_inputs(args.inputs or ["-"], stdin)
+    ids = extract_cve_ids(text)
+    if not ids:
+        sys.stderr.write("No CVE IDs found in the input.\n")
+        return 0
+    result = client.prioritize(ids, chunk_size=args.chunk_size)
+    ranked = result.get("ranked") or []
+    fail_on = [f.strip().lower() for f in (args.fail_on or "").split(",") if f.strip()]
+    tripped = failing(ranked, fail_on)
+    if args.json:
+        json.dump(result, out, indent=2)
+        out.write("\n")
+    else:
+        rows = [
+            (
+                r.get("rank_in_request"),
+                r.get("cve_id"),
+                BAND_LABEL.get(r.get("priority_band", ""), r.get("priority_band")),
+                r.get("rps_score"),
+                "yes" if _kev_listed(r) else "",
+                r.get("reason", ""),
+            )
+            for r in ranked
+        ]
+        _table(rows, ["#", "CVE", "PRIORITY", "RPS", "KEV", "REASON"], out)
+        out.write(f"\n{result.get('found', 0)} of {result.get('total', len(ids))} found")
+        out.write(f"; data as of {result['data_as_of']}\n" if result.get("data_as_of") else "\n")
+    if tripped:
+        sys.stderr.write(
+            f"{len(tripped)} CVE(s) match --fail-on {','.join(fail_on)}: "
+            + ", ".join(str(r.get("cve_id")) for r in tripped)
+            + "\n"
+        )
+        return 1
+    return 0
+
+
+def cmd_movers(client: Client, args: argparse.Namespace, out: TextIO) -> int:
+    types = [t.strip() for t in args.type.split(",")] if args.type else None
+    res = client.movers(window=args.window, scope=args.scope, types=types, limit=args.limit)
+    if args.json:
+        json.dump(res, out, indent=2)
+        out.write("\n")
+        return 0
+    items = (res.get("data") or {}).get("items") or []
+    rows = [
+        (
+            m.get("occurred_on"),
+            m.get("cve_id"),
+            m.get("type"),
+            BAND_LABEL.get(m.get("priority_now") or "", m.get("priority_now") or ""),
+            m.get("reason", ""),
+        )
+        for m in items
+    ]
+    _table(rows, ["DATE", "CVE", "CHANGE", "PRIORITY NOW", "REASON"], out)
+    return 0
+
+
+def cmd_kev(client: Client, args: argparse.Namespace, out: TextIO) -> int:
+    res = client.kev(limit=args.limit)
+    if args.json:
+        json.dump(res, out, indent=2)
+        out.write("\n")
+        return 0
+    rows = [
+        (r.get("rps_score"), r.get("cve_id"), (r.get("kev") or {}).get("vendor_project"), (r.get("kev") or {}).get("product"))
+        for r in res.get("results") or []
+    ]
+    _table(rows, ["RPS", "CVE", "VENDOR", "PRODUCT"], out)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="devsecure", description="DevSecure Intelligence from the terminal. Reads DEVSECURE_API_KEY."
+    )
+    p.add_argument("--version", action="version", version=f"devsecure {__version__}")
+    p.add_argument("--json", action="store_true", help="print the API's JSON instead of a table")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("cve", help="one CVE: Final Priority, RPS, KEV and the reason (no key: the public record)")
+    c.add_argument("cve_id")
+
+    pr = sub.add_parser("prioritize", help="rank the CVEs found in scanner output, SBOMs or any text files ('-' = stdin)")
+    pr.add_argument("inputs", nargs="*", metavar="FILE")
+    pr.add_argument(
+        "--fail-on", metavar="RULES", help="exit 1 if any CVE matches: critical, high, medium and/or kev (comma-separated)"
+    )
+    pr.add_argument("--chunk-size", type=int, default=None, help="IDs per call (default: your plan's limit)")
+
+    m = sub.add_parser("movers", help="what changed: KEV additions, priority changes, new exploits, fixes, EPSS jumps")
+    m.add_argument("--window", choices=["24h", "7d"], default="7d")
+    m.add_argument("--scope", choices=["actionable", "all"], default=None)
+    m.add_argument(
+        "--type", help="comma-separated: priority_change, kev_added, metasploit_module, exploitdb_added, fix_found, epss_jump"
+    )
+    m.add_argument("--limit", type=int, default=None)
+
+    k = sub.add_parser("kev", help="the CISA KEV catalogue ranked by RPS (no key needed)")
+    k.add_argument("--limit", type=int, default=20)
+    return p
+
+
+def main(
+    argv: Optional[Sequence[str]] = None, *, client: Optional[Client] = None, out: TextIO = sys.stdout, stdin: TextIO = sys.stdin
+) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "prioritize" and args.fail_on:
+        bad = [f for f in args.fail_on.split(",") if f.strip().lower() not in (*FAIL_BANDS, "kev")]
+        if bad:
+            parser.error(f"--fail-on: unknown rule(s) {', '.join(bad)}; use critical, high, medium, kev")
+    try:
+        client = client or Client()
+        if args.command == "cve":
+            return cmd_cve(client, args, out)
+        if args.command == "prioritize":
+            return cmd_prioritize(client, args, out, stdin)
+        if args.command == "movers":
+            return cmd_movers(client, args, out)
+        return cmd_kev(client, args, out)
+    except DevSecureError as e:
+        sys.stderr.write(f"devsecure: {e}\n")
+        if e.docs_url:
+            sys.stderr.write(f"  {e.docs_url}\n")
+        return 2
+    except (OSError, ValueError) as e:
+        sys.stderr.write(f"devsecure: {e}\n")
+        return 2
+
+
+def entry() -> None:  # console script
+    sys.exit(main())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    entry()
+
+
+__all__: List[str] = ["main", "failing", "build_parser"]

devsecure_intelligence/client.py

@@ -0,0 +1,366 @@
+"""Client for the DevSecure Intelligence API (https://api.intelligence.devsecure.io).
+
+Standard library only. Every call goes to the same endpoints and limits as the HTTP API, with your
+own key. Retries: network errors, timeouts, 5xx and ``429 rate_limited`` (honouring ``Retry-After``),
+with exponential backoff; never ``quota_exceeded`` or other 4xx.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple, Union, cast
+
+from . import __version__
+from .errors import DevSecureError, error_for
+from .models import BAND_ORDER, Mover, PrioritizeResult, Quota, RankedCve
+
+DEFAULT_BASE_URL = "https://api.intelligence.devsecure.io"
+DEFAULT_TIMEOUT = 30.0  # the API's own request timeout, in seconds
+MAX_IDS = 1000  # the largest per-call list on any plan; the API enforces your plan's own (Free: 25)
+MAX_RETRY_WAIT = 60.0  # never sleep longer than this for one retry, whatever Retry-After says
+
+CVE_ID = re.compile(r"^CVE-\d{4}-\d{4,}$")
+CVE_IN_TEXT = re.compile(r"CVE-\d{4}-\d{4,}", re.IGNORECASE)
+SIGNUP_URL = "https://intelligence.devsecure.io/signup"
+STATUS_URL = "https://intelligence.devsecure.io/status"
+
+# (method, url, headers, body, timeout) -> (status, headers, body bytes). Injectable for tests.
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes], float], Tuple[int, Mapping[str, str], bytes]]
+
+
+def normalise_cve_id(value: str) -> str:
+    """Upper-case and trim; raise for anything that isn't a CVE ID (the API would 400 anyway)."""
+    cve_id = str(value or "").strip().upper()
+    if not CVE_ID.match(cve_id):
+        raise DevSecureError(400, "invalid_cve_id", f'"{value}" is not a CVE ID (they look like CVE-2021-44228).')
+    return cve_id
+
+
+def extract_cve_ids(text: str) -> List[str]:
+    """Every distinct CVE ID in a scanner report, SBOM or any text, in first-seen order."""
+    seen: Dict[str, None] = {}
+    for match in CVE_IN_TEXT.findall(text or ""):
+        seen.setdefault(match.upper(), None)
+    return list(seen)
+
+
+def rank_key(item: Mapping[str, Any]) -> Tuple[int, float]:
+    """The API's ranking: band first (a KEV CVE floored at High never ranks under a Medium), then RPS."""
+    band = item.get("priority_band")
+    band_rank = BAND_ORDER.index(band) if band in BAND_ORDER else len(BAND_ORDER)
+    return band_rank, -float(item.get("rps_score") or 0)
+
+
+def _urllib_transport(
+    method: str, url: str, headers: Mapping[str, str], body: Optional[bytes], timeout: float
+) -> Tuple[int, Mapping[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+    try:
+        # B310: Client accepts only https:// or http://localhost base URLs, never file: or custom schemes.
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # nosec B310
+            return res.status, dict(res.headers.items()), res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers.items()) if e.headers else {}, e.read() or b""
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    lname = name.lower()
+    for k, v in headers.items():
+        if k.lower() == lname:
+            return v
+    return None
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    value = _header(headers, "Retry-After")
+    try:
+        return max(0.0, float(value)) if value is not None else None
+    except ValueError:
+        return None
+
+
+class Client:
+    """DevSecure Intelligence API client.
+
+    >>> from devsecure_intelligence import Client
+    >>> client = Client()                      # reads DEVSECURE_API_KEY
+    >>> client.prioritize(["CVE-2021-44228", "CVE-2024-3400"])["ranked"][0]["priority_band"]
+    'critical_priority'
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+        user_agent: Optional[str] = None,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("DEVSECURE_API_KEY") or None
+        self.base_url = (base_url or os.environ.get("DEVSECURE_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
+        if not self.base_url.startswith("https://") and not re.match(r"^http://(localhost|127\.0\.0\.1)(:|/|$)", self.base_url):
+            # The key travels in a header: refuse to send it in clear text anywhere but localhost.
+            raise ValueError(f"base_url must be https:// (got {self.base_url!r}).")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.user_agent = user_agent or f"devsecure-intelligence-python/{__version__}"
+        self._transport = transport or _urllib_transport
+        self._sleep = sleep
+        #: Rate-limit and quota headers from the most recent response.
+        self.last_quota: Quota = {}
+        #: ``X-Request-Id`` of the most recent response; quote it to support.
+        self.last_request_id: Optional[str] = None
+
+    def __repr__(self) -> str:  # never print the key
+        return f"Client(base_url={self.base_url!r}, api_key={'set' if self.api_key else 'not set'})"
+
+    # -- transport -------------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        auth: bool = True,
+    ) -> Any:
+        """Call any endpoint and return the parsed JSON. Raises :class:`DevSecureError` subclasses."""
+        if auth and not self.api_key:
+            raise error_for(401, "unauthorized")(
+                401, "unauthorized", f"Set DEVSECURE_API_KEY or pass api_key= (get a free key at {SIGNUP_URL})."
+            )
+        query = {k: ("true" if v is True else "false" if v is False else v) for k, v in (params or {}).items() if v is not None}
+        url = self.base_url + path + (("?" + urllib.parse.urlencode(query, doseq=True)) if query else "")
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if auth:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        body = None
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            body = json.dumps(json_body).encode("utf-8")
+
+        attempt = 0
+        while True:
+            try:
+                status, res_headers, raw = self._transport(method, url, headers, body, self.timeout)
+            except Exception as exc:  # timeouts and connection errors from the transport
+                timed_out = "timed out" in str(exc).lower() or isinstance(exc, TimeoutError)
+                err = DevSecureError(
+                    504 if timed_out else 503,
+                    "timeout" if timed_out else "network_error",
+                    (
+                        f"The API did not answer within {self.timeout:g} s. Status: {STATUS_URL}"
+                        if timed_out
+                        else f"Could not reach {self.base_url} ({exc}). Check the network or DEVSECURE_API_BASE."
+                    ),
+                )
+                if attempt < self.max_retries:
+                    attempt += 1
+                    self._sleep(self._backoff(attempt, None))
+                    continue
+                raise err from exc
+
+            self._record(res_headers)
+            payload = None
+            if raw:
+                try:
+                    payload = json.loads(raw.decode("utf-8"))
+                except ValueError:
+                    payload = None
+            if 200 <= status < 300:
+                return payload
+
+            e = payload.get("error", {}) if isinstance(payload, dict) and isinstance(payload.get("error"), dict) else {}
+            code = e.get("code") or ("rate_limited" if status == 429 else "http_error")
+            retry_after = _retry_after(res_headers)
+            retryable = status >= 500 or (status == 429 and code != "quota_exceeded")
+            if retryable and attempt < self.max_retries:
+                attempt += 1
+                self._sleep(self._backoff(attempt, retry_after))
+                continue
+            raise error_for(status, code)(
+                status,
+                code,
+                e.get("message") or f"HTTP {status}",
+                docs_url=e.get("docs_url"),
+                request_id=e.get("request_id") or self.last_request_id,
+                retry_after=retry_after,
+            )
+
+    def _call(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        return cast(Dict[str, Any], self.request(method, path, **kwargs))
+
+    def _backoff(self, attempt: int, retry_after: Optional[float]) -> float:
+        if retry_after is not None:
+            return min(retry_after, MAX_RETRY_WAIT)
+        # B311: retry jitter, not a secret.
+        return float(min(0.5 * (2 ** (attempt - 1)) + random.uniform(0, 0.25), MAX_RETRY_WAIT))  # nosec B311
+
+    def _record(self, headers: Mapping[str, str]) -> None:
+        quota: Quota = {}
+        for key, name in (
+            ("rate_limit", "X-RateLimit-Limit"),
+            ("rate_limit_remaining", "X-RateLimit-Remaining"),
+            ("rate_limit_reset", "X-RateLimit-Reset"),
+            ("quota_limit", "X-Quota-Limit"),
+            ("quota_remaining", "X-Quota-Remaining"),
+        ):
+            value = _header(headers, name)
+            if value is not None and value.strip().lstrip("-").isdigit():
+                quota[key] = int(value)  # type: ignore[literal-required]
+        self.last_quota = quota
+        self.last_request_id = _header(headers, "X-Request-Id")
+
+    # -- lookups (any plan) ----------------------------------------------------------------
+
+    def cve(self, cve_id: str) -> Dict[str, Any]:
+        """``GET /api/v1/cve/{id}``: RPS score, signals, evidence and a plain-English explanation."""
+        return self._call("GET", f"/api/v1/cve/{normalise_cve_id(cve_id)}")
+
+    def rps(self, cve_id: str) -> Dict[str, Any]:
+        """``GET /api/v1/rps/{id}``: the RPS score and Final Priority only."""
+        return self._call("GET", f"/api/v1/rps/{normalise_cve_id(cve_id)}")
+
+    def cve_batch(self, cve_ids: Iterable[str]) -> Dict[str, Any]:
+        """``POST /api/v1/cve/batch``: full records for up to your plan's limit (Free 100, Pro+ 1,000)."""
+        ids = [normalise_cve_id(c) for c in cve_ids]
+        return self._call("POST", "/api/v1/cve/batch", json_body={"cve_ids": ids})
+
+    def prioritize(self, cve_ids: Union[str, Iterable[str]], *, chunk_size: Optional[int] = None) -> PrioritizeResult:
+        """``POST /api/v1/prioritize``: rank CVEs into a fix order, with the reason for each.
+
+        ``cve_ids`` may be a list of IDs or any text (a scanner report, SBOM); IDs are extracted and
+        de-duplicated. Lists longer than ``chunk_size`` are sent in several calls and merged into
+        one ranking, in the API's own order. Without ``chunk_size``, a list over your plan's per-call
+        limit (Free: 25) is retried in chunks of that limit, read from the API's ``list_too_long`` error.
+        """
+        ids = extract_cve_ids(cve_ids) if isinstance(cve_ids, str) else list(dict.fromkeys(normalise_cve_id(c) for c in cve_ids))
+        if not ids:
+            raise DevSecureError(400, "bad_request", "No CVE IDs to prioritize.")
+        size = min(chunk_size or MAX_IDS, MAX_IDS)
+        if size < 1:
+            raise ValueError("chunk_size must be at least 1.")
+        if len(ids) <= size:
+            try:
+                return cast(PrioritizeResult, self._call("POST", "/api/v1/prioritize", json_body={"cve_ids": ids}))
+            except DevSecureError as e:
+                limit = _plan_limit(e)
+                if chunk_size is not None or limit is None or limit >= len(ids):
+                    raise
+                size = limit
+        return _merge_prioritize(
+            [
+                cast(PrioritizeResult, self._call("POST", "/api/v1/prioritize", json_body={"cve_ids": ids[i : i + size]}))
+                for i in range(0, len(ids), size)
+            ]
+        )
+
+    def cwe_cves(self, cwe_id: Union[str, int], **filters: Any) -> Dict[str, Any]:
+        """``GET /api/v1/cwe/{cwe}/cves``: CVEs for a weakness. Filters: ``severity``, ``has_patch``,
+        ``is_kev``, ``epss_min``, ``limit``, ``offset``, ``sort``."""
+        cwe = str(cwe_id).upper()
+        cwe = cwe if cwe.startswith("CWE-") else f"CWE-{cwe}"
+        return self._call("GET", f"/api/v1/cwe/{urllib.parse.quote(cwe)}/cves", params=filters)
+
+    def recent(self, *, since: Optional[str] = None, sort: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        """``GET /api/v1/cve/recent``: CVEs changed since a time (ISO 8601), to keep a local copy in sync."""
+        return self._call("GET", "/api/v1/cve/recent", params={"since": since, "sort": sort, "limit": limit})
+
+    def movers(
+        self,
+        *,
+        window: str = "7d",
+        scope: Optional[str] = None,
+        types: Optional[Sequence[str]] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """``GET /api/v1/movers``: what changed (KEV additions, priority changes, new exploits, fixes,
+        EPSS jumps) in the last ``24h`` or ``7d``. Items are in ``["data"]["items"]``."""
+        return self._call(
+            "GET",
+            "/api/v1/movers",
+            params={"window": window, "scope": scope, "type": ",".join(types) if types else None, "limit": limit},
+        )
+
+    def iter_movers(self, **kwargs: Any) -> Iterable[Mover]:
+        """The movers items themselves."""
+        return iter((self.movers(**kwargs).get("data") or {}).get("items") or [])
+
+    # -- enrichment (Pro and above; patches on Business and Enterprise) --------------------
+
+    def intelligence(self, cve_id: str) -> Dict[str, Any]:
+        """``GET /api/v1/cve/{id}/intelligence``: affected products, CWE mappings, remediation (Pro+)."""
+        return self._call("GET", f"/api/v1/cve/{normalise_cve_id(cve_id)}/intelligence")
+
+    def patches(self, cve_id: str) -> Dict[str, Any]:
+        """``GET /api/v1/patches/{id}``: fix commits and patched files (Business and Enterprise)."""
+        return self._call("GET", f"/api/v1/patches/{normalise_cve_id(cve_id)}")
+
+    # -- no key needed (limited per IP) ----------------------------------------------------
+
+    def public_cve(self, cve_id: str) -> Dict[str, Any]:
+        """``GET /api/v1/public/cve/{id}``: one public CVE record, no key needed."""
+        return self._call("GET", f"/api/v1/public/cve/{normalise_cve_id(cve_id)}", auth=False)
+
+    def kev(self, *, limit: Optional[int] = None, offset: Optional[int] = None) -> Dict[str, Any]:
+        """``GET /api/v1/kev``: the CISA KEV catalogue ranked by RPS. Cached an hour; fetch at most hourly."""
+        return self._call("GET", "/api/v1/kev", params={"limit": limit, "offset": offset}, auth=False)
+
+    def stats(self) -> Dict[str, Any]:
+        """``GET /api/v1/stats``: corpus totals."""
+        return self._call("GET", "/api/v1/stats", auth=False)
+
+    def status(self) -> Dict[str, Any]:
+        """``GET /api/v1/status``: data freshness (``data_freshness.last_data_refresh_utc``)."""
+        return self._call("GET", "/api/v1/status", auth=False)
+
+    def health(self) -> Dict[str, Any]:
+        """``GET /api/v1/health``: liveness and the API release."""
+        return self._call("GET", "/api/v1/health", auth=False)
+
+
+def _plan_limit(e: DevSecureError) -> Optional[int]:
+    """The per-call maximum from a ``list_too_long`` error ("Maximum 25 CVEs per request ...")."""
+    if e.code != "list_too_long":
+        return None
+    m = re.search(r"Maximum (\d+)", e.message)
+    return int(m.group(1)) if m and int(m.group(1)) > 0 else None
+
+
+def _merge_prioritize(parts: List[PrioritizeResult]) -> PrioritizeResult:
+    """One Prioritize result from several calls: found CVEs re-ranked in the API's order, then the
+    not-found ones (band ``unknown``), with ``rank_in_request`` renumbered across the whole list."""
+    found: List[RankedCve] = []
+    unknown: List[RankedCve] = []
+    not_found: List[str] = []
+    as_of: List[str] = []
+    for part in parts:
+        for item in part.get("ranked") or []:
+            (unknown if item.get("priority_band") == "unknown" else found).append(dict(item))  # type: ignore[arg-type]
+        not_found.extend(part.get("not_found") or [])
+        if part.get("data_as_of"):
+            as_of.append(str(part["data_as_of"]))
+    found.sort(key=rank_key)
+    ranked = found + unknown
+    for i, item in enumerate(ranked, 1):
+        item["rank_in_request"] = i
+    return {
+        "total": sum(int(p.get("total") or 0) for p in parts),
+        "found": sum(int(p.get("found") or 0) for p in parts),
+        "not_found": not_found,
+        "ranked": ranked,
+        # The oldest build any part came from: the merged answer is only as current as that.
+        "data_as_of": min(as_of) if as_of else None,
+        "status": "success",
+    }

devsecure_intelligence/errors.py

@@ -0,0 +1,71 @@
+"""Errors raised by the client. Every API error has one shape:
+``{"error": {"code", "message", "status", "request_id", "docs_url"}}``; branch on ``code``."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class DevSecureError(Exception):
+    """An error from the API, or a network failure reaching it.
+
+    ``code`` is the API's machine-readable code (``unauthorized``, ``forbidden_plan``,
+    ``not_found``, ``rate_limited``, ``quota_exceeded``, ...), or ``timeout`` /
+    ``network_error`` when no response arrived.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        *,
+        docs_url: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.docs_url = docs_url
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        extra = f" (request_id {self.request_id})" if self.request_id else ""
+        return f"{self.status} {self.code}: {self.message}{extra}"
+
+
+class AuthenticationError(DevSecureError):
+    """401: missing, invalid or revoked API key."""
+
+
+class PlanError(DevSecureError):
+    """403 ``forbidden_plan``: the key's plan doesn't include this endpoint."""
+
+
+class NotFoundError(DevSecureError):
+    """404: the CVE (or other resource) isn't in the corpus."""
+
+
+class RateLimitError(DevSecureError):
+    """429 ``rate_limited``: too many requests this minute. ``retry_after`` is in seconds."""
+
+
+class QuotaExceededError(DevSecureError):
+    """429 ``quota_exceeded``: the month's allowance is used. Retrying won't help until the 1st (UTC)."""
+
+
+def error_for(status: int, code: str) -> type:
+    if status == 401:
+        return AuthenticationError
+    if code == "forbidden_plan":
+        return PlanError
+    if status == 404:
+        return NotFoundError
+    if code == "quota_exceeded":
+        return QuotaExceededError
+    if status == 429:
+        return RateLimitError
+    return DevSecureError

devsecure_intelligence/models.py

@@ -0,0 +1,64 @@
+"""Typed shapes for the most used responses (from ``/docs/openapi.yaml``). The API adds fields
+within v1 without notice, so these are ``total=False`` and responses keep any extra keys."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+PriorityBand = Literal["critical_priority", "high_priority", "medium_priority", "low_priority", "informational", "unknown"]
+BandBasis = Literal["rps", "kev_floor", "epss_gate"]
+MoverType = Literal["priority_change", "kev_added", "metasploit_module", "exploitdb_added", "fix_found", "epss_jump"]
+
+#: Most urgent first; the order the API ranks by (band, then RPS score within a band).
+BAND_ORDER: List[str] = ["critical_priority", "high_priority", "medium_priority", "low_priority", "informational"]
+
+
+class RankedCve(TypedDict, total=False):
+    """One CVE in a Prioritize response. ``priority_band`` is the Final Priority (after the
+    CISA KEV floor and the EPSS gate); ``band_basis`` says which rule set it."""
+
+    cve_id: str
+    rps_score: float
+    priority_band: PriorityBand
+    band_basis: BandBasis
+    rank_in_request: int
+    confidence: str
+    evidence: Dict[str, Any]
+    data_quality: Dict[str, Any]
+    reason: str
+    sla_guidance: str
+    recommended_next_step: str
+    scored_at: Optional[str]
+    last_modified: Optional[str]
+
+
+class PrioritizeResult(TypedDict, total=False):
+    total: int
+    found: int
+    not_found: List[str]
+    ranked: List[RankedCve]
+    data_as_of: Optional[str]
+    status: str
+
+
+class Mover(TypedDict, total=False):
+    cve_id: str
+    type: MoverType
+    occurred_on: str
+    priority_before: str
+    priority_after: str
+    priority_now: Optional[str]
+    direction: Literal["up", "down"]
+    reason: str
+    epss_percentile: Dict[str, float]
+    actionable: bool
+
+
+class Quota(TypedDict, total=False):
+    """From the last response's headers; a key absent from the response is absent here."""
+
+    rate_limit: int
+    rate_limit_remaining: int
+    rate_limit_reset: int
+    quota_limit: int
+    quota_remaining: int

devsecure_intelligence-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: devsecure-intelligence
+Version: 0.1.0
+Summary: Python client for the DevSecure Intelligence API: rank CVEs by real-world risk (RPS from CVSS, EPSS and CISA KEV), with the reason for every rank.
+Project-URL: Homepage, https://intelligence.devsecure.io
+Project-URL: Documentation, https://intelligence.devsecure.io/docs/guides/python
+Author: DevSecure Limited
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cisa-kev,cve,cvss,epss,prioritisation,sbom,security,vulnerability
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# DevSecure Intelligence for Python
+
+Rank CVEs by real-world risk from Python. Each CVE gets an RPS score (from CVSS, EPSS and CISA KEV), a Final Priority, and the reason for its rank. Exploit and fix evidence come with it.
+
+- Standard library only: no dependencies.
+- Typed (`py.typed`), Python 3.10+.
+- Retries network errors, 5xx and `429 rate_limited`, honouring `Retry-After`. It never retries `quota_exceeded`.
+- Accepts a list of IDs or a whole scanner report, splits long lists to fit your plan, and merges the results into one ranking.
+
+```bash
+pip install devsecure-intelligence
+export DEVSECURE_API_KEY=dsec_live_...   # free key: https://intelligence.devsecure.io/signup
+```
+
+## Rank a scanner's findings
+
+```python
+from pathlib import Path
+from devsecure_intelligence import Client
+
+client = Client()  # reads DEVSECURE_API_KEY
+result = client.prioritize(Path("trivy.json").read_text())   # any text that mentions CVE IDs
+
+for cve in result["ranked"]:
+    print(cve["rank_in_request"], cve["cve_id"], cve["priority_band"], cve["rps_score"], cve["reason"])
+```
+
+`priority_band` is the **Final Priority**: the RPS band after the CISA KEV floor and the EPSS gate. `band_basis` says which rule set it (`rps`, `kev_floor` or `epss_gate`). CVEs not in the corpus come last with band `unknown` and are listed in `not_found`.
+
+Free keys take 25 IDs per call and Pro and above take 1,000. You can pass a longer list anyway: if the API rejects it as `list_too_long`, the client re-sends it in chunks of your plan's limit and merges them. The merged list uses the API's own order: band first, then RPS within a band. Pass `chunk_size=` to choose the size yourself.
+
+## Fail a CI step on High, Critical or KEV
+
+```python
+import sys
+blocking = [c for c in result["ranked"]
+            if c["priority_band"] in ("critical_priority", "high_priority") or (c.get("evidence") or {}).get("kev", {}).get("listed")]
+for c in blocking:
+    print(f"{c['cve_id']}\t{c['priority_band']}\t{c['reason']}")
+sys.exit(1 if blocking else 0)
+```
+
+Your organisation decides what blocks a build. For a ready-made GitHub Action with allowlists, VEX and a job summary, see the [CI gate](https://intelligence.devsecure.io/docs/guides/ci-gate).
+
+## Other calls
+
+| Method | Endpoint | Plan |
+|---|---|---|
+| `cve(id)`, `rps(id)` | `GET /api/v1/cve/{id}`, `/rps/{id}` | Any key |
+| `cve_batch(ids)` | `POST /api/v1/cve/batch` | Any key (Free 100 IDs, Pro+ 1,000) |
+| `prioritize(ids_or_text, chunk_size=None)` | `POST /api/v1/prioritize` | Any key |
+| `movers(window="7d", types=[...])`, `iter_movers(...)` | `GET /api/v1/movers` | Any key |
+| `recent(since=...)` | `GET /api/v1/cve/recent` | Any key |
+| `cwe_cves(79, is_kev=True)` | `GET /api/v1/cwe/{cwe}/cves` | Any key |
+| `intelligence(id)` | `GET /api/v1/cve/{id}/intelligence` | Pro and above |
+| `patches(id)` | `GET /api/v1/patches/{id}` | Business and Enterprise |
+| `public_cve(id)`, `kev()`, `stats()`, `status()`, `health()` | public endpoints | No key needed |
+| `request(method, path, params=..., json_body=...)` | anything else | |
+
+What changed in the last 24 hours:
+
+```python
+for m in client.iter_movers(window="24h", types=["kev_added", "priority_change"]):
+    print(m["occurred_on"], m["cve_id"], m["type"], m.get("priority_now"), m["reason"])
+```
+
+## Command line: `devsecure`
+
+Installing the package also installs a `devsecure` command:
+
+```bash
+devsecure cve CVE-2024-3400                        # no key needed: falls back to the public record
+devsecure prioritize trivy.json grype.json         # ranked table of every CVE found in the files
+trivy image -f json app:1.2 | devsecure prioritize - --fail-on high,kev
+devsecure movers --window 24h --type kev_added,priority_change
+devsecure kev --limit 10                           # CISA KEV ranked by RPS, no key needed
+devsecure --json prioritize sbom.cdx.json          # the API's JSON instead of a table
+```
+
+`--fail-on` takes `critical`, `high`, `medium` and/or `kev` (comma-separated). Exit codes: `0` done, `1` a CVE matched `--fail-on`, `2` a usage or API error, with the error's docs link printed. `python -m devsecure_intelligence` works too.
+
+## Errors, limits and quota
+
+Every error raises a `DevSecureError` carrying `status`, `code`, `message`, `docs_url`, `request_id` and `retry_after`. These subclasses let you catch the common cases:
+
+| Class | When |
+|---|---|
+| `AuthenticationError` | 401: missing, invalid or revoked key |
+| `PlanError` | 403 `forbidden_plan`: your plan doesn't include the endpoint |
+| `NotFoundError` | 404: the CVE isn't in the corpus |
+| `RateLimitError` | 429 `rate_limited`, after the retries are used up |
+| `QuotaExceededError` | 429 `quota_exceeded`: the month's allowance is used (resets on the 1st, UTC) |
+
+`client.last_quota` holds the rate-limit and quota headers from the last response, for example `{"quota_limit": 500, "quota_remaining": 412, "rate_limit_remaining": 19}`. `client.last_request_id` is the ID to quote to support.
+
+```python
+Client(api_key="...", base_url="https://api.intelligence.devsecure.io", timeout=30, max_retries=3)
+```
+
+The key is sent only in the `Authorization` header, and never appears in URLs or in `repr(client)`. `base_url` must be `https://`, except `http://localhost` for testing.
+
+## Development
+
+```bash
+cd sdk/python
+pip install pytest
+PYTHONPATH=src pytest            # unit tests, no network
+PYTHONPATH=src pytest -m live    # a few public calls to the production API, no key
+```
+
+Licence: MIT. API docs: <https://intelligence.devsecure.io/docs>. Support: support@devsecure.io.

devsecure_intelligence-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+devsecure_intelligence/__init__.py,sha256=JWVe_jFc6B4eUXPtl9pZw_FmPZ4TOjK0QtPZ3ORf60w,757
+devsecure_intelligence/__main__.py,sha256=iqL5sqaJteojUO-yluSE4moQ3YYJvhp0lJWkXincvCQ,32
+devsecure_intelligence/cli.py,sha256=IO9kuRqRF0pcauBgcfA8YdqQRiqB_Bv8rZSEfQCzzZw,9081
+devsecure_intelligence/client.py,sha256=wPydHjhN8IawWDABxjwK177QUi6WBkVTu9cN2hs1iE0,17260
+devsecure_intelligence/errors.py,sha256=11_SWmXgjUTPEg84Z6XbOVIe8up-max3g_1Ic2YANhM,2157
+devsecure_intelligence/models.py,sha256=XTpPinP5fqNU0ZtE_y7Juv9i6VoQG5LCUXr_K9fz5hE,2060
+devsecure_intelligence/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devsecure_intelligence-0.1.0.dist-info/METADATA,sha256=uJ9HlbToGHThplube3QcoM96Qg1gxG0_S2hnTqgvS2o,6394
+devsecure_intelligence-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+devsecure_intelligence-0.1.0.dist-info/entry_points.txt,sha256=1h7b2-m9Gz1NfoDHsSyQyEw0tt6Bjmz6nYKQ_O2dTHI,63
+devsecure_intelligence-0.1.0.dist-info/licenses/LICENSE,sha256=8mzQNvzrASI4xZEye2tmPKYpqYepAF9V-6gCmdHLbGs,1074
+devsecure_intelligence-0.1.0.dist-info/RECORD,,

devsecure_intelligence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devsecure_intelligence-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devsecure = devsecure_intelligence.cli:entry

devsecure_intelligence-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevSecure Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.