quantbom 0.6.0__py3-none-any.whl

quantbom/_merge.py

@@ -0,0 +1,187 @@
+"""Bundled environment-SBOM merge for the QuantBOM SDK (self-contained — no server deps).
+
+Merges a syft-generated (or any CycloneDX) environment SBOM into the collected
+QBOM so one document carries the full dependency inventory plus the quantum
+evidence (QBOM_SPEC §5). Runs client-side, where the environment lives — the
+merge can therefore enrich missing licenses from the *installed* package
+metadata, which a static scanner cannot.
+
+Internal module; reached via `quantbom certify --environment / --syft-sbom` or
+`quantbom.certify(..., environment=True / syft_sbom=...)`.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+ENV_TOOL_PROPERTY = "secqdevops:environment-sbom-tool"
+
+
+def syft_available() -> str | None:
+    return shutil.which("syft")
+
+
+def run_syft(target: str) -> dict[str, Any]:
+    """Run a local syft binary and return its CycloneDX JSON output."""
+    binary = syft_available()
+    if not binary:
+        raise RuntimeError("syft not found on PATH (https://github.com/anchore/syft)")
+    proc = subprocess.run(
+        [binary, "scan", target, "-o", "cyclonedx-json", "--quiet"],
+        capture_output=True, text=True, timeout=600,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"syft scan failed: {proc.stderr.strip()[:400]}")
+    return json.loads(proc.stdout)
+
+
+def _dedupe_key(component: dict[str, Any]) -> str:
+    purl = component.get("purl") or ""
+    if purl:
+        return purl.split("?", 1)[0].split("#", 1)[0].lower()
+    return f"{component.get('name', '')}@{component.get('version', '')}".lower()
+
+
+def _is_python_component(component: dict[str, Any]) -> bool:
+    if (component.get("purl") or "").startswith("pkg:pypi/"):
+        return True
+    for prop in component.get("properties", []) or []:
+        if prop.get("name", "").endswith("package:type") and prop.get("value") == "python":
+            return True
+        if prop.get("name", "").endswith(":language") and prop.get("value") == "python":
+            return True
+    return False
+
+
+def _license_from_environment(name: str) -> str | None:
+    try:
+        from importlib.metadata import metadata
+        meta = metadata(name)
+    except Exception:
+        return None
+    lic = (meta.get("License") or "").strip()
+    if lic and lic.upper() not in ("UNKNOWN", "NONE") and len(lic) <= 120:
+        return lic
+    for classifier in meta.get_all("Classifier") or []:
+        if classifier.startswith("License ::"):
+            return classifier.split("::")[-1].strip()
+    return None
+
+
+def _strip_local_references(component: dict[str, Any]) -> int:
+    """Drop externalReferences that point into the producer's filesystem.
+
+    syft copies pip's direct_url for packages installed from a local directory
+    or in editable mode (`file:///home/<user>/...`). That identifies the
+    producer's machine, not the component, and would travel to the service and
+    to every module the QBOM is handed to. Returns how many were removed.
+    """
+    refs = component.get("externalReferences")
+    if not refs:
+        return 0
+    kept = [r for r in refs if not str(r.get("url", "")).lower().startswith("file:")]
+    if kept:
+        component["externalReferences"] = kept
+    else:
+        del component["externalReferences"]
+    return len(refs) - len(kept)
+
+
+def merge_environment(qbom: dict[str, Any], env_sbom: dict[str, Any], tool_label: str | None = None,
+                      include_all: bool = False) -> dict[str, Any]:
+    """Merge env components/dependencies into the QBOM (in place). Returns stats.
+
+    The QBOM keeps its identity (metadata, serialNumber, specVersion). Colliding
+    components keep the env entry's bom-ref — the dependency graph stays intact —
+    and inherit the QBOM entry's properties/licenses. By default only
+    identifiable package components are merged (type:file inventory and
+    purl-less binary hits are skipped and counted in the stats).
+    """
+    stats = {"env_components": 0, "added": 0, "merged": 0,
+             "skipped_files": 0, "skipped_unidentified": 0,
+             "licenses_enriched": 0, "purls_synthesized": 0,
+             "missing_license": 0, "missing_purl": 0, "local_refs_removed": 0}
+
+    merged: dict[str, dict[str, Any]] = {}
+    for comp in qbom.get("components", []):
+        merged[_dedupe_key(comp)] = comp
+
+    for comp in env_sbom.get("components", []) or []:
+        stats["env_components"] += 1
+        stats["local_refs_removed"] += _strip_local_references(comp)
+        if not comp.get("purl") and _is_python_component(comp) and comp.get("name") and comp.get("version"):
+            comp["purl"] = f"pkg:pypi/{comp['name']}@{comp['version']}"
+            stats["purls_synthesized"] += 1
+        if not include_all:
+            if comp.get("type") == "file":
+                stats["skipped_files"] += 1
+                continue
+            if not comp.get("purl"):
+                stats["skipped_unidentified"] += 1
+                continue
+        key = _dedupe_key(comp)
+        ours = merged.get(key)
+        if ours is None:
+            merged[key] = comp
+            stats["added"] += 1
+            continue
+        if not comp.get("licenses") and ours.get("licenses"):
+            comp["licenses"] = ours["licenses"]
+        have = {(p.get("name"), p.get("value")) for p in comp.setdefault("properties", [])}
+        for prop in ours.get("properties", []) or []:
+            if (prop.get("name"), prop.get("value")) not in have:
+                comp["properties"].append(prop)
+        if not comp["properties"]:
+            del comp["properties"]
+        merged[key] = comp
+        stats["merged"] += 1
+
+    for comp in merged.values():
+        if not comp.get("licenses") and _is_python_component(comp):
+            lic = _license_from_environment(comp.get("name", ""))
+            if lic:
+                comp["licenses"] = [{"license": {"name": lic}}]
+                stats["licenses_enriched"] += 1
+        if not comp.get("licenses"):
+            stats["missing_license"] += 1
+        if not comp.get("purl"):
+            stats["missing_purl"] += 1
+
+    qbom["components"] = sorted(merged.values(), key=_dedupe_key)
+
+    if env_sbom.get("dependencies"):
+        # keep only edges whose refs resolve to merged components (skipped
+        # file/unidentified entries would otherwise leave dangling refs)
+        kept_refs = {c.get("bom-ref") for c in qbom["components"] if c.get("bom-ref")}
+        kept_refs.add((env_sbom.get("metadata", {}).get("component", {}) or {}).get("bom-ref"))
+        deps = []
+        for dep in env_sbom["dependencies"]:
+            if dep.get("ref") not in kept_refs:
+                continue
+            entry = {"ref": dep["ref"]}
+            if dep.get("dependsOn"):
+                entry["dependsOn"] = [r for r in dep["dependsOn"] if r in kept_refs]
+            deps.append(entry)
+        if deps:
+            qbom["dependencies"] = deps
+
+    env_tools = (env_sbom.get("metadata", {}).get("tools", {}) or {})
+    env_tool_components = env_tools.get("components", []) if isinstance(env_tools, dict) else []
+    label = tool_label
+    qbom_tools = qbom.setdefault("metadata", {}).setdefault("tools", {})
+    if isinstance(qbom_tools, dict):
+        tool_list = qbom_tools.setdefault("components", [])
+        for tool in env_tool_components:
+            entry = {"type": "application", "name": tool.get("name", "env-sbom-tool"), "version": tool.get("version", "")}
+            if entry not in tool_list:
+                tool_list.append(entry)
+            if not label:
+                label = f"{entry['name']}@{entry['version']}".rstrip("@")
+    props = qbom["metadata"].setdefault("properties", [])
+    props[:] = [p for p in props if p.get("name") != ENV_TOOL_PROPERTY]
+    props.append({"name": ENV_TOOL_PROPERTY, "value": label or "unknown"})
+
+    stats["total_components"] = len(qbom["components"])
+    return stats

quantbom/_qir.py

@@ -0,0 +1,224 @@
+"""QIR — the second standards-named IR (HARNESS_KITS_PLAN.md K5), by the QDK route.
+
+    Qiskit 2 ──qasm3.dumps──▶ OpenQASM 3 ──qdk.openqasm.compile──▶ QIR (LLVM IR)
+                                              │                      │
+                                       program.qasm            program.ll  ── pyqir (inspect)
+                                      (hash-bound)            (hash-bound)  ── qirrunner (execute)
+
+QIR is *derived*: a second compiler (Microsoft's QDK) sits in the chain, so a
+release never ships QIR on trust. `assess()` checks the QIR against the
+circuit it came from and the counts the release actually measured —
+qubit and result counts, and the output distribution of qirrunner within a
+tolerance — and the gate's QNT-07 fails the release on a mismatch.
+
+Conventions pinned, not assumed (the rule since the PennyLane bit-order bug):
+
+  * Output order. The QDK's `OutputSemantics.Qiskit` records results in the
+    order Qiskit's measured string reads (classical bit 0 rightmost, registers
+    reversed). `probe_order()` compiles and runs X-on-qubit-0-of-2 and requires
+    "01" before any comparison; anything else is undecidable, never a guess.
+  * Profiles. Static circuits compile to the Base profile, dynamic ones to
+    Adaptive_RI; the profile is read back from the module's own attribute.
+  * Gate names. The QDK rewrites gates (`p` -> `rz`, `u` -> `rz`/`ry`, `cp` ->
+    `rz`/`cx`), so gate-name equality is not a consistency criterion; both
+    inventories are recorded for the auditor, counts and behaviour are judged.
+
+Everything here is optional: install `quantbom[qir]` (qdk, pyqir, qirrunner).
+Without it, capture records why QIR is absent and QNT-07 is N-A.
+
+qirrunner executes in a child interpreter: its JIT and CUDA-Q's bundled
+LLVM/MLIR cannot share one process (K1 found a segmentation fault inside
+`qirrunner.run` whenever `cudaq` had been imported first). The QDK's Python
+telemetry is switched off before the QDK is imported: an evidence tool does
+not phone home.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from .frameworks import Undecidable
+
+os.environ.setdefault("QDK_PYTHON_TELEMETRY", "none")  # read by qdk.telemetry at import
+
+SCHEMA = "secqdevops.qir-consistency/v1"
+_RUNNER = (
+    "import json, sys, qirrunner\n"
+    "h = qirrunner.OutputHandler()\n"
+    "qirrunner.run(sys.argv[1], shots=int(sys.argv[2]), rng_seed=int(sys.argv[3]), output_fn=h.handle)\n"
+    "sys.stdout.write(json.dumps(str(h.get_output())))\n"
+)
+PROBE_QASM = 'OPENQASM 3.0;\ninclude "stdgates.inc";\nbit[2] c;\nqubit[2] q;\nx q[0];\nc[0] = measure q[0];\nc[1] = measure q[1];\n'
+PROBE_EXPECT = "01"  # Qiskit's reading: qubit 0 is the rightmost character
+RUN_SEED = 7
+_PROFILE = re.compile(r'"qir_profiles"="(\w+)"')
+
+
+def toolchain() -> tuple[bool, str | None]:
+    """(available, reason-if-not): the three packages the QIR route needs."""
+    missing = []
+    for mod, dist in (("qdk.openqasm", "qdk"), ("pyqir", "pyqir"), ("qirrunner", "qirrunner")):
+        try:
+            __import__(mod)
+        except Exception:
+            missing.append(dist)
+    if missing:
+        return False, f"QIR not emitted: {', '.join(missing)} not installed (pip install 'quantbom[qir]')"
+    return True, None
+
+
+def compile_qir(qasm3_text: str, dynamic: bool) -> tuple[str, str]:
+    """(QIR text, profile) for an OpenQASM 3 program — Base for static circuits,
+    Adaptive_RI for dynamic ones; Qiskit output semantics so the recorded
+    order is the measured order."""
+    import qdk
+    import qdk.openqasm as oq
+
+    profile = qdk.TargetProfile.Adaptive_RI if dynamic else qdk.TargetProfile.Base
+    text = str(oq.compile(qasm3_text, target_profile=profile, output_semantics=oq.OutputSemantics.Qiskit))
+    return text, profile_of(text)
+
+
+def profile_of(qir_text: str) -> str:
+    m = _PROFILE.search(qir_text)
+    return m.group(1) if m else "unknown"
+
+
+def inspect_qir(qir_text: str) -> dict[str, Any]:
+    """What the QIR module declares: entry point, qubits, results, profile, and
+    the quantum-instruction calls it makes (names and counts)."""
+    import pyqir
+
+    module = pyqir.Module.from_ir(pyqir.Context(), qir_text)
+    for f in module.functions:
+        if pyqir.is_entry_point(f):
+            calls = [inst.callee.name for bb in f.basic_blocks for inst in bb.instructions if isinstance(inst, pyqir.Call)]
+            qis = Counter(re.sub(r"^__quantum__qis__", "", c) for c in calls if c.startswith("__quantum__qis__"))
+            return {
+                "entry_point": f.name,
+                "qubits": int(pyqir.required_num_qubits(f) or 0),
+                "results": int(pyqir.required_num_results(f) or 0),
+                "profile": profile_of(qir_text),
+                "adaptive": any(c == "__quantum__rt__read_result" for c in calls),
+                "qis_calls": dict(sorted(qis.items())),
+            }
+    raise Undecidable("QIR module has no entry point")
+
+
+def run_qir(qir_text: str, shots: int, seed: int = RUN_SEED) -> dict[str, int]:
+    """Execute with qirrunner in a child interpreter; keys are the recorded bits in output order."""
+    with tempfile.TemporaryDirectory() as d:
+        path = Path(d) / "program.ll"
+        path.write_text(qir_text, encoding="utf-8")
+        proc = subprocess.run([sys.executable, "-c", _RUNNER, str(path), str(int(shots)), str(int(seed))],
+                              capture_output=True, text=True, timeout=600)
+        if proc.returncode != 0:
+            raise Undecidable(f"qirrunner failed (exit {proc.returncode}): {proc.stderr.strip()[-300:]}")
+        raw = json.loads(proc.stdout or '""')
+    counts: Counter = Counter()
+    cur: list[str] | None = None
+    for line in raw.splitlines():
+        parts = line.split("\t")
+        if parts[0] == "START":
+            cur = []
+        elif parts[:2] == ["OUTPUT", "RESULT"] and cur is not None:
+            cur.append(parts[2])
+        elif parts[0] == "END" and cur is not None:
+            counts["".join(cur)] += 1
+            cur = None
+    return dict(counts)
+
+
+def probe_order() -> str:
+    """Pin the output order with a circuit independent of the one under test."""
+    text, _ = compile_qir(PROBE_QASM, dynamic=False)
+    got = run_qir(text, shots=1)
+    if list(got) != [PROBE_EXPECT]:
+        raise Undecidable(f"QIR output-order probe read {list(got)!r}, expected {PROBE_EXPECT!r} (Qiskit order); "
+                          "the recorded order is unknown, so no comparison is made")
+    return "qiskit: classical bit 0 is the rightmost character (pinned by probe)"
+
+
+def tvd(a: dict[str, float], b: dict[str, float]) -> float:
+    return 0.5 * sum(abs(a.get(k, 0.0) - b.get(k, 0.0)) for k in set(a) | set(b))
+
+
+def default_tolerance(outcomes: int, shots: int) -> float:
+    """Two independent samples of `shots` over `outcomes` distinct results differ
+    by a TVD that grows with sqrt(outcomes / shots); the bound used is
+    max(0.1, 1.5 * sqrt(outcomes / shots)) and is recorded in the report."""
+    return max(0.1, 1.5 * math.sqrt(max(outcomes, 1) / max(shots, 1)))
+
+
+def assess(qir_text: str, circuit: Any, counts: dict[str, int], shots: int, tolerance: float | None = None) -> dict[str, Any]:
+    """The QIR consistency report. Never raises for an undecidable case: the
+    verdict is `consistent`, `inconsistent` (a mismatch the release must not
+    ship with) or `inconclusive` (nothing to compare, or the order unknown)."""
+    measured = {str(k).replace(" ", ""): int(v) for k, v in (counts or {}).items()}
+    report: dict[str, Any] = {
+        "schema": SCHEMA,
+        "method": ("QIR compiled by the QDK from the hash-bound OpenQASM 3 export (Qiskit output semantics); "
+                   "qubit and result counts compared with the source circuit; qirrunner's output distribution "
+                   "compared with the measured counts (total-variation distance); gate inventories recorded, "
+                   "not compared (the QDK rewrites gates)"),
+        "output_order": None,
+        "qir": None,
+        "circuit": {"qubits": int(getattr(circuit, "num_qubits", 0) or 0),
+                    "measured_clbits": _measured_clbits(circuit),
+                    "ops": {k: int(v) for k, v in dict(circuit.count_ops()).items()}},
+        "shots": int(shots or 0),
+        "distributions": None,
+        "tvd": None,
+        "tolerance": None,
+        "verdict": "inconclusive",
+        "reason": None,
+    }
+    try:
+        report["qir"] = inspect_qir(qir_text)
+        if report["circuit"]["measured_clbits"] == 0:
+            raise Undecidable("the source circuit declares no measurements, so its QIR records no results to compare "
+                              "(the run measured every qubit); declare measurements to enable the comparison")
+        if not shots or not measured:
+            raise Undecidable("no measured counts to compare with")
+        report["output_order"] = probe_order()
+        problems = []
+        if report["qir"]["qubits"] != report["circuit"]["qubits"]:
+            problems.append(f"QIR declares {report['qir']['qubits']} qubits, the circuit has {report['circuit']['qubits']}")
+        if report["qir"]["results"] != report["circuit"]["measured_clbits"]:
+            problems.append(f"QIR records {report['qir']['results']} results, the circuit measures {report['circuit']['measured_clbits']} bits")
+        qir_counts = run_qir(qir_text, shots)
+        n = sum(qir_counts.values()) or 1
+        p_qir = {k: v / n for k, v in qir_counts.items()}
+        p_meas = {k: v / shots for k, v in measured.items()}
+        report["distributions"] = {"measured": measured, "qir": qir_counts}
+        distance = tvd(p_qir, p_meas)
+        report["tvd"] = round(distance, 6)
+        report["tolerance"] = tolerance if tolerance is not None else round(default_tolerance(len(set(p_qir) | set(p_meas)), shots), 6)
+        if distance > report["tolerance"]:
+            problems.append(f"qirrunner's distribution differs from the measured counts: TVD {distance:.4f} > tolerance {report['tolerance']}")
+        if problems:
+            report["verdict"] = "inconsistent"
+            report["reason"] = "; ".join(problems)
+        else:
+            report["verdict"] = "consistent"
+    except Undecidable as why:
+        report["reason"] = str(why)
+    except Exception as err:  # never block collection, never affirm
+        report["reason"] = f"comparison failed: {type(err).__name__}: {err}"
+    return report
+
+
+def _measured_clbits(circuit: Any) -> int:
+    bits = set()
+    for inst in circuit.data:
+        if inst.operation.name == "measure":
+            bits.update(inst.clbits)
+    return len(bits)

