@quantakrypto/core 0.4.4 → 0.6.0

package/src/detectors/source.ts

@@ -32,6 +32,7 @@ import {
   DOC_EXTENSIONS,
   JWT_HOST_EXTENSIONS,
   eachMatch,
+  enclosingObject,
   findingFromRule,
   hasExtension,
   nearSortedCall,
@@ -46,6 +47,15 @@ import { CWE_BROKEN_CRYPTO, CWE_CERT_VALIDATION, CWE_WEAK_STRENGTH } from "../cw
 // (ordered alternation would otherwise match `rsa` and reject the `-pss` tail).
 const RE_GENERATE_KEYPAIR =
   /generateKeyPair(?:Sync)?\s*\(\s*['"`](rsa-pss|rsa|ec|dsa|dh|x25519|x448|ed25519|ed448)['"`]/g;
+// Variable-typed key generation: `generateKeyPair(kind, …)` where the algorithm
+// argument is an IDENTIFIER (a variable), not a quoted literal, so the concrete
+// family is unknown at scan time but a classical key is still being generated.
+// The lookbehind anchors the call to a word boundary so it does not fire inside
+// a longer identifier (e.g. `myGenerateKeyPair(`); the first argument must be a
+// bare identifier immediately followed by `,` or `)` so a quoted-literal call
+// (handled by RE_GENERATE_KEYPAIR) never matches here.
+const RE_GENERATE_KEYPAIR_VAR =
+  /(?<![\w$])generateKeyPair(?:Sync)?\s*\(\s*([A-Za-z_$][\w$]*)\s*[,)]/g;
 
 /** Per-key-type classification for `generateKeyPair(Sync)('<type>', …)`. Hoisted
  * to module scope so the direct matcher AND the import-alias pass (below) share
@@ -176,6 +186,20 @@ function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 const RE_CREATE_SIGN_VERIFY = /create(?:Sign|Verify)\s*\(/g;
+// Computed-member (bracket) access to a Node `crypto` method:
+// `crypto['createSign'](…)`, `c["createECDH"](…)`. Bracket access defeats the
+// dotted-call regexes above (which require `name(`), so match a quoted method
+// name inside a `[ '…' ]( ` computed call and route it to the right rule. The
+// method names here take no key-type argument, so no argument parsing is needed;
+// `generateKeyPair(Sync)` bracket access is handled separately (it carries the
+// key-type literal). None of these overlap the dotted regexes (those require the
+// name immediately before `(`, whereas here it is followed by a closing quote).
+const RE_BRACKET_CRYPTO_METHOD =
+  /\[\s*['"`](createSign|createVerify|createECDH|createDiffieHellman|createDiffieHellmanGroup|publicEncrypt|privateDecrypt)['"`]\s*\]\s*\(/g;
+// `crypto['generateKeyPairSync']('rsa', …)`: bracket access carrying the quoted
+// key-type literal, classified exactly like the dotted `generateKeyPair` call.
+const RE_BRACKET_KEYGEN =
+  /\[\s*['"`]generateKeyPair(?:Sync)?['"`]\s*\]\s*\(\s*['"`](rsa-pss|rsa|ec|dsa|dh|x25519|x448|ed25519|ed448)['"`]/g;
 // One-shot crypto.sign/verify(algorithm, data, key). A LOOKBEHIND (not a
 // consumed char) anchors it so it doesn't fire inside identifiers like `assign(`
 // or `createSign(` (handled by the dedicated createSign/createVerify rule) —
@@ -225,11 +249,15 @@ const RE_TLS_REJECT = /rejectUnauthorized\s*:\s*false/g;
 // Hardened cipher regex: bounded spans (no unbounded `[^'"`]*` straddling the
 // alternation), single-quote-style anchoring removed in favour of {0,256} bounds
 // so worst-case backtracking is linear in the bound, not the file (P0-6).
-// The `(?<![!-])` lookbehind skips OpenSSL EXCLUSION syntax — `!MD5` / `-RC4`
-// DISABLE those ciphers, so a hardened list like `...:!aNULL:!MD5:!RC4` must not
-// be flagged as weak (audit: crypto #7). A genuinely-enabled `RC4` still matches.
+// Skip OpenSSL EXCLUSION syntax — `!MD5` / `:-RC4` / `!ECDHE-RSA-RC4-SHA` DISABLE
+// those ciphers, so a hardened list must not be flagged as weak (audit: crypto #7). The
+// single variable-length lookbehind walks back over the suite-name chars to the
+// ELEMENT boundary (`:` / whitespace / comma / quote / start) and rejects the match
+// when that element begins with `!` or `-` — covering a bare `!RC4`, a space-separated
+// `HIGH !RC4`, and a full-suite `!ECDHE-RSA-RC4-SHA`. The intra-name hyphen in a
+// genuinely-enabled `ECDHE-RSA-RC4-SHA` (no leading `!`/`-`) still matches.
 const RE_TLS_WEAK_CIPHER =
-  /ciphers\s*:\s*['"`][^'"`\n]{0,256}?\b(?<![!-])(RC4|DES|3DES|MD5|NULL|EXPORT|aNULL|eNULL)\b[^'"`\n]{0,256}?['"`]/gi;
+  /ciphers\s*:\s*['"`][^'"`\n]{0,256}?\b(?<![:'"`,\s]\s*[!-][\w-]{0,64})(RC4|DES|3DES|MD5|NULL|EXPORT|aNULL|eNULL)\b[^'"`\n]{0,256}?['"`]/gi;
 
 /* -------------------------------------------------------------------------- */
 /* Node.js `crypto` module                                                    */
@@ -370,6 +398,28 @@ const nodeCryptoDetector: Detector = {
       pushKeygenFinding(findings, m[1], file, content, m.index, m[0].length);
     });
 
+    // generateKeyPair(Sync)(<variable>, …): key type passed as a variable, so the
+    // family is unknown; emit the generic keygen rule (unknown / key-exchange /
+    // HNDL-conservative) rather than missing the classical key generation.
+    eachMatch(RE_GENERATE_KEYPAIR_VAR, content, (m) => {
+      findings.push(
+        findingFromRule(
+          RULE_NODE_KEYGEN,
+          { file, content, index: m.index, matchLength: m[0].length },
+          {
+            title: "Classical key generation (variable key type)",
+            message:
+              "Generates a classical asymmetric key pair (key type passed as a variable), which is not quantum-safe.",
+          },
+        ),
+      );
+    });
+
+    // Bracket (computed-member) key generation: crypto['generateKeyPairSync']('rsa').
+    eachMatch(RE_BRACKET_KEYGEN, content, (m) => {
+      pushKeygenFinding(findings, m[1], file, content, m.index, m[0].length);
+    });
+
     // Import-alias resolution: follow `import { generateKeyPairSync as gk }` (and
     // the CommonJS destructure-rename) so an aliased call still detects. Only the
     // keygen / ECDH / DH constructors are resolved — their classification is
@@ -427,6 +477,23 @@ const nodeCryptoDetector: Detector = {
       );
     });
 
