opencra-cli 0.1.0__py3-none-any.whl

opencra_cli/__init__.py

@@ -0,0 +1,3 @@
+"""OpenCRA CLI — Syft wrapper, OSV + CISA KEV matching."""
+
+__version__ = "0.1.0"

opencra_cli/app.py

@@ -0,0 +1,257 @@
+"""OpenCRA Typer CLI."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+
+import typer
+from opencra_shared.models import FailOn, OutputFormat, ScanResult
+from rich.console import Console
+
+from opencra_cli import __version__
+from opencra_cli.db import Cache, default_db_path
+from opencra_cli.kev import KevError, load_index, refresh
+from opencra_cli.match import merge_matches
+from opencra_cli.nvd import cvss_from_nvd, enrich_cve
+from opencra_cli.osv import ping as osv_ping
+from opencra_cli.osv import query_batch
+from opencra_cli.pdf import PDF_HINT, export_report, weasyprint_status
+from opencra_cli.render import format_payload, print_table, result_to_json, write_output
+from opencra_cli.syft import SyftError, resolve_syft, scan_to_document, syft_version, version_ok
+from opencra_cli.sync import ingest
+
+app = typer.Typer(
+    name="opencra",
+    help="CRA Article 14 reporting readiness for your SBOM. A KEV hit is a candidate, not awareness.",
+    no_args_is_help=True,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+class FailOnOpt(str, Enum):
+    none = "none"
+    kev = "kev"
+    critical = "critical"
+    high = "high"
+
+
+class FormatOpt(str, Enum):
+    table = "table"
+    json = "json"
+    cyclonedx = "cyclonedx"
+    spdx = "spdx"
+
+
+class EnrichOpt(str, Enum):
+    none = "none"
+    nvd = "nvd"
+
+
+def _configure_logging(verbose: bool, quiet: bool) -> None:
+    level = logging.WARNING
+    if verbose:
+        level = logging.DEBUG
+    if quiet:
+        level = logging.ERROR
+    logging.basicConfig(level=level, format="%(levelname)s %(name)s: %(message)s")
+
+
+def _exit(code: int, message: str | None = None) -> None:
+    if message:
+        err_console.print(f"[red]{message}[/red]")
+    raise typer.Exit(code)
+
+
+def _run_scan(
+    target: str,
+    *,
+    offline: bool,
+    enrich: EnrichOpt,
+    syft_bin: str | None,
+    cache: Cache,
+) -> ScanResult:
+    document = scan_to_document(target, syft_bin=syft_bin)
+    skipped = [c for c in document.components if not c.purl]
+    valid_purls = sorted({c.purl for c in document.components if c.purl})
+    warnings: list[str] = []
+    if skipped:
+        warnings.append(
+            f"Skipped {len(skipped)} component(s) with invalid or missing PURLs "
+            "(they were not sent to OSV)."
+        )
+
+    kev_index = load_index(cache, offline=offline)
+    osv_by_purl = query_batch(valid_purls, cache, offline=offline)
+    matches = merge_matches(document.components, osv_by_purl, kev_index)
+
+    if enrich is EnrichOpt.nvd and not offline:
+        for match in matches:
+            if match.cve_id and match.cvss_v3 is None:
+                payload = enrich_cve(match.cve_id)
+                if payload:
+                    match.cvss_v3 = cvss_from_nvd(payload)
+
+    return ScanResult(
+        target=target,
+        scanned_at=datetime.now(timezone.utc),
+        sbom=document,
+        matches=matches,
+        skipped_components=skipped,
+        offline=offline,
+        warnings=warnings,
+    )
+
+
+@app.command()
+def scan(
+    target: str = typer.Argument(
+        ".", help="Path, image, Syft target, or CycloneDX JSON file."
+    ),
+    format: FormatOpt = typer.Option(FormatOpt.table, "--format", help="Output format."),
+    output: Path | None = typer.Option(None, "--output", help="Write formatted output to PATH."),
+    export_pdf: Path | None = typer.Option(
+        None, "--export-pdf", help="Write a community PDF (falls back to HTML/Markdown)."
+    ),
+    fail_on: FailOnOpt = typer.Option(
+        FailOnOpt.kev, "--fail-on", help="Exit 1 when threshold is met. Default: kev."
+    ),
+    offline: bool = typer.Option(False, "--offline", help="Use SQLite caches only. No network."),
+    enrich: EnrichOpt = typer.Option(EnrichOpt.none, "--enrich"),
+    sync_cloud: bool = typer.Option(False, "--sync-cloud", help="POST results to CRA-Shield."),
+    syft_bin: str | None = typer.Option(None, "--syft-bin", help="Path to the Syft binary."),
+    quiet: bool = typer.Option(False, "--quiet"),
+    verbose: bool = typer.Option(False, "--verbose"),
+) -> None:
+    """Generate or ingest an SBOM and match components against OSV + CISA KEV."""
+    _configure_logging(verbose, quiet)
+    try:
+        with Cache() as cache:
+            result = _run_scan(
+                target,
+                offline=offline,
+                enrich=enrich,
+                syft_bin=syft_bin,
+                cache=cache,
+            )
+            cache.save_scan(target, result_to_json(result), result.sbom.model_dump(mode="json"))
+    except SyftError as exc:
+        _exit(exc.exit_code, str(exc))
+    except KevError as exc:
+        _exit(2, str(exc))
+
+    fmt = OutputFormat(format.value)
+    if fmt is OutputFormat.TABLE and not quiet:
+        print_table(result, console)
+    elif fmt is not OutputFormat.TABLE:
+        payload = format_payload(result, fmt)
+        if output:
+            write_output(result, fmt, output)
+            if not quiet:
+                console.print(f"Wrote {fmt.value} to {output}")
+        else:
+            console.print(payload)
+    elif output:
+        write_output(result, OutputFormat.JSON, output)
+
+    if export_pdf:
+        written = export_report(result, export_pdf)
+        if not quiet:
+            if written.suffix == ".pdf":
+                console.print(f"Wrote PDF to {written}")
+            else:
+                console.print(
+                    f"[yellow]PDF engine unavailable.[/yellow] Wrote {written} instead.\n{PDF_HINT}"
+                )
+
+    if sync_cloud:
+        response = ingest(result)
+        if not quiet:
+            console.print(response.get("message") or response)
+
+    threshold = FailOn(fail_on.value)
+    if result.fails(threshold):
+        _exit(1, f"Scan failed --fail-on {threshold.value}.")
+
+
+@app.command()
+def doctor(
+    syft_bin: str | None = typer.Option(None, "--syft-bin"),
+) -> None:
+    """Check Syft, network, cache, and PDF engine. Friendly, not a stack trace."""
+    console.print(f"[bold]OpenCRA[/bold] {__version__}")
+    try:
+        path = resolve_syft(syft_bin)
+        label, parsed = syft_version(syft_bin)
+        ok = version_ok(parsed)
+        status = "[green]ok[/green]" if ok else "[yellow]old[/yellow]"
+        console.print(f"Syft: {status} {path} ({label})")
+        if not ok:
+            console.print("  Install Syft >= 1.0.0 for CycloneDX 1.6 output.")
+    except SyftError as exc:
+        console.print(f"Syft: [red]missing[/red]\n{exc}")
+
+    cache_path = default_db_path()
+    console.print(f"Cache: {cache_path} ({'exists' if cache_path.exists() else 'will be created'})")
+    with Cache() as cache:
+        fetched = cache.get_kev_fetched_at()
+        console.print(f"KEV cache: {fetched.isoformat() if fetched else 'empty'}")
+
+    console.print(f"OSV: {'reachable' if osv_ping() else 'unreachable (offline scans still work)'}")
+    pdf_ok, pdf_reason = weasyprint_status()
+    console.print(f"PDF engine: {'ok' if pdf_ok else 'fallback'} — {pdf_reason}")
+    console.print(
+        "[dim]A KEV match is a CRA candidate. Clocks start only after human awareness.[/dim]"
+    )
+
+
+@app.command("kev")
+def kev_cmd(
+    action: str = typer.Argument("refresh", help="Only 'refresh' is supported."),
+) -> None:
+    """Download or refresh the CISA KEV catalog into the local cache."""
+    if action != "refresh":
+        _exit(2, "Usage: opencra kev refresh")
+    try:
+        with Cache() as cache:
+            count, fetched = refresh(cache)
+    except KevError as exc:
+        _exit(2, str(exc))
+    console.print(f"Cached {count} CISA KEV entries ({fetched.isoformat()}).")
+
+
+@app.command()
+def report(
+    last: bool = typer.Option(False, "--last", help="Re-render the most recent local scan."),
+    export_pdf: Path | None = typer.Option(None, "--export-pdf"),
+    format: FormatOpt = typer.Option(FormatOpt.table, "--format"),
+) -> None:
+    """Show the last cached scan without invoking Syft."""
+    if not last:
+        _exit(2, "Pass --last to print the most recent scan.")
+    with Cache() as cache:
+        raw = cache.last_scan()
+    if raw is None:
+        _exit(2, "No cached scans. Run `opencra scan .` first.")
+    result = ScanResult.model_validate(raw)
+    fmt = OutputFormat(format.value)
+    if fmt is OutputFormat.TABLE:
+        print_table(result, console)
+    else:
+        console.print(format_payload(result, fmt))
+    if export_pdf:
+        written = export_report(result, export_pdf)
+        console.print(f"Wrote report to {written}")
+
+
+@app.callback()
+def main() -> None:
+    """OpenCRA CLI."""
+    return
+
+
+if __name__ == "__main__":
+    app()

opencra_cli/db.py

@@ -0,0 +1,176 @@
+"""Local SQLite cache at ~/.opencra/cache.db with WAL mode."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+OSV_TTL = timedelta(hours=12)
+
+
+def default_db_path() -> Path:
+    override = os.environ.get("OPENCRA_CACHE")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".opencra" / "cache.db"
+
+
+class Cache:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_db_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(self.path)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.execute("PRAGMA journal_mode=WAL;")
+        self.conn.execute("PRAGMA foreign_keys=ON;")
+        self._init()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def __enter__(self) -> Cache:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _init(self) -> None:
+        self.conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS kev_meta (
+                id INTEGER PRIMARY KEY CHECK (id = 1),
+                fetched_at TEXT NOT NULL,
+                catalog_json TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS osv_cache (
+                purl TEXT PRIMARY KEY,
+                fetched_at TEXT NOT NULL,
+                vulns_json TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS scans (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                target TEXT NOT NULL,
+                scanned_at TEXT NOT NULL,
+                serial_number TEXT,
+                sbom_json TEXT NOT NULL,
+                result_json TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS components (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                scan_id INTEGER NOT NULL,
+                purl TEXT,
+                name TEXT NOT NULL,
+                version TEXT,
+                FOREIGN KEY (scan_id) REFERENCES scans(id)
+            );
+            CREATE TABLE IF NOT EXISTS matches (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                scan_id INTEGER NOT NULL,
+                purl TEXT NOT NULL,
+                osv_id TEXT,
+                cve_id TEXT,
+                severity TEXT,
+                in_kev INTEGER NOT NULL DEFAULT 0,
+                summary TEXT,
+                FOREIGN KEY (scan_id) REFERENCES scans(id)
+            );
+            """
+        )
+        self.conn.commit()
+
+    def get_kev_catalog(self) -> dict[str, Any] | None:
+        row = self.conn.execute("SELECT catalog_json FROM kev_meta WHERE id = 1").fetchone()
+        if not row:
+            return None
+        return json.loads(row["catalog_json"])
+
+    def get_kev_fetched_at(self) -> datetime | None:
+        row = self.conn.execute("SELECT fetched_at FROM kev_meta WHERE id = 1").fetchone()
+        if not row:
+            return None
+        return datetime.fromisoformat(row["fetched_at"])
+
+    def save_kev_catalog(self, payload: dict[str, Any]) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        self.conn.execute(
+            """
+            INSERT INTO kev_meta (id, fetched_at, catalog_json)
+            VALUES (1, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET fetched_at = excluded.fetched_at,
+                                          catalog_json = excluded.catalog_json
+            """,
+            (now, json.dumps(payload)),
+        )
+        self.conn.commit()
+
+    def get_osv(self, purl: str) -> list[dict[str, Any]] | None:
+        row = self.conn.execute(
+            "SELECT fetched_at, vulns_json FROM osv_cache WHERE purl = ?",
+            (purl,),
+        ).fetchone()
+        if not row:
+            return None
+        fetched = datetime.fromisoformat(row["fetched_at"])
+        if datetime.now(timezone.utc) - fetched > OSV_TTL:
+            return None
+        return json.loads(row["vulns_json"])
+
+    def save_osv(self, purl: str, vulns: list[dict[str, Any]]) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        self.conn.execute(
+            """
+            INSERT INTO osv_cache (purl, fetched_at, vulns_json)
+            VALUES (?, ?, ?)
+            ON CONFLICT(purl) DO UPDATE SET fetched_at = excluded.fetched_at,
+                                            vulns_json = excluded.vulns_json
+            """,
+            (purl, now, json.dumps(vulns)),
+        )
+        self.conn.commit()
+
+    def save_scan(self, target: str, result_json: dict[str, Any], sbom_json: dict[str, Any]) -> int:
+        scanned_at = result_json.get("scanned_at") or datetime.now(timezone.utc).isoformat()
+        serial = (result_json.get("sbom") or {}).get("serial_number")
+        cur = self.conn.execute(
+            """
+            INSERT INTO scans (target, scanned_at, serial_number, sbom_json, result_json)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (target, scanned_at, serial, json.dumps(sbom_json), json.dumps(result_json)),
+        )
+        scan_id = int(cur.lastrowid or 0)
+        for component in (result_json.get("sbom") or {}).get("components") or []:
+            self.conn.execute(
+                "INSERT INTO components (scan_id, purl, name, version) VALUES (?, ?, ?, ?)",
+                (scan_id, component.get("purl"), component.get("name"), component.get("version")),
+            )
+        for match in result_json.get("matches") or []:
+            self.conn.execute(
+                """
+                INSERT INTO matches (scan_id, purl, osv_id, cve_id, severity, in_kev, summary)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    scan_id,
+                    match.get("purl"),
+                    match.get("osv_id"),
+                    match.get("cve_id"),
+                    match.get("severity"),
+                    1 if match.get("in_kev") else 0,
+                    match.get("summary"),
+                ),
+            )
+        self.conn.commit()
+        return scan_id
+
+    def last_scan(self) -> dict[str, Any] | None:
+        row = self.conn.execute(
+            "SELECT result_json FROM scans ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+        if not row:
+            return None
+        return json.loads(row["result_json"])

opencra_cli/httputil.py

@@ -0,0 +1,18 @@
+"""Shared HTTP defaults: User-Agent and a hard 10s timeout."""
+
+from __future__ import annotations
+
+import httpx
+
+from opencra_cli import __version__
+
+USER_AGENT = f"opencra/{__version__}"
+HTTP_TIMEOUT = 10.0
+
+
+def client(**kwargs: object) -> httpx.Client:
+    headers = {"User-Agent": USER_AGENT}
+    extra = kwargs.pop("headers", None)
+    if isinstance(extra, dict):
+        headers.update(extra)
+    return httpx.Client(timeout=HTTP_TIMEOUT, headers=headers, follow_redirects=True, **kwargs)  # type: ignore[arg-type]

opencra_cli/kev.py

@@ -0,0 +1,78 @@
+"""CISA KEV catalog download and local index."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import httpx
+from opencra_shared.kev import KevEntry, index_kev_by_cve, parse_kev_catalog
+
+from opencra_cli.db import Cache
+from opencra_cli.httputil import client
+
+logger = logging.getLogger("opencra.kev")
+
+KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
+KEV_FALLBACK_URL = (
+    "https://raw.githubusercontent.com/cisagov/known-exploited-vulnerabilities-data/"
+    "main/known_exploited_vulnerabilities.json"
+)
+KEV_SOURCES = (KEV_URL, KEV_FALLBACK_URL)
+KEV_TTL = timedelta(hours=24)
+
+
+class KevError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+def _fetch_kev_payload(http: httpx.Client, url: str) -> dict[str, Any]:
+    response = http.get(url)
+    response.raise_for_status()
+    payload = response.json()
+    if not isinstance(payload, dict) or "vulnerabilities" not in payload:
+        raise KevError("KEV catalog JSON is missing a vulnerabilities array.")
+    return payload
+
+
+def refresh(cache: Cache) -> tuple[int, datetime]:
+    last_error: Exception | None = None
+    payload: dict[str, Any] | None = None
+    with client() as http:
+        for url in KEV_SOURCES:
+            try:
+                payload = _fetch_kev_payload(http, url)
+                logger.info("Downloaded CISA KEV catalog from %s", url)
+                break
+            except (httpx.HTTPError, ValueError, KevError) as exc:
+                last_error = exc
+                logger.warning("KEV download failed from %s: %s", url, exc)
+    if payload is None:
+        raise KevError(f"Failed to download CISA KEV catalog: {last_error}") from last_error
+    cache.save_kev_catalog(payload)
+    entries = parse_kev_catalog(payload)
+    fetched = cache.get_kev_fetched_at() or datetime.now(timezone.utc)
+    return len(entries), fetched
+
+
+def load_index(cache: Cache, *, offline: bool = False, force_refresh: bool = False) -> dict[str, KevEntry]:
+    fetched = cache.get_kev_fetched_at()
+    stale = fetched is None or datetime.now(timezone.utc) - fetched > KEV_TTL
+    if (stale or force_refresh) and not offline:
+        try:
+            refresh(cache)
+        except KevError as exc:
+            if cache.get_kev_catalog() is None:
+                raise
+            logger.warning("KEV refresh failed, using cached catalog: %s", exc)
+    payload = cache.get_kev_catalog()
+    if payload is None:
+        if offline:
+            raise KevError(
+                "No cached CISA KEV catalog. Re-run without --offline after "
+                "`opencra kev refresh` while online."
+            )
+        raise KevError("CISA KEV catalog is unavailable.")
+    return index_kev_by_cve(parse_kev_catalog(payload))

opencra_cli/match.py

@@ -0,0 +1,88 @@
+"""Merge OSV results with the CISA KEV index into VulnMatch rows."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opencra_shared.kev import KevEntry, extract_cves
+from opencra_shared.models import Component, VulnMatch
+
+
+def _severity(vuln: dict[str, Any]) -> tuple[str | None, float | None]:
+    severity = None
+    score = None
+    for item in vuln.get("severity") or []:
+        if not isinstance(item, dict):
+            continue
+        typ = str(item.get("type") or "").upper()
+        raw = item.get("score")
+        if typ.startswith("CVSS") and raw is not None:
+            try:
+                # CVSS vector or numeric
+                if isinstance(raw, int | float):
+                    score = float(raw)
+                else:
+                    text = str(raw)
+                    if text.replace(".", "", 1).isdigit():
+                        score = float(text)
+            except ValueError:
+                pass
+    db = vuln.get("database_specific") or {}
+    sev = db.get("severity")
+    if isinstance(sev, str):
+        severity = sev.upper()
+    if score is not None and severity is None:
+        if score >= 9.0:
+            severity = "CRITICAL"
+        elif score >= 7.0:
+            severity = "HIGH"
+        elif score >= 4.0:
+            severity = "MEDIUM"
+        else:
+            severity = "LOW"
+    return severity, score
+
+
+def merge_matches(
+    components: list[Component],
+    osv_by_purl: dict[str, list[dict[str, Any]]],
+    kev_index: dict[str, KevEntry],
+) -> list[VulnMatch]:
+    matches: list[VulnMatch] = []
+    seen: set[tuple[str, str]] = set()
+    for component in components:
+        if not component.purl:
+            continue
+        for vuln in osv_by_purl.get(component.purl, []):
+            osv_id = str(vuln.get("id") or "")
+            aliases = [str(a) for a in (vuln.get("aliases") or [])]
+            cves = extract_cves(aliases, osv_id)
+            cve_id = cves[0] if cves else None
+            key = (component.purl, osv_id or cve_id or "")
+            if key in seen:
+                continue
+            seen.add(key)
+            kev = None
+            for cve in cves:
+                if cve in kev_index:
+                    kev = kev_index[cve]
+                    cve_id = cve
+                    break
+            severity, score = _severity(vuln)
+            matches.append(
+                VulnMatch(
+                    purl=component.purl,
+                    component_name=component.name,
+                    component_version=component.version,
+                    osv_id=osv_id or None,
+                    cve_id=cve_id,
+                    severity=severity,
+                    cvss_v3=score,
+                    in_kev=kev is not None,
+                    kev_added_at=kev.date_added if kev else None,
+                    kev_ransomware=kev.known_ransomware if kev else None,
+                    aliases=aliases,
+                    summary=vuln.get("summary"),
+                )
+            )
+    return matches

opencra_cli/nvd.py

@@ -0,0 +1,43 @@
+"""Optional NVD 2.0 enrichment. Off by default to avoid rate limits."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from opencra_cli.httputil import client
+
+logger = logging.getLogger("opencra.nvd")
+
+NVD_URL = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+
+
+def enrich_cve(cve_id: str) -> dict[str, Any] | None:
+    headers: dict[str, str] = {}
+    api_key = os.environ.get("NVD_API_KEY")
+    if api_key:
+        headers["apiKey"] = api_key
+    try:
+        with client(headers=headers) as http:
+            response = http.get(NVD_URL, params={"cveId": cve_id})
+            response.raise_for_status()
+            return response.json()
+    except httpx.HTTPError as exc:
+        logger.warning("NVD lookup failed for %s: %s", cve_id, exc)
+        return None
+
+
+def cvss_from_nvd(payload: dict[str, Any]) -> float | None:
+    try:
+        vuln = payload["vulnerabilities"][0]["cve"]
+        metrics = vuln.get("metrics") or {}
+        for key in ("cvssMetricV31", "cvssMetricV30", "cvssMetricV2"):
+            items = metrics.get(key)
+            if items:
+                return float(items[0]["cvssData"]["baseScore"])
+    except (KeyError, IndexError, TypeError, ValueError):
+        return None
+    return None

opencra_cli/osv.py

@@ -0,0 +1,79 @@
+"""OSV Query Batch client with 100-item chunks and SQLite cache."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from opencra_cli.db import Cache
+from opencra_cli.httputil import USER_AGENT, client
+
+logger = logging.getLogger("opencra.osv")
+
+OSV_QUERYBATCH = "https://api.osv.dev/v1/querybatch"
+BATCH_SIZE = 100
+
+
+def _chunks(items: list[str], size: int) -> list[list[str]]:
+    return [items[i : i + size] for i in range(0, len(items), size)]
+
+
+def query_batch(
+    purls: list[str],
+    cache: Cache,
+    *,
+    offline: bool = False,
+) -> dict[str, list[dict[str, Any]]]:
+    """Return {purl: [osv vuln dicts]} for validated PURLs only."""
+    results: dict[str, list[dict[str, Any]]] = {}
+    missing: list[str] = []
+    for purl in purls:
+        cached = cache.get_osv(purl)
+        if cached is not None:
+            results[purl] = cached
+        else:
+            missing.append(purl)
+
+    if not missing:
+        return results
+    if offline:
+        logger.warning("Offline mode: %s PURLs have no cached OSV data", len(missing))
+        for purl in missing:
+            results[purl] = []
+        return results
+
+    for chunk in _chunks(missing, BATCH_SIZE):
+        payload = {"queries": [{"package": {"purl": purl}} for purl in chunk]}
+        try:
+            with client() as http:
+                response = http.post(OSV_QUERYBATCH, json=payload)
+                response.raise_for_status()
+                body = response.json()
+        except httpx.HTTPError as exc:
+            logger.warning("OSV querybatch failed for %s items: %s", len(chunk), exc)
+            for purl in chunk:
+                results.setdefault(purl, [])
+            continue
+
+        results_list = body.get("results") or []
+        for purl, item in zip(chunk, results_list, strict=False):
+            vulns = item.get("vulns") or [] if isinstance(item, dict) else []
+            cache.save_osv(purl, vulns)
+            results[purl] = vulns
+        # If OSV returned fewer results than queries, mark leftovers empty.
+        if len(results_list) < len(chunk):
+            for purl in chunk[len(results_list) :]:
+                cache.save_osv(purl, [])
+                results[purl] = []
+    return results
+
+
+def ping() -> bool:
+    try:
+        with client() as http:
+            response = http.get("https://api.osv.dev/v1/querybatch", headers={"User-Agent": USER_AGENT})
+            return response.status_code in {200, 405, 415}
+    except httpx.HTTPError:
+        return False

opencra_cli/pdf.py

@@ -0,0 +1,125 @@
+"""Community PDF export with WeasyPrint, falling back to HTML/Markdown."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Template
+from opencra_shared.models import ScanResult
+
+from opencra_cli.render import DISCLAIMER
+
+_HTML_TEMPLATE = Template(
+    """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <title>OpenCRA scan report</title>
+  <style>
+    body { font-family: Helvetica, Arial, sans-serif; margin: 32px; color: #111; }
+    h1 { font-size: 20px; }
+    .disclaimer { background: #fff6e5; border: 1px solid #e6c36a; padding: 12px; }
+    table { border-collapse: collapse; width: 100%; margin-top: 16px; font-size: 12px; }
+    th, td { border: 1px solid #ccc; padding: 6px 8px; text-align: left; }
+    th { background: #f4f4f4; }
+    .kev { color: #b00020; font-weight: bold; }
+  </style>
+</head>
+<body>
+  <h1>OpenCRA community scan report</h1>
+  <p>Target: {{ result.target }}<br/>Scanned: {{ result.scanned_at }}</p>
+  <p class="disclaimer">{{ disclaimer }}</p>
+  <p>Components: {{ result.sbom.components|length }} ·
+     Matches: {{ result.matches|length }} ·
+     KEV hits: {{ result.kev_hits|length }}</p>
+  <table>
+    <thead>
+      <tr><th>Package</th><th>Version</th><th>ID</th><th>Severity</th><th>KEV</th></tr>
+    </thead>
+    <tbody>
+    {% for m in result.matches %}
+      <tr>
+        <td>{{ m.component_name or m.purl }}</td>
+        <td>{{ m.component_version or "" }}</td>
+        <td>{{ m.cve_id or m.osv_id or "" }}</td>
+        <td>{{ m.severity or "" }}</td>
+        <td class="{{ 'kev' if m.in_kev else '' }}">{{ "KEV" if m.in_kev else "" }}</td>
+      </tr>
+    {% endfor %}
+    </tbody>
+  </table>
+</body>
+</html>
+""".strip()
+)
+
+PDF_HINT = (
+    "WeasyPrint needs Cairo and Pango. Install them, or use the HTML/Markdown fallback:\n"
+    "  macOS:  brew install cairo pango\n"
+    "  Debian: sudo apt install libcairo2 libpango-1.0-0 libgdk-pixbuf-2.0-0 "
+    "libffi-dev shared-mime-info"
+)
+
+
+def weasyprint_status() -> tuple[bool, str]:
+    try:
+        import weasyprint  # noqa: F401
+    except ImportError:
+        return False, "weasyprint is not installed (pip install 'opencra-cli[pdf]')"
+    try:
+        from weasyprint import HTML  # noqa: F401
+    except Exception as exc:  # native cairo/pango missing
+        return False, f"WeasyPrint native libraries missing: {exc}\n{PDF_HINT}"
+    return True, "WeasyPrint available"
+
+
+def render_html(result: ScanResult) -> str:
+    return _HTML_TEMPLATE.render(result=result, disclaimer=DISCLAIMER)
+
+
+def render_markdown(result: ScanResult) -> str:
+    lines = [
+        "# OpenCRA community scan report",
+        "",
+        f"Target: `{result.target}`",
+        f"Scanned: {result.scanned_at}",
+        "",
+        f"> {DISCLAIMER}",
+        "",
+        f"Components: {len(result.sbom.components)} · "
+        f"Matches: {len(result.matches)} · KEV hits: {len(result.kev_hits)}",
+        "",
+        "| Package | Version | ID | Severity | KEV |",
+        "|---|---|---|---|---|",
+    ]
+    for match in result.matches:
+        lines.append(
+            f"| {match.component_name or match.purl} | {match.component_version or ''} | "
+            f"{match.cve_id or match.osv_id or ''} | {match.severity or ''} | "
+            f"{'KEV' if match.in_kev else ''} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def export_report(result: ScanResult, path: Path) -> Path:
+    """Write PDF if possible; otherwise write HTML (and Markdown alongside)."""
+    html = render_html(result)
+    ok, reason = weasyprint_status()
+    suffix = path.suffix.lower()
+    if ok and suffix in {"", ".pdf"}:
+        from weasyprint import HTML
+
+        dest = path if suffix == ".pdf" else path.with_suffix(".pdf")
+        HTML(string=html).write_pdf(dest)
+        return dest
+
+    html_path = path.with_suffix(".html") if suffix == ".pdf" else path
+    if html_path.suffix.lower() != ".html":
+        html_path = path.with_suffix(".html")
+    html_path.write_text(html, encoding="utf-8")
+    md_path = html_path.with_suffix(".md")
+    md_path.write_text(render_markdown(result), encoding="utf-8")
+    # Surface the reason to the caller via a sidecar note.
+    html_path.with_suffix(".pdf-fallback.txt").write_text(reason + "\n", encoding="utf-8")
+    return html_path

opencra_cli/py.typed

@@ -0,0 +1 @@
+

opencra_cli/render.py

@@ -0,0 +1,87 @@
+"""Rich table and file exporters."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from opencra_shared.models import OutputFormat, ScanResult
+from opencra_shared.sbom import cyclonedx_to_spdx, serialize_cyclonedx
+from rich.console import Console
+from rich.table import Table
+
+DISCLAIMER = (
+    "OpenCRA prepares evidence. A KEV match is a CRA candidate, not legal awareness. "
+    "Article 14 clocks start only after a human assessment."
+)
+
+
+def result_to_json(result: ScanResult) -> dict:
+    return result.model_dump(mode="json")
+
+
+def format_payload(result: ScanResult, fmt: OutputFormat) -> str:
+    if fmt is OutputFormat.JSON:
+        return json.dumps(result_to_json(result), indent=2)
+    if fmt is OutputFormat.CYCLONEDX:
+        return json.dumps(serialize_cyclonedx(result.sbom), indent=2)
+    if fmt is OutputFormat.SPDX:
+        return json.dumps(cyclonedx_to_spdx(result.sbom), indent=2)
+    return ""
+
+
+def write_output(result: ScanResult, fmt: OutputFormat, path: Path) -> None:
+    path.write_text(format_payload(result, fmt), encoding="utf-8")
+
+
+def print_table(result: ScanResult, console: Console) -> None:
+    console.print(f"[bold]OpenCRA[/bold] scan of [cyan]{result.target}[/cyan]")
+    console.print(f"[dim]{DISCLAIMER}[/dim]")
+    if result.warnings:
+        for warning in result.warnings:
+            console.print(f"[yellow]warn[/yellow] {warning}")
+
+    kev_count = len(result.kev_hits)
+    console.print(
+        f"Components: {len(result.sbom.components)}  "
+        f"Matches: {len(result.matches)}  "
+        f"[red]KEV hits: {kev_count}[/red]"
+        if kev_count
+        else f"Components: {len(result.sbom.components)}  Matches: {len(result.matches)}  KEV hits: 0"
+    )
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Package")
+    table.add_column("Version")
+    table.add_column("ID")
+    table.add_column("Severity")
+    table.add_column("KEV")
+    table.add_column("Action")
+
+    rows = sorted(result.matches, key=lambda m: (not m.in_kev, m.severity or "ZZ", m.purl))
+    if not rows:
+        console.print("[green]No vulnerability matches.[/green]")
+        return
+
+    for match in rows:
+        kev = "[bold red]KEV[/bold red]" if match.in_kev else ""
+        action = (
+            "Candidate — assess awareness (do not auto-file)"
+            if match.in_kev
+            else "Triage"
+        )
+        ident = match.cve_id or match.osv_id or "—"
+        table.add_row(
+            match.component_name or match.purl,
+            match.component_version or "—",
+            ident,
+            match.severity or "—",
+            kev,
+            action,
+        )
+    console.print(table)
+    if kev_count:
+        console.print(
+            "[bold]KEV hits are CRA candidates.[/bold] "
+            "Acknowledge awareness in CRA-Shield to start the 24-hour clock."
+        )

opencra_cli/syft.py

@@ -0,0 +1,132 @@
+"""Safe Syft subprocess wrapper. Never uses shell=True."""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from opencra_shared.sbom import parse_cyclonedx
+
+logger = logging.getLogger("opencra.syft")
+
+MIN_SYFT_VERSION = (1, 0, 0)
+INSTALL_HINT = (
+    "Syft is required. Install it, then re-run:\n"
+    "  macOS:  brew install syft\n"
+    "  Linux:  curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh "
+    "| sh -s -- -b ~/.local/bin"
+)
+
+
+class SyftError(Exception):
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def resolve_syft(syft_bin: str | None = None) -> str:
+    if syft_bin:
+        path = Path(syft_bin).expanduser()
+        if path.is_file():
+            return str(path)
+        which = shutil.which(syft_bin)
+        if which:
+            return which
+        raise SyftError(f"Syft binary not found at {syft_bin}.\n{INSTALL_HINT}")
+    found = shutil.which("syft")
+    if not found:
+        raise SyftError(f"Syft is not on PATH.\n{INSTALL_HINT}")
+    return found
+
+
+def parse_syft_version(text: str) -> tuple[int, int, int] | None:
+    # Typical: "syft 1.18.1"
+    for token in text.replace(",", " ").split():
+        parts = token.strip().split(".")
+        if len(parts) >= 2 and parts[0].isdigit() and parts[1].isdigit():
+            patch = int(parts[2]) if len(parts) > 2 and parts[2].isdigit() else 0
+            return int(parts[0]), int(parts[1]), patch
+    return None
+
+
+def syft_version(syft_bin: str | None = None) -> tuple[str, tuple[int, int, int] | None]:
+    binary = resolve_syft(syft_bin)
+    result = subprocess.run(
+        [binary, "version"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    output = (result.stdout or "") + (result.stderr or "")
+    if result.returncode != 0:
+        # Older syft prints version via --version
+        result = subprocess.run(
+            [binary, "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        output = (result.stdout or "") + (result.stderr or "")
+    parsed = parse_syft_version(output)
+    return output.strip().splitlines()[0] if output.strip() else binary, parsed
+
+
+def version_ok(version: tuple[int, int, int] | None) -> bool:
+    if version is None:
+        return True
+    return version >= MIN_SYFT_VERSION
+
+
+def scan_target(target: str, *, syft_bin: str | None = None) -> dict[str, Any]:
+    binary = resolve_syft(syft_bin)
+    cmd = [binary, "scan", target, "-o", "cyclonedx-json"]
+    logger.debug("Running %s", cmd)
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or exc.stdout or "").strip()
+        raise SyftError(f"Syft failed on {target}: {stderr or exc}") from exc
+    except FileNotFoundError as exc:
+        raise SyftError(f"Syft is not on PATH.\n{INSTALL_HINT}") from exc
+
+    stdout = result.stdout.strip()
+    if not stdout:
+        raise SyftError("Syft produced empty CycloneDX output.")
+    try:
+        payload = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise SyftError(f"Syft output is not valid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise SyftError("Syft output is not a CycloneDX object.")
+    return payload
+
+
+def load_cyclonedx_file(path: Path) -> dict[str, Any] | None:
+    """Return a CycloneDX object if path is an existing CDX JSON file."""
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if str(payload.get("bomFormat") or "").lower() == "cyclonedx":
+        return payload
+    return None
+
+
+def scan_to_document(target: str, *, syft_bin: str | None = None):
+    payload = load_cyclonedx_file(Path(target).expanduser())
+    if payload is not None:
+        return parse_cyclonedx(payload)
+    return parse_cyclonedx(scan_target(target, syft_bin=syft_bin))

opencra_cli/sync.py

@@ -0,0 +1,46 @@
+"""Optional CRA-Shield cloud ingest. Never required for local scans."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from opencra_shared.models import ScanResult
+
+from opencra_cli.httputil import client
+
+DEFAULT_API = "https://api.crashield.dev"
+SIGNUP_URL = "https://crashield.dev/signup"
+
+
+def ingest(
+    result: ScanResult,
+    *,
+    api_url: str | None = None,
+    api_key: str | None = None,
+) -> dict[str, Any]:
+    key = api_key or os.environ.get("OPENCRA_API_KEY")
+    base = (api_url or os.environ.get("OPENCRA_API_URL") or DEFAULT_API).rstrip("/")
+    if not key:
+        return {
+            "ok": False,
+            "skipped": True,
+            "message": (
+                "No OPENCRA_API_KEY set. Local scan is complete. "
+                f"Create a CRA-Shield workspace at {SIGNUP_URL}"
+            ),
+            "signup_url": SIGNUP_URL,
+        }
+    payload = result.model_dump(mode="json")
+    try:
+        with client() as http:
+            response = http.post(
+                f"{base}/v1/ingest",
+                json=payload,
+                headers={"Authorization": f"Bearer {key}"},
+            )
+            response.raise_for_status()
+            return {"ok": True, "response": response.json()}
+    except httpx.HTTPError as exc:
+        return {"ok": False, "message": f"CRA-Shield ingest failed: {exc}"}

opencra_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: opencra-cli
+Version: 0.1.0
+Summary: OpenCRA command-line scanner — Syft wrapper, OSV + CISA KEV matching.
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: opencra-shared
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.15
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=63.0; extra == 'pdf'

opencra_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+opencra_cli/__init__.py,sha256=iKbZoSTYswhd1ABTIP9bn6E6kj2LgKr-lhgLqaJXD2M,84
+opencra_cli/app.py,sha256=6wiYso_vDoUn09HM-WnV69ihjEhqif_1lDmMIKZtcrw,8651
+opencra_cli/db.py,sha256=is9zjXxkteo25RjJftTKyGSG8cWyiUe0edG6FU4MIsQ,6406
+opencra_cli/httputil.py,sha256=PzADwxfk4QFcULncmbJx1-JKJN3n68C8RBChDzz0290,522
+opencra_cli/kev.py,sha256=lceyHlo3OY0127qQIzteDx9xbYJSKWMhaMfH_r1OJ5g,2861
+opencra_cli/match.py,sha256=228BK7uGJeMpAARE2m69SfghRWLScXMzteIiI29QC0I,3014
+opencra_cli/nvd.py,sha256=IzKRd6AC9kPr7I5EmAqaupDdbJxuFHhWh6b3wzi2ALY,1277
+opencra_cli/osv.py,sha256=iKXfPM2pmKmbjoUfERc2jgb4SxFLTqPS7TZg7Q5sCG0,2525
+opencra_cli/pdf.py,sha256=iHzzSeVSPLTKxnz-ZQYYLxJfR4C77-vEVVZypUualMc,4292
+opencra_cli/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+opencra_cli/render.py,sha256=ES6NmTz7VHmKYSvuCtWeQlg9bntO1Gz4YDNnuNiibs8,2892
+opencra_cli/syft.py,sha256=IuNMXDK_ozlw3QiNa1fz-B3rS2VOCSr-HVXcX-S190Y,4327
+opencra_cli/sync.py,sha256=DT5_ponrfKsPlS-25bQRTsUhsqdwHwSLJJqkuij-tg8,1378
+opencra_cli-0.1.0.dist-info/METADATA,sha256=CexHTYNopn9nV4IvS8SKaRukl57I9E68TMgsbye5pv4,385
+opencra_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+opencra_cli-0.1.0.dist-info/entry_points.txt,sha256=OxRu28JUVu-jbtrM8DL6FPQz-4iX1TNwo2OY60ttLW4,48
+opencra_cli-0.1.0.dist-info/RECORD,,

opencra_cli-0.1.0.dist-info/WHEEL

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

opencra_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencra = opencra_cli.app:app