@quantakrypto/core 0.4.2 → 0.4.4

package/src/detectors/stateful-hbs.ts

@@ -0,0 +1,180 @@
+/**
+ * Config / source-agnostic detector: stateful hash-based signatures
+ * (NIST SP 800-208) — LMS, HSS, XMSS and XMSSMT.
+ *
+ * These schemes ARE quantum-safe and NIST-approved (SP 800-208, for firmware /
+ * secure-boot signing), so this is NOT a "broken crypto" finding. The hazard it
+ * flags is STATE MANAGEMENT: each private key holds a bounded set of one-time
+ * key indices, and reusing an index is catastrophic (it enables signature
+ * forgery). The detector therefore surfaces the usage so a reviewer can confirm
+ * rigorous state handling exists — or migrate to a stateless scheme.
+ *
+ * Like {@link pemDetector}, this is a `scope: "config"`, `language: "any"`
+ * detector that runs on every text file, because the distinctive LMS/XMSS
+ * parameter strings and library tokens (`LMS_SHA256_M32_H10`, `pyhsslms`,
+ * `XMSS-SHA2_10_256`, …) appear identically across languages, config, and docs.
+ * Every rule's metadata lives in the {@link RuleMeta} declaration below; the
+ * regexes are tightly bounded and `\b`-anchored to stay high-signal.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import { eachMatch, findingFromRule } from "../detect-utils.js";
+import { CWE_RISKY_PRIMITIVE } from "../cwe.js";
+
+/**
+ * Shared remediation for every stateful-HBS finding: these are approved but
+ * STATEFUL, so the reviewer must confirm state management before trusting them.
+ */
+const STATEFUL_HBS_REMEDIATION =
+  "LMS/HSS/XMSS/XMSSMT are NIST-approved (SP 800-208) but STATEFUL: the signer " +
+  "must NEVER reuse a one-time key index (reuse enables signature forgery). Use " +
+  "only with rigorous, crash-safe state management; otherwise prefer the " +
+  "stateless ML-DSA (FIPS 204) or SLH-DSA (FIPS 205).";
+
+/** A stateful-HBS rule: its catalog metadata plus the token regex that triggers it. */
+interface HbsRule {
+  /** Global regex matching the distinctive token. */
+  re: RegExp;
+  meta: RuleMeta;
+}
+
+const HBS_RULES: HbsRule[] = [
+  {
+    // LMS parameter set, e.g. LMS_SHA256_M32_H10 / LMS_SHAKE_M24_H10 (SP 800-208
+    // adds SHAKE256 and the 192-bit M24/N24 sets to RFC 8554's SHA-256 sets).
+    re: /\bLMS_(?:SHA256|SHAKE(?:256)?)_[MN]\d+_[HW]\d+\b/g,
+    meta: {
+      id: "stateful-hbs-lms-param",
+      title: "LMS parameter set (stateful hash-based signature)",
+      description: "LMS/HSS one-time-signature parameter string (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "LMS parameter set — NIST-approved (SP 800-208) but STATEFUL: reusing a one-time key index is catastrophic.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+  {
+    // HSS keygen (hierarchical LMS), e.g. pyhsslms.hss_generate_private_key(...).
+    re: /\bhss_generate_private_key\b/g,
+    meta: {
+      id: "stateful-hbs-hss-keygen",
+      title: "HSS private-key generation (stateful hash-based signature)",
+      description: "HSS (hierarchical LMS) private-key generation call (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "HSS private-key generation — NIST-approved (SP 800-208) but STATEFUL: never reuse a one-time key index.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+  {
+    // pyhsslms — the Python LMS/HSS library import token.
+    re: /\bpyhsslms\b/g,
+    meta: {
+      id: "stateful-hbs-pyhsslms",
+      title: "pyhsslms library (stateful LMS/HSS signatures)",
+      description: "Reference to the pyhsslms LMS/HSS library (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "pyhsslms (LMS/HSS) — NIST-approved (SP 800-208) but STATEFUL: the signer must never reuse a one-time key index.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+  {
+    // XMSS parameter set, e.g. XMSS-SHA2_10_256 / XMSS-SHAKE256_10_192 (SP 800-208
+    // adds the SHAKE256 and 192-bit variants to RFC 8391's SHA-2/256 sets).
+    re: /\bXMSS-(?:SHA2|SHAKE(?:256)?)_\d+_(?:192|256)\b/g,
+    meta: {
+      id: "stateful-hbs-xmss-param",
+      title: "XMSS parameter set (stateful hash-based signature)",
+      description: "XMSS one-time-signature parameter string (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "XMSS parameter set — NIST-approved (SP 800-208) but STATEFUL: reusing a one-time key index is catastrophic.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+  {
+    // XMSSMT (multi-tree XMSS) parameter set, e.g. XMSSMT-SHA2_20/2_256 or the
+    // SP 800-208 SHAKE256 variant XMSSMT-SHAKE256_20/2_256.
+    re: /\bXMSSMT-(?:SHA2|SHAKE(?:256)?)_\d+\b/g,
+    meta: {
+      id: "stateful-hbs-xmssmt-param",
+      title: "XMSSMT parameter set (stateful hash-based signature)",
+      description: "XMSSMT (multi-tree XMSS) parameter string (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "XMSSMT parameter set — NIST-approved (SP 800-208) but STATEFUL: never reuse a one-time key index.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+  {
+    // XMSS keypair generation, e.g. xmss_keypair(...) (liboqs / xmss reference).
+    re: /\bxmss_keypair\b/g,
+    meta: {
+      id: "stateful-hbs-xmss-keypair",
+      title: "XMSS keypair generation (stateful hash-based signature)",
+      description: "XMSS keypair-generation call (SP 800-208)",
+      category: "signature",
+      severity: "medium",
+      confidence: "high",
+      algorithm: "unknown",
+      hndl: false,
+      cwe: CWE_RISKY_PRIMITIVE,
+      message:
+        "XMSS keypair generation — NIST-approved (SP 800-208) but STATEFUL: the signer must never reuse a one-time key index.",
+      remediation: STATEFUL_HBS_REMEDIATION,
+    },
+  },
+];
+
+/** Detects stateful hash-based signature (SP 800-208) usage in arbitrary files. */
+export const statefulHbsDetector: Detector = {
+  id: "stateful-hbs",
+  description:
+    "Stateful hash-based signatures (NIST SP 800-208: LMS / HSS / XMSS / XMSSMT) in any file",
+  scope: "config",
+  language: "any",
+  rules: HBS_RULES.map((r) => r.meta),
+  // Applies to every text file; the walker already filters out binaries.
+  appliesTo: () => true,
+  detect({ file, content }): Finding[] {
+    const findings: Finding[] = [];
+    for (const rule of HBS_RULES) {
+      eachMatch(rule.re, content, (m) => {
+        findings.push(
+          findingFromRule(rule.meta, {
+            file,
+            content,
+            index: m.index,
+            matchLength: m[0].length,
+          }),
+        );
+      });
+    }
+    return findings;
+  },
+};

package/src/detectors/terraform.ts

@@ -0,0 +1,154 @@
+/**
+ * IaC detector: classical asymmetric cryptography provisioned by Terraform /
+ * OpenTofu (`.tf`, `.tf.json`). Infrastructure-as-code mints real keys and CMKs
+ * that never appear in application source, so this is a distinct surface from the
+ * language packs.
+ *
+ * Covered:
+ *  - hashicorp/tls `tls_private_key`:      `algorithm = "RSA" | "ECDSA"`
+ *  - Google Cloud KMS `version_template`:  `algorithm = "RSA_SIGN_…" | "EC_SIGN_…"`
+ *  - AWS KMS `aws_kms_key`:                `customer_master_key_spec = "RSA_…" | "ECC_…"`
+ *  - Azure `azurerm_key_vault_key`:        `key_type = "RSA" | "EC"` (+ HSM variants)
+ *
+ * The HCL assignment forms (`algorithm = "…"`, `customer_master_key_spec = "…"`,
+ * `key_type = "…"`) are specific enough inside `.tf` files that the false-positive
+ * risk is low. EC keys are classified conservatively as key-agreement-capable
+ * (hndl:true) since a provisioned EC key can feed ECDH.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import { eachMatch, findingFromRule, hasExtension } from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+const TF_EXTENSIONS: readonly string[] = [".tf", ".tf.json"];
+
+// Each attribute is matched in BOTH HCL (`algorithm = "RSA"`) and the `.tf.json`
+// variant (`"algorithm": "RSA"`): an optional quote around the key, and `:` or
+// `=` as the separator. The `(?<![\w"-])` lookbehind stops a longer attribute
+// name (`my_algorithm`) from matching on its suffix.
+// RSA: tls_private_key `"RSA"` plus the Google KMS `RSA_SIGN_…` / `RSA_DECRYPT_…`.
+const RE_TF_RSA = /(?<![\w"-])"?algorithm"?\s*[:=]\s*"RSA(?:_[A-Z0-9_]+)?"/g;
+// ECDSA / EC signing: tls_private_key `"ECDSA"` and Google KMS `"EC_SIGN_…"`.
+const RE_TF_ECDSA = /(?<![\w"-])"?algorithm"?\s*[:=]\s*"(?:ECDSA|EC_SIGN_[A-Z0-9_]+)"/g;
+// AWS KMS customer master key specs.
+const RE_TF_KMS_RSA = /(?<![\w"-])"?customer_master_key_spec"?\s*[:=]\s*"RSA_\d+"/g;
+const RE_TF_KMS_EC = /(?<![\w"-])"?customer_master_key_spec"?\s*[:=]\s*"ECC_[A-Z0-9_]+"/g;
+// Azure Key Vault key type (incl. the `-HSM` variants).
+const RE_TF_AZ_RSA = /(?<![\w"-])"?key_type"?\s*[:=]\s*"RSA(?:-HSM)?"/g;
+const RE_TF_AZ_EC = /(?<![\w"-])"?key_type"?\s*[:=]\s*"EC(?:-HSM)?"/g;
+
+const RULE_TF_RSA: RuleMeta = {
+  id: "tf-rsa-key",
+  title: "Terraform RSA key",
+  description: "Terraform tls_private_key / KMS RSA key material",
+  category: "kem",
+  severity: "high",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message: "Terraform provisions a classical RSA key, which is not quantum-safe.",
+  remediation: "Plan migration to PQC (ML-KEM-768 for encryption, ML-DSA-65 for signatures).",
+};
+const RULE_TF_ECDSA: RuleMeta = {
+  id: "tf-ecdsa-key",
+  title: "Terraform ECDSA key",
+  description: "Terraform tls_private_key / KMS EC signing key",
+  category: "signature",
+  severity: "high",
+  confidence: "high",
+  algorithm: "ECDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message: "Terraform provisions a classical ECDSA key, forgeable by a quantum attacker.",
+  remediation: "ML-DSA-65 (FIPS 204) or SLH-DSA (FIPS 205).",
+};
+const RULE_TF_KMS_RSA: RuleMeta = {
+  id: "tf-kms-rsa",
+  title: "Terraform AWS KMS RSA CMK",
+  description: 'Terraform aws_kms_key customer_master_key_spec = "RSA_*"',
+  category: "kem",
+  severity: "high",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "Terraform provisions a classical RSA KMS customer master key (harvest-now-decrypt-later exposed for encryption CMKs).",
+  remediation: "Plan migration to PQC as cloud KMS adds ML-KEM / ML-DSA key specs.",
+};
+const RULE_TF_KMS_EC: RuleMeta = {
+  id: "tf-kms-ec",
+  title: "Terraform AWS KMS EC CMK",
+  description: 'Terraform aws_kms_key customer_master_key_spec = "ECC_*"',
+  category: "key-exchange",
+  severity: "high",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "Terraform provisions a classical EC KMS customer master key; EC keys feed ECDSA signatures and ECDH key agreement (the ECDH path is harvest-now-decrypt-later exposed).",
+  remediation:
+    "For key agreement: hybrid X25519MLKEM768 (ML-KEM-768). For signatures: ML-DSA-65 (FIPS 204).",
+};
+const RULE_TF_AZ_RSA: RuleMeta = {
+  id: "tf-keyvault-rsa",
+  title: "Terraform Azure Key Vault RSA key",
+  description: 'Terraform azurerm_key_vault_key key_type = "RSA"',
+  category: "kem",
+  severity: "high",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message: "Terraform provisions a classical RSA Azure Key Vault key, which is not quantum-safe.",
+  remediation: "Plan migration to PQC (ML-KEM-768 / ML-DSA-65).",
+};
+const RULE_TF_AZ_EC: RuleMeta = {
+  id: "tf-keyvault-ec",
+  title: "Terraform Azure Key Vault EC key",
+  description: 'Terraform azurerm_key_vault_key key_type = "EC"',
+  category: "key-exchange",
+  severity: "high",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "Terraform provisions a classical EC Azure Key Vault key; EC keys feed ECDSA signatures and ECDH key agreement (the ECDH path is harvest-now-decrypt-later exposed).",
+  remediation:
+    "For key agreement: hybrid X25519MLKEM768 (ML-KEM-768). For signatures: ML-DSA-65 (FIPS 204).",
+};
+
+/** Detects classical asymmetric crypto provisioned in Terraform / OpenTofu. */
+export const terraformDetector: Detector = {
+  id: "terraform-crypto",
+  description: "Classical asymmetric crypto provisioned by Terraform / OpenTofu (IaC)",
+  scope: "config",
+  language: "any",
+  rules: [
+    RULE_TF_RSA,
+    RULE_TF_ECDSA,
+    RULE_TF_KMS_RSA,
+    RULE_TF_KMS_EC,
+    RULE_TF_AZ_RSA,
+    RULE_TF_AZ_EC,
+  ],
+  appliesTo: (f) => hasExtension(f, TF_EXTENSIONS),
+  detect({ file, content }): Finding[] {
+    const findings: Finding[] = [];
+    const add = (re: RegExp, rule: RuleMeta) =>
+      eachMatch(re, content, (m) =>
+        findings.push(
+          findingFromRule(rule, { file, content, index: m.index, matchLength: m[0].length }),
+        ),
+      );
+    add(RE_TF_RSA, RULE_TF_RSA);
+    add(RE_TF_ECDSA, RULE_TF_ECDSA);
+    add(RE_TF_KMS_RSA, RULE_TF_KMS_RSA);
+    add(RE_TF_KMS_EC, RULE_TF_KMS_EC);
+    add(RE_TF_AZ_RSA, RULE_TF_AZ_RSA);
+    add(RE_TF_AZ_EC, RULE_TF_AZ_EC);
+    return findings;
+  },
+};

package/src/detectors/vpn.ts

@@ -0,0 +1,131 @@
+/**
+ * Config detector: classical key exchange in network transport / VPN config —
+ * WireGuard, IPsec (strongSwan), and OpenSSH server config. These are the tunnels
+ * carrying "communication between things"; their key exchange is classical and so
+ * harvest-now-decrypt-later exposed (a recorded tunnel is decryptable once a CRQC
+ * exists).
+ *
+ * Covered (each gated so it only fires inside the relevant config):
+ *  - **WireGuard** — `[Interface]`/`[Peer]` sections with `PrivateKey`/`PublicKey`.
+ *    WireGuard's Noise handshake is Curve25519 with NO standard PQC option, so this
+ *    is an especially sharp finding: it cannot be made quantum-safe without a
+ *    tunnel-wrapping layer. The private key is treated as sensitive key material.
+ *  - **IPsec / strongSwan** — IKE/ESP proposals naming classical DH groups
+ *    (`modp*` = finite-field DH, `ecp*` = ECDH).
+ *  - **sshd_config / ssh_config** — a `KexAlgorithms` line that offers no PQC hybrid
+ *    KEX (`sntrup761x25519-*`, `mlkem768x25519-*`). If a PQC KEX IS listed the line
+ *    is left alone, so a hardened server stays silent.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import { eachMatch, findingFromRule } from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+const RE_WG_KEY = /\b(?:PrivateKey|PublicKey)\s*=\s*[A-Za-z0-9+/]{42,}=/g;
+const RE_IPSEC_MODP = /\bmodp\d+\b/gi;
+const RE_IPSEC_ECP = /\becp\d+(?:bp)?\b/gi;
+const RE_SSHD_KEX = /^[ \t]*KexAlgorithms[ \t]+([^\n]*)/gm;
+
+const RULE_WG: RuleMeta = {
+  id: "net-wireguard-x25519",
+  title: "WireGuard Curve25519 key",
+  description: "WireGuard [Interface]/[Peer] key — Curve25519 Noise handshake (no PQC option)",
+  category: "key-exchange",
+  severity: "high",
+  confidence: "high",
+  algorithm: "X25519",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  sensitive: true,
+  message:
+    "WireGuard tunnel keyed by classical Curve25519 (Noise); WireGuard has no standard post-quantum KEM, so the tunnel is harvest-now-decrypt-later exposed until wrapped by a PQC layer.",
+  remediation:
+    "Wrap the tunnel in a PQC-hybrid transport (e.g. a TLS 1.3 X25519MLKEM768 layer) or track WireGuard PQC proposals; rotate keys when available.",
+};
+const RULE_IPSEC_DH: RuleMeta = {
+  id: "net-ipsec-modp-dh",
+  title: "IPsec classical DH group (modp)",
+  description: "IPsec/strongSwan IKE/ESP proposal names a finite-field DH group (modp*)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "DH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "IPsec proposal uses a classical finite-field Diffie-Hellman group (modp*); the tunnel key exchange is harvest-now-decrypt-later exposed.",
+  remediation: "Add a PQC/hybrid IKE proposal (ML-KEM) as your IPsec stack supports it.",
+};
+const RULE_IPSEC_EC: RuleMeta = {
+  id: "net-ipsec-ecp-ecdh",
+  title: "IPsec classical ECDH group (ecp)",
+  description: "IPsec/strongSwan IKE/ESP proposal names an elliptic-curve DH group (ecp*)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "IPsec proposal uses a classical elliptic-curve Diffie-Hellman group (ecp*); the tunnel key exchange is harvest-now-decrypt-later exposed.",
+  remediation:
+    "Add a PQC/hybrid IKE proposal (X25519MLKEM768 / ML-KEM) as your IPsec stack supports it.",
+};
+const RULE_SSHD_KEX: RuleMeta = {
+  id: "net-sshd-classical-kex",
+  title: "SSH server offers no PQC key exchange",
+  description:
+    "sshd_config KexAlgorithms lists only classical key exchange (no sntrup761/mlkem768)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "SSH server's KexAlgorithms offers only classical key exchange (no sntrup761x25519 / mlkem768x25519); sessions are harvest-now-decrypt-later exposed.",
+  remediation: "Add a PQC hybrid KEX: sntrup761x25519-sha512@openssh.com or mlkem768x25519-sha256.",
+};
+
+/** True when a KexAlgorithms value already offers a post-quantum hybrid KEX. */
+function offersPqKex(kexLine: string): boolean {
+  return /sntrup761x25519|mlkem768/.test(kexLine);
+}
+
+/** Detects classical key exchange in WireGuard / IPsec / sshd network config. */
+export const vpnDetector: Detector = {
+  id: "network-transport-crypto",
+  description: "Classical key exchange in network transport / VPN config (WireGuard, IPsec, sshd)",
+  scope: "config",
+  language: "any",
+  rules: [RULE_WG, RULE_IPSEC_DH, RULE_IPSEC_EC, RULE_SSHD_KEX],
+  appliesTo: (f) => {
+    const lower = f.toLowerCase();
+    const base = lower.split("/").pop() ?? lower;
+    return lower.endsWith(".conf") || base === "sshd_config" || base === "ssh_config";
+  },
+  detect({ file, content }): Finding[] {
+    const findings: Finding[] = [];
+    const push = (rule: RuleMeta, index: number, length: number) =>
+      findings.push(findingFromRule(rule, { file, content, index, matchLength: length }));
+
+    // WireGuard: gated to a WireGuard config section.
+    if (content.includes("[Interface]") || content.includes("[Peer]")) {
+      eachMatch(RE_WG_KEY, content, (m) => push(RULE_WG, m.index, m[0].length));
+    }
+
+    // IPsec / strongSwan: gated to a proposal assignment.
+    if (/\b(?:ike|esp|proposals?|keyexchange)\s*=/i.test(content)) {
+      eachMatch(RE_IPSEC_MODP, content, (m) => push(RULE_IPSEC_DH, m.index, m[0].length));
+      eachMatch(RE_IPSEC_ECP, content, (m) => push(RULE_IPSEC_EC, m.index, m[0].length));
+    }
+
+    // sshd_config / ssh_config: KexAlgorithms line with no PQC hybrid offered.
+    const base = file.toLowerCase().split("/").pop() ?? "";
+    if (base === "sshd_config" || base === "ssh_config") {
+      eachMatch(RE_SSHD_KEX, content, (m) => {
+        if (!offersPqKex(m[1])) push(RULE_SSHD_KEX, m.index, m[0].length);
+      });
+    }
+    return findings;
+  },
+};

package/src/evidence.ts

@@ -0,0 +1,135 @@
+/**
+ * ISO/IEC 27001:2022 Annex A 8.24 evidence-chain export
+ * (docs/compliance/iso27001-a8.24-evidence.md).
+ *
+ * Emits a self-describing readiness report bundling the scan result, crypto
+ * inventory, and CycloneDX CBOM, plus an attestation carrying a DETERMINISTIC
+ * content hash — the same scan over the same commit + config yields the same
+ * hash (the volatile scan timestamp is deliberately excluded from the hashed
+ * body). Signing + RFC-3161 timestamping are left to an EXTERNAL, vetted signer
+ * (ADR-0004: this project performs no cryptography itself — it orchestrates a
+ * signer, it does not implement one). SHA-256 here is an integrity hash (a Node
+ * built-in), not an asymmetric primitive.
+ *
+ * Honesty boundary: this artifact is EVIDENCE for A.8.24, not the control. The
+ * organization still owns the cryptography policy, key management, and the
+ * conformance judgment. A clean scan is the absence of detected candidates, not
+ * proof of quantum-safety (qScan is lexical). See docs/COMPLIANCE.md §3.
+ */
+import { createHash } from "node:crypto";
+
+import type { ScanResult } from "./types.js";
+import { toCbom } from "./cbom.js";
+import { VERSION } from "./version.js";
+import { buildPolicyMapping } from "./policy.js";
+import type { CryptoPolicy, PolicyMapping } from "./policy.js";
+
+/** Stable per-finding record for the evidence body (deterministic per commit). */
+export interface EvidenceFinding {
+  ruleId: string;
+  algorithm?: string;
+  severity: string;
+  hndl: boolean;
+  file: string;
+  line: number;
+}
+
+export interface ReadinessReport {
+  reportType: "quantakrypto-readiness";
+  specVersion: 1;
+  subject: {
+    repository: string | null;
+    commit: string | null;
+    scannedRoot: string;
+    scanTimeUtc: string;
+  };
+  tool: { name: "qScan"; version: string };
+  inventory: ScanResult["inventory"];
+  findings: EvidenceFinding[];
+  /** §4 policy verdicts, present only when a crypto policy was supplied. */
+  policyMapping?: PolicyMapping;
+  cbom: unknown;
+  attestation: {
+    /** sha256 over the canonicalized deterministic body (excludes scanTimeUtc). */
+    contentHash: string;
+    /** RFC-3161 / transparency-log token — filled by an external signer. */
+    timestamp: null;
+    /** Detached signature over `contentHash` — filled by an external signer. */
+    signature: null;
+  };
+}
+
+/** Canonical JSON: object keys sorted recursively, so the hash is reproducible. */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      out[k] = canonicalize((value as Record<string, unknown>)[k]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export interface ReadinessReportOptions {
+  /** Repository URL (e.g. from `GITHUB_REPOSITORY`); omitted → null. */
+  repository?: string;
+  /** Full commit SHA (e.g. from `GITHUB_SHA`); omitted → null. */
+  commit?: string;
+  /** Optional org cryptography policy — adds the §4 `policyMapping` verdicts. */
+  policy?: CryptoPolicy;
+}
+
+/**
+ * Build the A.8.24 readiness report for a scan result. The attestation's
+ * `contentHash` covers everything EXCEPT the scan timestamp and the attestation
+ * block itself, so re-running the same scan on the same commit is verifiable.
+ */
+export function buildReadinessReport(
+  result: ScanResult,
+  opts: ReadinessReportOptions = {},
+): ReadinessReport {
+  const findings: EvidenceFinding[] = result.findings.map((f) => ({
+    ruleId: f.ruleId,
+    ...(f.algorithm ? { algorithm: f.algorithm } : {}),
+    severity: f.severity,
+    hndl: f.hndl,
+    file: f.location.file,
+    line: f.location.line,
+  }));
+
+  // The CBOM is a deterministic *view* of the (hashed) findings + inventory, but
+  // its CycloneDX envelope carries a volatile timestamp/serial — so it is
+  // EXCLUDED from the hashed body (its integrity follows from its hashed inputs)
+  // to keep the content hash reproducible across scan runs on the same commit.
+  // §4: if the org supplied a crypto policy, attest the per-finding verdicts too.
+  // Deterministic (same findings + policy → same mapping), so it is hashed.
+  const policyMapping = opts.policy ? buildPolicyMapping(result.findings, opts.policy) : undefined;
+
+  const hashableBody = {
+    reportType: "quantakrypto-readiness",
+    specVersion: 1,
+    subject: {
+      repository: opts.repository ?? null,
+      commit: opts.commit ?? null,
+      scannedRoot: result.root,
+    },
+    tool: { name: "qScan", version: VERSION },
+    inventory: result.inventory,
+    findings,
+    ...(policyMapping ? { policyMapping } : {}),
+  };
+  const contentHash =
+    "sha256:" +
+    createHash("sha256")
+      .update(JSON.stringify(canonicalize(hashableBody)))
+      .digest("hex");
+
+  return {
+    ...hashableBody,
+    subject: { ...hashableBody.subject, scanTimeUtc: result.finishedAt },
+    cbom: toCbom(result),
+    attestation: { contentHash, timestamp: null, signature: null },
+  } as ReadinessReport;
+}

package/src/index.ts

@@ -104,12 +104,21 @@ export { vulnerableDependencies, DEP_VULNERABLE_RULE, isManifestFile } from "./d
 export { SEVERITY_ORDER, severityRank, meetsThreshold, sarifLevel } from "./severity.js";
 
 // Reporters.
-export { toSarif, toJson, formatSummary } from "./report.js";
+export { toSarif, toJson, formatSummary, formatTierGuidance } from "./report.js";
 export type { ReportOptions } from "./report.js";
 
 // CycloneDX 1.6 cryptographic bill of materials (CBOM) export.
 export { toCbom } from "./cbom.js";
 export type { CycloneDxBom, CbomComponent } from "./cbom.js";
+// Merge multiple CBOMs (code + infra + live endpoints) into one combined BOM.
+export { mergeCboms } from "./cbom-merge.js";
+// ISO/IEC 27001 A.8.24 evidence-chain readiness report.
+export { buildReadinessReport } from "./evidence.js";
+export type { ReadinessReport, EvidenceFinding, ReadinessReportOptions } from "./evidence.js";
+
+// Cryptography policy → per-finding verdicts (A.8.24 evidence §4).
+export { buildPolicyMapping, parseCryptoPolicy, verdictForAlgorithm } from "./policy.js";
+export type { CryptoPolicy, PolicyVerdict, PolicyMapping, PolicyFindingVerdict } from "./policy.js";
 
 // Remediation lookup (family + tier-aware) and stateful-HBS guidance.
 export {
@@ -117,10 +126,15 @@ export {
   remediationForTier,
   TIER_PARAMS,
   STATEFUL_HBS_NOTE,
+  PQC_TRANSITION_NOTE,
   statefulHbsApplies,
 } from "./remediation.js";
 export type { SecurityTier } from "./remediation.js";
 
+// Post-quantum standards source of truth + review cadence.
+export { PQC_STANDARDS, standardsReviewStatus } from "./standards.js";
+export type { PqcStandards, StandardsCitation, StandardsReviewStatus } from "./standards.js";
+
 // CWE identifier constants.
 export {
   CWE_BROKEN_CRYPTO,