quantbom/_scan.py

@@ -0,0 +1,118 @@
+"""Bundled vulnerability scan for the QuantBOM SDK (self-contained — no server deps).
+
+Runs grype over the collected (optionally syft-merged) QBOM and writes the
+normalized findings into its `vulnerabilities[]`, so the gate's CRA-ESR-03
+control and the VEX/VDR evidence carry real data. Affected-component refs are
+remapped onto this QBOM's components by purl. Internal module; reached via
+`quantbom certify --vuln-scan` or `quantbom.certify(..., vuln_scan=True)`.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+SCANNER_PROPERTY = "secqdevops:vuln-scanner"
+SEVERITY_ORDER = ["critical", "high", "medium", "low", "info", "none", "unknown"]
+
+
+def grype_available() -> str | None:
+    return shutil.which("grype")
+
+
+def run_grype(sbom_path: Path) -> dict[str, Any]:
+    import tempfile
+
+    binary = grype_available()
+    if not binary:
+        raise RuntimeError("grype not found on PATH (https://github.com/anchore/grype)")
+    # grype's CycloneDX decoder lags the spec and rejects specVersion 1.7
+    # documents. Feed it a temp copy floored to 1.6 — purls/versions (all the
+    # scanner reads) are identical; the real QBOM keeps its specVersion.
+    doc = json.loads(sbom_path.read_text(encoding="utf-8"))
+    scan_target, tmp_path = sbom_path, None
+    try:
+        if str(doc.get("specVersion", "")) not in ("1.2", "1.3", "1.4", "1.5", "1.6"):
+            doc["specVersion"] = "1.6"
+            with tempfile.NamedTemporaryFile("w", suffix=".cdx.json", delete=False) as tmp:
+                json.dump(doc, tmp)
+                tmp_path = Path(tmp.name)
+            scan_target = tmp_path
+        proc = subprocess.run(
+            [binary, f"sbom:{scan_target}", "-o", "cyclonedx-json"],
+            capture_output=True, text=True, timeout=900,
+        )
+    finally:
+        if tmp_path:
+            tmp_path.unlink(missing_ok=True)
+    if proc.returncode != 0:
+        raise RuntimeError(f"grype scan failed: {proc.stderr.strip()[-400:]}")
+    return json.loads(proc.stdout)
+
+
+def _purl_key(purl: str | None) -> str | None:
+    if not purl:
+        return None
+    return purl.split("?", 1)[0].split("#", 1)[0].lower()
+
+
+def _severity(vuln: dict[str, Any]) -> str:
+    for rating in vuln.get("ratings", []) or []:
+        sev = str(rating.get("severity", "")).lower()
+        if sev:
+            return sev
+    return "unknown"
+
+
+def apply_findings(qbom: dict[str, Any], scan_doc: dict[str, Any], tool_label: str | None = None) -> dict[str, Any]:
+    """Write the scanner's vulnerabilities into the QBOM (in place). Returns stats."""
+    scanner_ref_to_purl: dict[str, str] = {}
+    for comp in scan_doc.get("components", []) or []:
+        key = _purl_key(comp.get("purl"))
+        if key and comp.get("bom-ref"):
+            scanner_ref_to_purl[comp["bom-ref"]] = key
+    ours_by_purl: dict[str, str] = {}
+    for comp in qbom.get("components", []) or []:
+        key = _purl_key(comp.get("purl"))
+        if key:
+            ours_by_purl[key] = comp.get("bom-ref") or comp["purl"]
+
+    stats = {"findings": 0, "matched_components": 0, "unmatched_refs": 0}
+    by_severity: dict[str, int] = {}
+    vulnerabilities: list[dict[str, Any]] = []
+    for vuln in scan_doc.get("vulnerabilities", []) or []:
+        stats["findings"] += 1
+        by_severity[_severity(vuln)] = by_severity.get(_severity(vuln), 0) + 1
+        entry = {k: v for k, v in vuln.items() if k in ("id", "source", "references", "ratings", "description", "advisories")}
+        affects = []
+        for affected in vuln.get("affects", []) or []:
+            purl_key = scanner_ref_to_purl.get(affected.get("ref", ""))
+            our_ref = ours_by_purl.get(purl_key) if purl_key else None
+            if our_ref:
+                affects.append({"ref": our_ref})
+                stats["matched_components"] += 1
+            else:
+                affects.append(affected)
+                stats["unmatched_refs"] += 1
+        if affects:
+            entry["affects"] = affects
+        vulnerabilities.append(entry)
+
+    qbom["vulnerabilities"] = vulnerabilities
+
+    label = tool_label
+    scan_tools = (scan_doc.get("metadata", {}).get("tools", {}) or {})
+    tool_components = scan_tools.get("components", []) if isinstance(scan_tools, dict) else []
+    if not label:
+        for tool in tool_components:
+            if tool.get("name"):
+                label = f"{tool.get('name')}@{tool.get('version', '')}".rstrip("@")
+                break
+    props = qbom.setdefault("metadata", {}).setdefault("properties", [])
+    props[:] = [p for p in props if p.get("name") != SCANNER_PROPERTY]
+    props.append({"name": SCANNER_PROPERTY, "value": label or "unknown"})
+
+    stats["by_severity"] = {s: by_severity[s] for s in SEVERITY_ORDER if s in by_severity}
+    return stats