+    // Bracket (computed-member) access to argument-free crypto methods:
+    // crypto['createSign'](…), c["createECDH"](…). Route each to its rule.
+    eachMatch(RE_BRACKET_CRYPTO_METHOD, content, (m) => {
+      const loc = { file, content, index: m.index, matchLength: m[0].length };
+      const method = m[1];
+      if (method === "createSign" || method === "createVerify") {
+        findings.push(findingFromRule(RULE_NODE_SIGN, loc));
+      } else if (method === "createECDH") {
+        findings.push(findingFromRule(RULE_NODE_ECDH, loc));
+      } else if (method === "publicEncrypt" || method === "privateDecrypt") {
+        findings.push(findingFromRule(RULE_NODE_RSA_ENCRYPT, loc));
+      } else {
+        // createDiffieHellman / createDiffieHellmanGroup: finite-field DH.
+        findings.push(findingFromRule(RULE_NODE_DH, loc));
+      }
+    });
+
     // One-shot crypto.sign(algorithm, data, key) / crypto.verify(...) (Node ≥ 12).
     eachMatch(RE_ONESHOT_SIGN_VERIFY, content, (m) => {
       findings.push(
@@ -561,7 +628,9 @@ const webCryptoDetector: Detector = {
         algorithm = name === "X448" ? "X448" : "X25519";
         category = "key-exchange";
         hndl = true;
-        severity = "low"; // modern but classical
+        // `medium`, aligned with X25519/X448 key agreement in node/rust/go — HNDL-exposed
+        // key agreement scores the same regardless of which surface uses it.
+        severity = "medium";
       } else if (name === "ED25519" || name === "ED448") {
         algorithm = "EdDSA";
         category = "signature";
@@ -818,8 +887,21 @@ const jwtDetector: Detector = {
   detect({ file, content }): Finding[] {
     const findings: Finding[] = [];
 
+    // Deferral guards against double-counting:
+    //  - webCryptoDetector owns a quoted `RSA-OAEP`/`ECDH-ES` sitting next to a
+    //    `subtle.*(` call (it matches the `RSA-OAEP`/`ECDH` name). Collect the subtle
+    //    call offsets so the JOSE key-management loops can skip those. (In non-JS host
+    //    files there are no subtle calls, so nothing is skipped.)
+    //  - jwkDetector owns any alg/`kty` that lives inside a JWK object; skip a token
+    //    whose enclosing `{…}` carries a `"kty"` so a JWK's own `alg` is not counted by
+    //    both detectors. Mirrors the same guard jose.ts applies for other languages.
+    const subtleCalls: number[] = [];
+    eachMatch(RE_SUBTLE_CALL, content, (m) => subtleCalls.push(m.index));
+    const inJwk = (index: number): boolean => enclosingObject(content, index).includes('"kty"');
+
     // Classical JWS signature alg tokens. Anchored to quotes to avoid words.
     eachMatch(RE_JWT_ALG, content, (m) => {
+      if (inJwk(m.index)) return; // jwk-{rsa,ec,eddsa} owns a JWK's own alg
       const alg = m[1];
       let algorithm: Finding["algorithm"];
       if (alg.startsWith("RS") || alg.startsWith("PS")) algorithm = "RSA";
@@ -840,6 +922,8 @@ const jwtDetector: Detector = {
 
     // JOSE ECDH-ES key agreement (and ECDH-ES+A*KW) — confidentiality, HNDL.
     eachMatch(RE_JOSE_ECDH, content, (m) => {
+      if (inJwk(m.index)) return; // jwk-ec owns a JWK's own alg
+      if (nearSortedCall(subtleCalls, m.index, 400)) return; // webcrypto owns it
       findings.push(
         findingFromRule(
           RULE_JOSE_ECDH,
@@ -854,6 +938,10 @@ const jwtDetector: Detector = {
 
     // JOSE RSA key transport (RSA-OAEP / RSA1_5) — classical RSA encryption, HNDL.
     eachMatch(RE_JOSE_KEM, content, (m) => {
+      if (inJwk(m.index)) return; // jwk-rsa owns a JWK's own alg
+      // webCryptoDetector's regex matches `RSA-OAEP` but NOT `RSA1_5`, so only defer the
+      // OAEP form near a subtle call — deferring RSA1_5 would drop it entirely.
+      if (m[1].startsWith("RSA-OAEP") && nearSortedCall(subtleCalls, m.index, 400)) return;
       findings.push(
         findingFromRule(
           RULE_JOSE_RSA_OAEP,
@@ -981,6 +1069,21 @@ const RE_CERT_SIG_ALG =
 const RE_SSH_KEX =
   /\b(diffie-hellman-group(?:1|14|15|16|17|18)(?:-sha1|-sha256|-sha512)?|diffie-hellman-group-exchange-sha(?:1|256)|ecdh-sha2-nistp(?:256|384|521)|curve25519-sha256)\b/g;
 
+/**
+ * True when the match at `index` sits inside a DOCUMENTATION field value — a
+ * `description` / `help` / `summary` / `doc` / `comment` / `note` assignment
+ * (`key = "…"` or `key: "…"`), as used by Terraform/Packer variable descriptions,
+ * JSON-schema docs, etc. Classical KEX/cipher algorithm names LISTED in such a field
+ * are prose ("acceptable values include ecdh-sha2-nistp256, …"), not an active
+ * setting, so a transport-token rule must not fire on them. Scans the current line's
+ * prefix only (cheap; the common single-line description case).
+ */
+function inDocFieldValue(content: string, index: number): boolean {
+  const lineStart = content.lastIndexOf("\n", index - 1) + 1;
+  const prefix = content.slice(lineStart, index);
+  return /\b(?:description|help|summary|doc|comment|note)\b\s*[:=]/i.test(prefix);
+}
+
 // A bare key-type token (`ssh-rsa`, `ssh-ed25519`, …) is real SSH crypto only
 // when it is EITHER (a) followed by base64 key material — an actual
 // authorized_keys / known_hosts entry — OR (b) one of ≥2 DISTINCT ssh key/host-key
@@ -1128,6 +1231,7 @@ const sshCertDetector: Detector = {
 
     // SSH key-exchange algorithm identifiers (finite-field DH / ECDH / X25519).
     eachMatch(RE_SSH_KEX, content, (m) => {
+      if (inDocFieldValue(content, m.index)) return; // names listed in a doc string
       const tok = m[1];
       const algorithm: Finding["algorithm"] = tok.startsWith("diffie-hellman")
         ? "DH"
@@ -1196,6 +1300,7 @@ const tlsClassicalKexDetector: Detector = {
   detect({ file, content }): Finding[] {
     const findings: Finding[] = [];
     eachMatch(RE_TLS_CLASSICAL_KEX, content, (m) => {
+      if (inDocFieldValue(content, m.index)) return; // names listed in a doc string
       const tok = m[0];
       const algorithm: Finding["algorithm"] = tok.includes("ECDH") ? "ECDH" : "DH";
       findings.push(

package/src/detectors/spire.ts

@@ -0,0 +1,143 @@
+/**
+ * Config detector: classical key types configured for SPIFFE X.509 SVIDs in
+ * SPIRE server/agent configuration (HCL, and the `.conf`/YAML/JSON variants
+ * SPIRE deployments ship).
+ *
+ * SPIRE is the reference SPIFFE implementation: it issues each workload a
+ * short-lived X.509-SVID certificate, signed by the SPIRE server's CA (itself
+ * often chained to an UpstreamAuthority). The SVID leaf key and the CA signing
+ * key are configured by explicit key-type strings:
+ *  - server `ca_key_type = "rsa-2048" | "rsa-4096" | "ec-p256" | "ec-p384"` —
+ *    the CA that signs every workload SVID in the trust domain (the identity
+ *    ROOT: forge this and you forge the whole trust domain).
+ *  - agent/server `svid_key_type = "rsa-2048" | "ec-p256"` — the per-workload
+ *    leaf key type.
+ *  - per-plugin `key_type = "rsa-2048" | "ec-p256"` on UpstreamAuthority /
+ *    KeyManager plugins.
+ *
+ * These are SIGNING / identity keys, not confidentiality keys: an SVID X.509
+ * signature is verified, never used to wrap harvestable ciphertext. So there is
+ * nothing to "harvest now, decrypt later" — `hndl: false` — but every SVID
+ * signature (and the CA signature over it) becomes FORGEABLE the moment a
+ * cryptographically-relevant quantum computer (CRQC) exists, letting an attacker
+ * mint certificates for any SPIFFE ID in the trust domain. Findings are
+ * therefore `category: "certificate"` (X.509 / PKI material), `severity:
+ * "medium"`, `confidence: "high"`.
+ *
+ * Algorithm mapping (SPIRE key-type value → {@link AlgorithmFamily}):
+ *  - `rsa-2048` / `rsa-4096` / any `rsa-*`  → RSA
+ *  - `ec-p256` / `ec-p384` / `ecdsa`        → ECDSA
+ *
+ * Match shape: the key-type attribute name (`ca_key_type`, `svid_key_type`, or
+ * the bare per-plugin `key_type`) followed by `=`/`:` and a quoted value, in
+ * both HCL (`=`) and YAML/JSON (`:`) forms. The `\b(?:ca_|svid_)?key_type\b`
+ * anchor covers all three names in one pattern — the leading `\b` won't fire
+ * inside `ca_key_type`/`svid_key_type` for the bare `key_type` alternative
+ * because `_` is a word character, so those longer names are matched whole.
+ *
+ * Fast reject: `detect()` bails unless the file carries a SPIFFE/SPIRE-specific
+ * marker (`spiffe`, `spire`, the distinctive `ca_key_type`, or `svid`). A bare
+ * `key_type = "rsa-2048"` is deliberately NOT a sufficient marker — `key_type`
+ * is a generic attribute (Vault PKI roles, cloud IaC, …), so without a
+ * spiffe/spire/svid/ca_key_type anchor an unrelated config must not fire. This
+ * keeps the generic per-plugin `key_type` rule precise while still catching a
+ * real SPIRE config, which always names its trust domain / server / SVIDs.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import {
+  DOC_EXTENSIONS,
+  eachMatch,
+  findingFromRule,
+  hasExtension,
+  maskCommentLines,
+} from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+// SPIRE config is HCL/conf, but deployments also template it as YAML (Helm
+// values / ConfigMaps) or JSON. Prose (`.md`, …) is excluded in `appliesTo`.
+const SPIRE_EXTENSIONS: readonly string[] = [".conf", ".hcl", ".yaml", ".yml", ".json"];
+
+// The three SPIRE key-type attribute names in one anchor: `ca_key_type`,
+// `svid_key_type`, and the bare per-plugin `key_type`.
+const KEY_ATTR = "(?:ca_|svid_)?key_type";
+// HCL `=`, unquoted YAML `:`, and JSON `"key_type": "..."` assignment forms. The
+// attribute-name and value quotes are BOTH optional (`"?`): HCL uses `key_type =
+// "rsa-2048"`, Helm/YAML uses the unquoted `key_type: rsa-2048`, and JSON quotes
+// the key (`"key_type": "rsa-2048"`) — a required-quote regex missed the latter
+// two entirely. Case-insensitive, though SPIRE writes these lowercase.
+const RE_SPIRE_RSA = new RegExp(`\\b${KEY_ATTR}"?\\s*[:=]\\s*"?rsa-\\d+`, "gi");
+const RE_SPIRE_ECDSA = new RegExp(`\\b${KEY_ATTR}"?\\s*[:=]\\s*"?(?:ec-p\\d+|ecdsa)\\b`, "gi");
+
+const RULE_SPIRE_RSA: RuleMeta = {
+  id: "spire-rsa-key",
+  title: "SPIRE/SPIFFE RSA SVID key type",
+  description: 'SPIRE ca_key_type/svid_key_type/key_type = "rsa-*" (classical X.509-SVID key)',
+  category: "certificate",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "SPIRE issues SPIFFE X.509-SVIDs with a classical RSA key; the SVID (and CA) signatures become forgeable once a CRQC exists, letting an attacker mint identities for the trust domain.",
+  remediation:
+    "SPIFFE/SPIRE has no PQC SVID key type yet — track the SPIFFE roadmap for PQC signature support. Prioritise the SPIRE server ca_key_type: the classical CA is the identity root, so its forgeability compromises every workload SVID.",
+};
+const RULE_SPIRE_ECDSA: RuleMeta = {
+  id: "spire-ec-key",
+  title: "SPIRE/SPIFFE ECDSA SVID key type",
+  description:
+    'SPIRE ca_key_type/svid_key_type/key_type = "ec-p256|ec-p384|ecdsa" (classical X.509-SVID key)',
+  category: "certificate",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "SPIRE issues SPIFFE X.509-SVIDs with a classical ECDSA (P-256/P-384) key; the SVID (and CA) signatures become forgeable once a CRQC exists, letting an attacker mint identities for the trust domain.",
+  remediation:
+    "SPIFFE/SPIRE has no PQC SVID key type yet — track the SPIFFE roadmap for PQC signature support. Prioritise the SPIRE server ca_key_type: the classical CA is the identity root, so its forgeability compromises every workload SVID.",
+};
+
+/**
+ * True when `content` carries a SPIFFE/SPIRE-specific marker. A bare generic
+ * `key_type` is intentionally NOT enough — only `spiffe`/`spire` context, the
+ * distinctive `ca_key_type`, or an `svid` token qualifies — so an unrelated
+ * config that merely sets `key_type = "rsa-2048"` cannot fire.
+ */
+function hasSpireMarker(content: string): boolean {
+  // Word-anchored so `inspired` / `aspire` / a `svid` substring inside a longer
+  // token don't qualify; `ca_key_type` is distinctive enough to match unanchored.
+  return /\b(?:spiffe|spire|svid)\b/i.test(content) || content.includes("ca_key_type");
+}
+
+/** Detects classical key types configured for SPIFFE X.509 SVIDs in SPIRE config. */
+export const spireDetector: Detector = {
+  id: "spire-crypto",
+  description: "Classical key types for SPIFFE X.509 SVIDs in SPIRE server/agent config",
+  scope: "config",
+  language: "any",
+  rules: [RULE_SPIRE_RSA, RULE_SPIRE_ECDSA],
+  // Gate to SPIRE's config extensions, and never run on prose (a README that
+  // describes `ca_key_type = "rsa-2048"` is documentation, not live config).
+  appliesTo: (f) => hasExtension(f, SPIRE_EXTENSIONS) && !hasExtension(f, DOC_EXTENSIONS),
+  detect({ file, content }): Finding[] {
+    if (!hasSpireMarker(content)) return [];
+
+    // Mask whole comment lines (HCL/YAML `#`, HCL/JSON5 `//`) so a commented-out
+    // key-type directive can't fire. Offsets are preserved, so finding
+    // line/column/snippet for the remaining live config stay exact.
+    const scan = maskCommentLines(content, ["#", "//"]);
+    const findings: Finding[] = [];
+    const add = (re: RegExp, rule: RuleMeta) =>
+      eachMatch(re, scan, (m) =>
+        findings.push(
+          findingFromRule(rule, { file, content, index: m.index, matchLength: m[0].length }),
+        ),
+      );
+    add(RE_SPIRE_RSA, RULE_SPIRE_RSA);
+    add(RE_SPIRE_ECDSA, RULE_SPIRE_ECDSA);
+    return findings;
+  },
+};

package/src/detectors/ssh-ca.ts

@@ -0,0 +1,215 @@
+/**
+ * Config detector: classical SSH **certificate-authority** cryptography — the
+ * OpenSSH certificate mechanism, in which a CA key signs host/user certificates
+ * (`*-cert-v01@openssh.com`) that servers and clients then trust in place of
+ * bare public keys.
+ *
+ * This is DIFFERENT from the `ssh-kex-classical` rule in `source.ts`, and from
+ * the `ssh-public-key` rule there — deliberately non-overlapping:
+ *  - `ssh-kex-classical` is about the SSH *key-exchange* (finite-field DH, ECDH,
+ *    curve25519): session-key *agreement*, `category: "key-exchange"`,
+ *    `hndl: true` — a passively-recorded handshake is decryptable once a CRQC
+ *    exists (harvest-now-decrypt-later confidentiality loss).
+ *  - `ssh-public-key` flags bare `ssh-rsa AAAA…` / `ecdsa-sha2-* …` key lines.
+ *  - THIS detector flags the SSH **certificate / CA signing** surface: the
+ *    `*-cert-v01@openssh.com` cert key types, the `@cert-authority` known_hosts
+ *    marker, the `TrustedUserCAKeys` / `HostCertificate` sshd directives, and
+ *    `ssh-keygen -s` (the command that signs a certificate with a CA key).
+ *
+ * WHY it matters for PQC: an SSH certificate is a *signature* made by a CA key
+ * over a principal's public key + validity constraints. There is no
+ * confidentiality to harvest (so `hndl: false`), but every such signature
+ * becomes FORGEABLE the moment a cryptographically-relevant quantum computer
+ * (CRQC) can recover the classical CA private key from its public key. Forging a
+ * CA signature lets an attacker mint host or user certificates that every relying
+ * party accepts — a full trust-root compromise. SSH CA keys are also unusually
+ * long-lived (they are the anchor an entire fleet trusts and are rotated
+ * rarely), so the exposure window is large. Hence `category: "signature"`,
+ * `severity: "medium"`, `confidence: "high"`.
+ *
+ * Two match shapes:
+ *  1. The cert key type, which NAMES the signing algorithm → an accurate
+ *     {@link AlgorithmFamily}:
+ *      - `ssh-rsa-cert-v01@openssh.com`, `rsa-sha2-256/512-cert-v01@openssh.com` → RSA
+ *      - `ecdsa-sha2-nistp256/384/521-cert-v01@openssh.com`                      → ECDSA
+ *      - `ssh-ed25519-cert-v01@openssh.com`                                      → EdDSA
+ *  2. The CA *deployment* directives — `TrustedUserCAKeys` / `HostCertificate`
+ *     (sshd_config) and `ssh-keygen -s` (the CA signing command). These are the
+ *     MOST COMMON way an SSH CA is configured, but they don't name the algorithm
+ *     (that lives in the referenced key file), so they emit the `ssh-ca-config`
+ *     rule with `algorithm: "unknown"` and `confidence: "medium"`.
+ *
+ * Precision:
+ *  - Fast reject: `detect()` bails unless the file carries an SSH-CA marker
+ *    (`cert-v01@openssh.com`, `@cert-authority`, `TrustedUserCAKeys`,
+ *    `HostCertificate`, or `ssh-keygen -s`) — so the algorithm tokens can't be
+ *    reached on unrelated config.
+ *  - The cert-type tokens are the full `*-cert-v01@openssh.com` strings. The
+ *    trailing `-cert-v01@openssh.com` suffix distinguishes a CA certificate type
+ *    from the plain `ssh-rsa` / `ssh-ed25519` public-key tokens handled by
+ *    `ssh-public-key`, so a non-cert `ssh-ed25519 AAAA…` line NEVER fires a cert
+ *    rule here.
+ *  - Comment lines (`#`) are masked with {@link maskCommentLines} (offsets
+ *    preserved) so a commented-out cert line can't fire. Known_hosts
+ *    `@cert-authority` lines start with `@`, not `#`, so masking leaves them
+ *    live — exactly what we want.
+ *  - Doc/prose files are excluded ({@link DOC_EXTENSIONS}), and so are program
+ *    SOURCE files ({@link ANALYZABLE_SOURCE_EXTENSIONS}) — a vendored SSH library
+ *    or constants table that spells a cert type as a string literal is not live
+ *    CA config. SSH CA config lives in extensionless / `.conf` / `.pub` files.
+ *
+ * The matched line frequently carries the CA public key's base64 blob (a
+ * `@cert-authority` known_hosts entry), so findings are marked `sensitive` and
+ * reporters drop the snippet, consistent with `ssh-public-key`.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import {
+  eachMatch,
+  findingFromRule,
+  hasExtension,
+  maskCommentLines,
+  DOC_EXTENSIONS,
+  ANALYZABLE_SOURCE_EXTENSIONS,
+} from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+// --- OpenSSH certificate key types (`*-cert-v01@openssh.com`), by signing family. ---
+// The `\b` after `.com` is a real boundary (`m` is a word char); the leading `\b`
+// keeps `ssh-rsa-cert-v01@…` from matching inside a longer token. RSA covers the
+// legacy `ssh-rsa` cert type plus the SHA-2 RSA cert types (`rsa-sha2-256/512`)
+// OpenSSH emits for RSA CA/host certificates.
+const RE_CERT_RSA = /\b(?:ssh-rsa|rsa-sha2-(?:256|512))-cert-v01@openssh\.com\b/g;
+const RE_CERT_ECDSA = /\becdsa-sha2-nistp(?:256|384|521)-cert-v01@openssh\.com\b/g;
+const RE_CERT_EDDSA = /\bssh-ed25519-cert-v01@openssh\.com\b/g;
+// The canonical CA *deployment* directives — the most common way an SSH CA is
+// configured (sshd_config `TrustedUserCAKeys` / `HostCertificate`, and the CA
+// signing command `ssh-keygen -s`). These name the CA usage but not the algorithm
+// (that lives in the referenced key file), so the finding is `algorithm: "unknown"`.
+const RE_CA_DIRECTIVE = /\bTrustedUserCAKeys\b|\bHostCertificate\b|\bssh-keygen\s+-s\b/g;
+
+const REMEDIATION =
+  "No post-quantum SSH certificate format is standardized yet — track OpenSSH release notes and IETF work on PQC signatures for SSH. SSH CA keys are long-lived trust roots, so plan for their rotation to a PQC signing algorithm (e.g. ML-DSA) as soon as a cert format lands, and keep validity periods short in the interim.";
+
+const RULE_CA_RSA: RuleMeta = {
+  id: "ssh-ca-rsa-cert",
+  title: "SSH certificate authority — RSA signing",
+  description: "OpenSSH RSA certificate key type (ssh-rsa/rsa-sha2-*-cert-v01@openssh.com)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  sensitive: true,
+  message:
+    "SSH certificate uses a classical RSA key type (ssh-rsa/rsa-sha2-*-cert-v01@openssh.com); the CA signature is forgeable once a CRQC can recover the RSA CA key.",
+  remediation: REMEDIATION,
+};
+const RULE_CA_ECDSA: RuleMeta = {
+  id: "ssh-ca-ecdsa-cert",
+  title: "SSH certificate authority — ECDSA signing",
+  description: "OpenSSH ECDSA certificate key type (ecdsa-sha2-nistp*-cert-v01@openssh.com)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  sensitive: true,
+  message:
+    "SSH certificate uses a classical ECDSA key type (ecdsa-sha2-nistp*-cert-v01@openssh.com); the CA signature is forgeable once a CRQC can recover the ECDSA CA key.",
+  remediation: REMEDIATION,
+};
+const RULE_CA_EDDSA: RuleMeta = {
+  id: "ssh-ca-ed25519-cert",
+  title: "SSH certificate authority — EdDSA signing",
+  description: "OpenSSH Ed25519 certificate key type (ssh-ed25519-cert-v01@openssh.com)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "EdDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  sensitive: true,
+  message:
+    "SSH certificate uses a classical Ed25519 key type (ssh-ed25519-cert-v01@openssh.com); modern but still classical — the CA signature is forgeable once a CRQC can recover the Ed25519 CA key.",
+  remediation: REMEDIATION,
+};
+
+const RULE_CA_CONFIG: RuleMeta = {
+  id: "ssh-ca-config",
+  title: "SSH certificate authority configured",
+  description:
+    "OpenSSH CA deployment directive (TrustedUserCAKeys / HostCertificate / ssh-keygen -s)",
+  category: "signature",
+  severity: "medium",
+  // The directive names CA usage, not the algorithm — hence a lower confidence and
+  // an unknown family; the CA key file itself carries the specific algorithm.
+  confidence: "medium",
+  algorithm: "unknown",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "SSH certificate authority is configured (TrustedUserCAKeys / HostCertificate / ssh-keygen -s); the CA signing key is a long-lived classical trust root whose signatures become forgeable once a CRQC exists — verify the CA key's algorithm.",
+  remediation: REMEDIATION,
+};
+
+interface SshCaRule {
+  meta: RuleMeta;
+  re: RegExp;
+}
+
+const SSH_CA_RULES: readonly SshCaRule[] = [
+  { meta: RULE_CA_RSA, re: RE_CERT_RSA },
+  { meta: RULE_CA_ECDSA, re: RE_CERT_ECDSA },
+  { meta: RULE_CA_EDDSA, re: RE_CERT_EDDSA },
+  { meta: RULE_CA_CONFIG, re: RE_CA_DIRECTIVE },
+];
+
+/** True when `content` carries some SSH-CA-specific marker (not just a bare token). */
+function hasSshCaMarker(content: string): boolean {
+  return (
+    content.includes("cert-v01@openssh.com") ||
+    content.includes("@cert-authority") ||
+    content.includes("TrustedUserCAKeys") ||
+    content.includes("HostCertificate") ||
+    content.includes("ssh-keygen -s")
+  );
+}
+
+/**
+ * Detects classical SSH certificate-authority signing (OpenSSH cert key types)
+ * in SSH config, sshd_config, and known_hosts files. Distinct from SSH
+ * key-exchange (`ssh-kex-classical`): this is the certificate SIGNATURE surface.
+ */
+export const sshCaDetector: Detector = {
+  id: "ssh-ca",
+  description: "Classical SSH certificate-authority signing (OpenSSH *-cert-v01@openssh.com)",
+  scope: "config",
+  language: "any",
+  rules: SSH_CA_RULES.map((r) => r.meta),
+  // Apply broadly (SSH CA config lives in many differently-named / extensionless
+  // files: sshd_config, known_hosts, *.pub) but never on prose/docs OR on program
+  // SOURCE files — a vendored SSH library or a constants table that spells out
+  // `ssh-ed25519-cert-v01@openssh.com` as a string literal is not a live CA config.
+  // The strict fast-reject in detect() is the remaining gate.
+  appliesTo: (f) =>
+    !hasExtension(f, DOC_EXTENSIONS) && !hasExtension(f, ANALYZABLE_SOURCE_EXTENSIONS),
+  detect({ file, content }): Finding[] {
+    if (!hasSshCaMarker(content)) return [];
+
+    // Mask `#` comment lines so a commented-out cert line can't fire; offsets are
+    // preserved. `@cert-authority` known_hosts lines start with `@`, not `#`, so
+    // they are intentionally left live.
+    const scan = maskCommentLines(content, ["#"]);
+    const findings: Finding[] = [];
+    for (const { meta, re } of SSH_CA_RULES) {
+      eachMatch(re, scan, (m) =>
+        findings.push(
+          findingFromRule(meta, { file, content, index: m.index, matchLength: m[0].length }),
+        ),
+      );
+    }
+    return findings;
+  },
+};