quantbom 0.6.0__py3-none-any.whl

quantbom/attest.py

@@ -0,0 +1,363 @@
+"""Partner and tool evidence from a pip install — MVP_PLAN.md B3.
+
+The four `provider: tool` actions of the harness (`quantbom actions`) used to
+exist only as repository scripts, so a pip user saw them listed and could not
+run them. This module is those scripts, in the wheel, stdlib-only:
+
+    quantbom attest tests         --bundle b/ --suite S --outcome passed --passed N      (MOD-05 test report)
+    quantbom attest vulns         --bundle b/ --policy-url U --contact C                 (VEX/VDR + CVD policy, MOD-07)
+    quantbom attest constant-time --bundle b/ --tool dudect --target T --measurements CSV (CT proof, MOD-09)
+    quantbom attest crypto        --bundle b/ [--cbom FILE]                              (CBOM agility, MOD-03/09)
+
+Each writes its artifact(s) at the canonical path inside the bundle, hash-bound
+and referenced from the QBOM exactly as the repository script does: the bytes
+and the properties are identical, and tests/harness/test_sdk_attest.py keeps
+them so. Run them after `quantbom collect` and before `quantbom sign`, so the
+producer signature covers what they add.
+
+The classification tables and thresholds below mirror the repository scripts
+(emit_test_evidence.py, emit_vuln_evidence.py, emit_ct_evidence.py,
+cbom_agility.py); the test pins the ones the gate also holds.
+"""
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import math
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+# ---- shared ----------------------------------------------------------------
+def _canonical(data: Any) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def _sha256(raw: bytes) -> str:
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _bundle(bundle: str | os.PathLike) -> tuple[Path, Path]:
+    bundle_dir = Path(bundle)
+    sbom_path = bundle_dir / "sbom.cdx.json"
+    if not sbom_path.is_file():
+        raise FileNotFoundError(f"{bundle_dir} is not an evidence bundle (no sbom.cdx.json); make one with `quantbom collect`")
+    return bundle_dir, sbom_path
+
+
+def _load(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _write_report(path: Path, report: dict[str, Any]) -> tuple[bytes, str]:
+    """Canonical JSON plus a newline — the bytes every repository emitter writes."""
+    raw = (_canonical(report) + "\n").encode("utf-8")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(raw)
+    return raw, _sha256(raw)
+
+
+def _inject(sbom_path: Path, own: set[str], props: list[dict[str, str]]) -> None:
+    """Replace this action's own properties on the QBOM; every other property stays."""
+    sbom = _load(sbom_path)
+    metadata = sbom.setdefault("metadata", {})
+    kept = [p for p in metadata.setdefault("properties", []) if p.get("name") not in own]
+    metadata["properties"] = kept + props
+    sbom_path.write_text(json.dumps(sbom, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+
+def _rel(bundle_dir: Path, path: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(bundle_dir.resolve()))
+    except ValueError:
+        return str(path)
+
+
+# ---- attest tests (MOD-05) -------------------------------------------------
+TEST_PROPERTY_NAMES = {"secqdevops:test-report-ref", "secqdevops:test-report-sha256", "secqdevops:test-outcome"}
+TEST_REPORT_REL = "evidence/mod05/test-report.json"
+TEST_OUTCOMES = ("passed", "failed")
+
+
+def tests(bundle: str | os.PathLike, *, suite: str, outcome: str, passed: int = 0, failed: int = 0, skipped: int = 0,
+          tool: str = "mod05", source_module: str = "MOD-05", out: str = TEST_REPORT_REL) -> dict[str, Any]:
+    """Attach a security test report (CRA Annex I Part II(3); control MOD05-TEST-01)."""
+    if outcome not in TEST_OUTCOMES:
+        raise ValueError(f"outcome must be one of {TEST_OUTCOMES}")
+    bundle_dir, sbom_path = _bundle(bundle)
+    report = {
+        "schema": "secqdevops.test-report/v1",
+        "source_module": source_module,
+        "suite": suite,
+        "tool": tool,
+        "outcome": outcome,
+        "totals": {"passed": passed, "failed": failed, "skipped": skipped},
+    }
+    path = bundle_dir / out
+    _, sha = _write_report(path, report)
+    ref = _rel(bundle_dir, path)
+    _inject(sbom_path, TEST_PROPERTY_NAMES, [
+        {"name": "secqdevops:test-report-ref", "value": ref},
+        {"name": "secqdevops:test-report-sha256", "value": sha},
+        {"name": "secqdevops:test-outcome", "value": outcome},
+    ])
+    return {"out": str(path), "sha256": sha, "outcome": outcome, "injected_into": str(sbom_path)}
+
+
+# ---- attest vulnerability handling (MOD-07) --------------------------------
+VULN_PROPERTY_NAMES = {"secqdevops:vex-ref", "secqdevops:vex-sha256", "secqdevops:cvd-policy-ref",
+                       "secqdevops:cvd-policy-sha256", "secqdevops:cvd-contact"}
+VEX_REL, CVD_REL = "evidence/vex.cdx.json", "evidence/cvd-policy.json"
+ALIGNED_STANDARDS = ["EN 40000-1-3 (prEN — no OJ citation; draft)", "ISO/IEC 29147:2018", "EN ISO/IEC 30111:2019"]
+
+
+def _build_vex(sbom: dict[str, Any]) -> dict[str, Any]:
+    metadata = sbom.get("metadata", {})
+    component = metadata.get("component", {})
+    return {
+        "bomFormat": "CycloneDX",
+        "specVersion": sbom.get("specVersion", "1.7"),
+        "version": 1,
+        "metadata": {
+            "timestamp": metadata.get("timestamp", "1970-01-01T00:00:00Z"),
+            "component": {"type": component.get("type", "application"), "name": component.get("name", "unknown"),
+                          # the QBOM's version when it has one; never an invented "0"
+                          **({"version": component["version"]} if component.get("version") else {}),
+                          "purl": component.get("purl")},
+            "properties": [
+                {"name": "secqdevops:document-kind", "value": "vex-vdr"},
+                {"name": "secqdevops:covers-sbom-serial", "value": sbom.get("serialNumber", "")},
+            ],
+        },
+        "vulnerabilities": sbom.get("vulnerabilities", []),
+    }
+
+
+def vulnerability_handling(bundle: str | os.PathLike, *, policy_url: str, contact: str, sla_days: int = 90,
+                           advisories: str | os.PathLike | None = None, vex_out: str = VEX_REL, cvd_out: str = CVD_REL) -> dict[str, Any]:
+    """VEX/VDR over the release plus a CVD-policy attestation (CRA Annex I Part II(2), II(5); CRA-VULN-01, CRA-VDP-01)."""
+    bundle_dir, sbom_path = _bundle(bundle)
+    sbom = _load(sbom_path)
+    if advisories is not None:  # sibling-module advisories feed the VEX (and CRA-ESR-03)
+        known = {v.get("id") for v in sbom.get("vulnerabilities", [])}
+        merged = [dict(v, **{"properties": (v.get("properties") or []) + [{"name": "secqdevops:advisory-source", "value": "MOD-07"}]})
+                  for v in _load(Path(advisories)).get("vulnerabilities", []) if v.get("id") and v["id"] not in known]
+        if merged:
+            sbom.setdefault("vulnerabilities", []).extend(merged)
+            sbom_path.write_text(json.dumps(sbom, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    timestamp = sbom.get("metadata", {}).get("timestamp", "1970-01-01T00:00:00Z")
+    vex = _build_vex(sbom)
+    cvd = {"schema": "secqdevops.cvd-policy/v1", "policy_url": policy_url, "contact": contact,
+           "disclosure_sla_days": sla_days, "attested_at": timestamp, "aligned_standards": ALIGNED_STANDARDS}
+    vex_path, cvd_path = bundle_dir / vex_out, bundle_dir / cvd_out
+    _, vex_sha = _write_report(vex_path, vex)
+    _, cvd_sha = _write_report(cvd_path, cvd)
+    _inject(sbom_path, VULN_PROPERTY_NAMES, [
+        {"name": "secqdevops:vex-ref", "value": _rel(bundle_dir, vex_path)},
+        {"name": "secqdevops:vex-sha256", "value": vex_sha},
+        {"name": "secqdevops:cvd-policy-ref", "value": _rel(bundle_dir, cvd_path)},
+        {"name": "secqdevops:cvd-policy-sha256", "value": cvd_sha},
+        {"name": "secqdevops:cvd-contact", "value": contact},
+    ])
+    return {"vex_out": str(vex_path), "vex_sha256": vex_sha, "vex_vulnerability_count": len(vex["vulnerabilities"]),
+            "cvd_out": str(cvd_path), "cvd_policy_sha256": cvd_sha, "injected_into": str(sbom_path)}
+
+
+# ---- prove constant time (MOD-09) -------------------------------------------
+CT_PROPERTY_NAMES = {"secqdevops:ct-tool", "secqdevops:ct-target", "secqdevops:ct-verdict",
+                     "secqdevops:ct-proof-ref", "secqdevops:ct-proof-sha256"}
+CT_PROOF_REL = "crypto/ct-proof.json"
+SUPPORTED_CT_TOOLS = ("binsec-rel", "ctgrind", "dudect")  # the gate's SUPPORTED_CT_TOOLS
+DEFAULT_T_THRESHOLD = 10.0  # dudect's rule of thumb: |t| > 10 is strong evidence of timing leakage
+
+
+def welch_t(class_a: list[float], class_b: list[float]) -> float:
+    """Two-sample Welch's t-statistic — the core of dudect's leakage test."""
+    if len(class_a) < 2 or len(class_b) < 2:
+        raise ValueError("each timing class needs at least two measurements")
+    mean_a, mean_b = sum(class_a) / len(class_a), sum(class_b) / len(class_b)
+    var_a = sum((v - mean_a) ** 2 for v in class_a) / (len(class_a) - 1)
+    var_b = sum((v - mean_b) ** 2 for v in class_b) / (len(class_b) - 1)
+    denom = math.sqrt(var_a / len(class_a) + var_b / len(class_b))
+    return 0.0 if denom == 0.0 else (mean_a - mean_b) / denom
+
+
+def load_measurements(path: str | os.PathLike) -> tuple[list[float], list[float]]:
+    """A two-column CSV: class label (0/1, fix/fixed = class 0) and a timing in nanoseconds."""
+    class_a: list[float] = []
+    class_b: list[float] = []
+    with Path(path).open(newline="", encoding="utf-8") as handle:
+        for row in csv.reader(handle):
+            if not row or row[0].strip().lower() in {"class", "#"}:
+                continue
+            label, timing = row[0].strip(), float(row[1])
+            (class_a if label in {"0", "fix", "fixed"} else class_b).append(timing)
+    return class_a, class_b
+
+
+def constant_time(bundle: str | os.PathLike, *, tool: str, target: str, t_value: float | None = None,
+                  measurements: str | os.PathLike | None = None, threshold: float = DEFAULT_T_THRESHOLD,
+                  out: str = CT_PROOF_REL) -> dict[str, Any]:
+    """A constant-time proof from a dudect / ctgrind / Binsec-Rel result (CRA Annex I 3(c); CRA-ESR-06)."""
+    if tool not in SUPPORTED_CT_TOOLS:
+        raise ValueError(f"tool must be one of {SUPPORTED_CT_TOOLS}")
+    if (t_value is None) == (measurements is None):
+        raise ValueError("give exactly one of t_value= or measurements=")
+    bundle_dir, sbom_path = _bundle(bundle)
+    if measurements is not None:
+        class_a, class_b = load_measurements(measurements)
+        t_value = welch_t(class_a, class_b)
+        n = len(class_a) + len(class_b)
+    else:
+        n = None
+    leaks = abs(t_value) > threshold
+    report = {
+        "schema": "secqdevops.ct-proof/v1",
+        "tool": tool,
+        "target": target,
+        "metric": "welch_t" if tool == "dudect" else "tool_verdict",
+        "t_value": round(t_value, 6),
+        "t_threshold": threshold,
+        "n_measurements": n,
+        "verdict": "fail" if leaks else "pass",
+        "interpretation": (f"|t|={abs(t_value):.3f} exceeds {threshold} — timing leakage detected" if leaks
+                           else f"|t|={abs(t_value):.3f} within {threshold} — no timing leakage observed"),
+    }
+    path = bundle_dir / out
+    _, sha = _write_report(path, report)
+    ref = _rel(bundle_dir, path)
+    _inject(sbom_path, CT_PROPERTY_NAMES, [
+        {"name": "secqdevops:ct-tool", "value": tool},
+        {"name": "secqdevops:ct-target", "value": target},
+        {"name": "secqdevops:ct-verdict", "value": report["verdict"]},
+        {"name": "secqdevops:ct-proof-ref", "value": ref},
+        {"name": "secqdevops:ct-proof-sha256", "value": sha},
+    ])
+    return {"verdict": report["verdict"], "t_value": report["t_value"], "report_ref": ref, "report_sha256": sha, "injected_into": str(sbom_path)}
+
+
+# ---- assess crypto (MOD-03 / MOD-09) ----------------------------------------
+CBOM_PROPERTY_NAMES = {"secqdevops:cbom-ref", "secqdevops:cbom-sha256", "secqdevops:crypto-agility-ref",
+                       "secqdevops:crypto-agility-sha256", "secqdevops:crypto-agility-score", "secqdevops:crypto-migration-readiness"}
+CBOM_REL, AGILITY_REL = "crypto/cbom.cdx.json", "crypto/cbom-agility.json"
+# Shor-broken public-key families
+QUANTUM_VULNERABLE = ["RSA", "DSA", "DIFFIE-HELLMAN", "DH", "ECDH", "ECDSA", "ECC", "EDDSA",
+                      "ED25519", "ED448", "X25519", "X448", "ELGAMAL", "SECP", "BRAINPOOL", "CURVE25519"]
+# NIST PQC + stateful hash-based signatures
+PQC = ["ML-KEM", "KYBER", "ML-DSA", "DILITHIUM", "SLH-DSA", "SPHINCS", "FALCON", "FN-DSA", "HQC", "MCELIECE",
+       "CLASSIC MCELIECE", "BIKE", "FRODO", "FRODOKEM", "XMSS", "LMS", "HSS"]
+# symmetric / hash that remain acceptable (Grover only halves the security margin)
+SAFE_SYMMETRIC = ["AES-256", "AES256", "AES-192", "CHACHA20", "SHA-256", "SHA-384", "SHA-512", "SHA256", "SHA384", "SHA512", "SHA3", "SHAKE", "HMAC"]
+# broken or quantum-weakened classical primitives
+WEAKENED = ["AES-128", "AES128", "3DES", "TRIPLE-DES", "DES", "RC4", "SHA-1", "SHA1", "MD5"]
+CLASS_RISK = {"QUANTUM_VULNERABLE": 1.0, "WEAKENED": 0.5, "UNKNOWN": 0.5, "QUANTUM_SAFE": 0.0}
+PQC_STANDARD_IDS = [
+    (("ML-KEM", "KYBER"), "NIST FIPS 203 (ML-KEM)"),
+    (("ML-DSA", "DILITHIUM"), "NIST FIPS 204 (ML-DSA)"),
+    (("SLH-DSA", "SPHINCS"), "NIST FIPS 205 (SLH-DSA)"),
+    (("XMSS", "LMS", "HSS"), "NIST SP 800-208 (stateful hash-based signatures)"),
+]
+REPORT_STANDARDS = ["NIST FIPS 203/204/205", "NIST SP 800-208", "ETSI TR 103 619"]
+
+
+def _match(name: str, table: list[str]) -> bool:
+    n = name.upper().replace("_", "-")
+    return any(token in n for token in table)
+
+
+def _standard_for(name: str) -> str | None:
+    n = name.upper().replace("_", "-")
+    for tokens, standard in PQC_STANDARD_IDS:
+        if any(token in n for token in tokens):
+            return standard
+    return None
+
+
+def classify_asset(name: str, crypto_props: dict[str, Any]) -> tuple[str, str]:
+    """(classification, reason); uses nistQuantumSecurityLevel when present."""
+    algo = crypto_props.get("algorithmProperties", {}) if isinstance(crypto_props, dict) else {}
+    primitive = str(algo.get("primitive", "")).lower()
+    nq = algo.get("nistQuantumSecurityLevel")
+    is_asymmetric = primitive in {"pke", "kem", "signature", "key-agree", "drbg-asym"} or _match(name, QUANTUM_VULNERABLE) or _match(name, PQC)
+    if _match(name, PQC):
+        return "QUANTUM_SAFE", "NIST PQC / hash-based primitive"
+    if isinstance(nq, int):
+        if nq >= 1:
+            return "QUANTUM_SAFE", f"declared nistQuantumSecurityLevel={nq}"
+        if nq == 0 and is_asymmetric:
+            return "QUANTUM_VULNERABLE", "declared nistQuantumSecurityLevel=0 (asymmetric)"
+    if _match(name, QUANTUM_VULNERABLE):
+        return "QUANTUM_VULNERABLE", "Shor-broken public-key family"
+    if _match(name, WEAKENED):
+        return "WEAKENED", "broken or quantum-weakened classical primitive"
+    if _match(name, SAFE_SYMMETRIC):
+        return "QUANTUM_SAFE", "strong symmetric/hash (Grover only halves margin)"
+    return "UNKNOWN", "unrecognized algorithm; manual review required"
+
+
+def assess_cbom(cbom: dict[str, Any]) -> dict[str, Any]:
+    assets = []
+    counts = {"QUANTUM_VULNERABLE": 0, "WEAKENED": 0, "QUANTUM_SAFE": 0, "UNKNOWN": 0}
+    pqc_present = 0
+    for comp in [c for c in cbom.get("components", []) if c.get("type") == "cryptographic-asset" or "cryptoProperties" in c]:
+        name = comp.get("name", "<unnamed>")
+        crypto_props = comp.get("cryptoProperties", {})
+        classification, reason = classify_asset(name, crypto_props)
+        counts[classification] += 1
+        if _match(name, PQC):
+            pqc_present += 1
+        asset: dict[str, Any] = {"name": name, "primitive": (crypto_props.get("algorithmProperties", {}) or {}).get("primitive"),
+                                 "classification": classification, "reason": reason}
+        standard = _standard_for(name)
+        if standard:
+            asset["standard"] = standard
+        assets.append(asset)
+    total = len(assets)
+    risk = sum(CLASS_RISK[a["classification"]] for a in assets)
+    agility_score = round(100 * (1 - risk / total)) if total else 0
+    if counts["QUANTUM_VULNERABLE"] == 0 and counts["WEAKENED"] == 0:
+        readiness = "READY"
+    elif counts["QUANTUM_VULNERABLE"] > 0 and pqc_present == 0:
+        readiness = "NOT_READY"
+    else:
+        readiness = "IN_PROGRESS"
+    return {
+        "schema": "secqdevops.cbom-agility/v1",
+        "standards": REPORT_STANDARDS,
+        "summary": {"total_assets": total, "quantum_vulnerable": counts["QUANTUM_VULNERABLE"], "weakened": counts["WEAKENED"],
+                    "quantum_safe": counts["QUANTUM_SAFE"], "pqc_present": pqc_present, "unknown": counts["UNKNOWN"]},
+        "agility_score": agility_score,
+        "migration_readiness": readiness,
+        "assets": assets,
+    }
+
+
+def crypto(bundle: str | os.PathLike, *, cbom: str | os.PathLike | None = None, out: str = AGILITY_REL) -> dict[str, Any]:
+    """CBOM ingestion and PQC migration-readiness (CRA Annex I 3(c); CRA-CRYPTO-01).
+
+    The CBOM is read from crypto/cbom.cdx.json inside the bundle; a path given
+    with cbom= is copied there first, so the bundle carries what was assessed.
+    """
+    bundle_dir, sbom_path = _bundle(bundle)
+    cbom_path = bundle_dir / CBOM_REL
+    if cbom is not None and Path(cbom).resolve() != cbom_path.resolve():
+        cbom_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(Path(cbom), cbom_path)
+    if not cbom_path.is_file():
+        raise FileNotFoundError(f"no CBOM at {cbom_path}: copy your CycloneDX CBOM there, or pass cbom=FILE (--cbom)")
+    report = assess_cbom(_load(cbom_path))
+    path = bundle_dir / out
+    _, report_sha = _write_report(path, report)
+    cbom_sha = _sha256(cbom_path.read_bytes())
+    _inject(sbom_path, CBOM_PROPERTY_NAMES, [
+        {"name": "secqdevops:cbom-ref", "value": _rel(bundle_dir, cbom_path)},
+        {"name": "secqdevops:cbom-sha256", "value": cbom_sha},
+        {"name": "secqdevops:crypto-agility-ref", "value": _rel(bundle_dir, path)},
+        {"name": "secqdevops:crypto-agility-sha256", "value": report_sha},
+        {"name": "secqdevops:crypto-agility-score", "value": str(report["agility_score"])},
+        {"name": "secqdevops:crypto-migration-readiness", "value": report["migration_readiness"]},
+    ])
+    return {"agility_score": report["agility_score"], "migration_readiness": report["migration_readiness"],
+            "summary": report["summary"], "report_out": str(path), "injected_into": str(sbom_path)}