devsecure-intelligence 0.1.0__tar.gz

devsecure_intelligence-0.1.0/.gitignore

@@ -0,0 +1,100 @@
+# Local environment / secrets
+.env
+.env.*
+!.env.example
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+
+
+# Secret/config dumps
+secrets.json
+credentials.json
+service-account*.json
+*secret*
+*secrets*
+
+# Cloudflare local state / generated files
+.wrangler/
+.wrangler-tmp/
+
+# Claude / local AI agent state (keep automation files versioned)
+.claude/*
+!.claude/skills/
+!.claude/agents/
+!.claude/hooks/
+!.claude/settings.json
+.claude.local/
+*.local.md
+
+# VS / IDE local files
+.vs/
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.example.json
+
+# Test/build output
+dist/
+coverage/
+test-results/
+playwright-report/
+
+# Logs
+*.log
+logs/
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# IDE
+.vs/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node
+node_modules/
+
+# Prompts
+docs/prompts/
+docs/temp/
+.prompt-local*.md
+.prompt-scratch*.md
+.prompt*.md
+.*report.md
+.UPGRADE_PLAN.md
+.strategy.md
+.test-report01.md
+.deepseek.md
+.AGENTS.md
+
+# Session handoff / AI conversation artifacts (never ship to master)
+docs/SESSION_HANDOFF.md
+
+# Private keys and certificates
+*.pem
+*.key
+*.p12
+*.pfx
+*.crt
+*.csr
+
+
+# Python
+__pycache__/
+
+
+
+# Misc
+INDEX.md
+
+===============
+
+t e s t . p s 1 
+ 
+ 
+# Local PowerShell test scripts
+/test.ps1

devsecure_intelligence-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First release: `Client` for the v1 API (lookups, Prioritize with scanner-text input and plan-aware chunking, movers, recent, CWE search, enrichment, public endpoints), typed responses, retries with `Retry-After`, quota headers.
+- `devsecure` command: `cve`, `prioritize` (files or stdin, `--fail-on critical|high|medium|kev`), `movers`, `kev`; `--json`.

devsecure_intelligence-0.1.0/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.

devsecure_intelligence-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,111 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "devsecure-intelligence"
+dynamic = ["version"]
+description = "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."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+authors = [{ name = "DevSecure Limited" }]
+keywords = ["cve", "vulnerability", "epss", "cisa-kev", "cvss", "prioritisation", "security", "sbom"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+
+[project.scripts]
+devsecure = "devsecure_intelligence.cli:entry"
+
+[project.urls]
+Homepage = "https://intelligence.devsecure.io"
+# The Intelligence repository is private: no source/changelog links until a public repo exists.
+Documentation = "https://intelligence.devsecure.io/docs/guides/python"
+
+[tool.hatch.version]
+path = "src/devsecure_intelligence/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/devsecure_intelligence"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: calls the production API (no key needed); run with -m live"]
+addopts = "-m 'not live'"

devsecure_intelligence-0.1.0/src/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-0.1.0/src/devsecure_intelligence/__main__.py

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

devsecure_intelligence-0.1.0/src/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"]