@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/collectors/secrets.js

@@ -1,19 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/secrets.js
- *
- * Companion collector for the `secrets` playbook. Walks the cwd
- * tree, identifies the artifact files (env / auth-config / ssh-keys /
- * iac-credential-bearers), runs the catalogued regex set against text
- * file contents, and stats permission posture on secret-carrier
- * files. Emits a submission with deterministic signal_overrides per
- * indicator that fired.
- *
- * Scope: any cwd. Cross-platform (Windows / macOS / Linux).
- * Permission-posture indicator only meaningful on POSIX hosts.
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `secrets` playbook: walks the cwd tree, classifies
+ * artifact files, regex-scans text content, and stats permission posture on the
+ * carriers (POSIX only). Interface: lib/collectors/README.md
  */
 
 const fs = require("node:fs");
@@ -22,19 +12,13 @@ const { codeExcludeSet, walkTree, buildEvidenceLocations, lineFromOffset } = req
 
 const COLLECTOR_ID = "secrets";
 
-// Walk depth + exclusion list mirrors the secrets playbook's
-// `look.artifacts[repo-tree].source` declaration. Exclusions come from
-// the shared code-scope policy (dependency caches, build output, VCS +
-// agent/editor scratch including `.claude/`); no secrets-specific extras.
+// Depth and exclusions mirror the secrets playbook's `look.artifacts[repo-tree]`;
+// the exclusions come from the shared code-scope policy.
 const DEFAULT_MAX_DEPTH = 6;
 const DEFAULT_EXCLUDES = codeExcludeSet();
 
-// Path segments that denote test / fixture / example material. Hits
-// scoped exclusively to these paths are downgraded — a private-key
-// block in `cosign-test.key` or a JWT literal in `_test.go` is
-// expected test material, not a real secret. If at least one hit
-// exists outside these paths, the indicator still fires. Mirrors
-// the crypto-codebase collector's isTestPath shape.
+// Hits confined to these paths are downgraded; one hit outside them still fires.
+// Mirrors the crypto-codebase collector's isTestPath.
 const TEST_PATH_SEGMENTS = [
   "/test/", "/tests/", "/spec/", "/specs/", "/__tests__/",
   "/fixtures/", "/fixture/", "/examples/", "/example/",
@@ -47,12 +31,9 @@ function isTestPath(rel) {
   for (const seg of TEST_PATH_SEGMENTS) {
     if (norm.includes(seg)) return true;
   }
-  // foo.test.js / bar.spec.py — dot-separated convention.
   if (/\.(test|spec)\.[a-z]+$/i.test(rel)) return true;
-  // foo_test.go (Go) / bar_test.py (some Python) — underscore convention.
   if (/(?:^|[\\/])[^\\/]+_test\.[a-z]+$/i.test(rel)) return true;
-  // Files whose name itself includes the substring "test" before a
-  // key extension (e.g. cosign-test.key, github-test-token.json).
+  // "test" inside the name itself: cosign-test.key, github-test-token.json.
   if (/-test[-.][^\\/]*$/i.test(rel)) return true;
   return false;
 }
@@ -73,11 +54,8 @@ const AUTH_CONFIG_FILES = new Set([
 
 const SSH_PRIVATE_KEY_FILES = new Set(["id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"]);
 const SSH_PRIVATE_KEY_EXTS = new Set([".pem", ".key", ".p12", ".pfx"]);
-// `.pem` / `.key` are ambiguous: a certificate chain (`fullchain.pem`) or a
-// public trust anchor (`bimi-trust-anchors.pem`) is conventionally `.pem` and
-// carries no private key. A name-only classifier flags these as private keys.
-// `.p12` / `.pfx` are binary keystores (private material by nature) and the
-// id_* names are private SSH keys, so only the PEM extensions are content-gated.
+// `.pem` / `.key` are ambiguous — a cert chain is conventionally `.pem` — so only
+// those two are content-gated; `.p12` / `.pfx` and id_* are private by nature.
 const PEM_PRIVATE_KEY_MARKER = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/;
 const CONTENT_GATED_KEY_EXTS = new Set([".pem", ".key"]);
 function carriesPrivateKey(file) {
@@ -88,15 +66,9 @@ function carriesPrivateKey(file) {
     fd = fs.openSync(file.full, "r");
     const st = fs.fstatSync(fd); // fstat on the open fd — no stat-then-read race
     if (st.size > MAX_FILE_BYTES) return true; // too big to scan → conservative
-    // Read the whole descriptor to EOF. A single readSync may return fewer
-    // bytes than requested (a short read on a network / FUSE / interrupted fd),
-    // which would leave the buffer's tail NUL-padded; if the BEGIN marker sat
-    // past that boundary — e.g. a .pem with a leading `Bag Attributes` /
-    // subject= header block, the default OpenSSL pkcs12→PEM layout — the marker
-    // test would return false and silently drop a real private key. readFileSync
-    // on the open fd loops internally until EOF, so the test always sees the
-    // complete content. Reading from the already-open fd keeps the no-TOCTOU
-    // open→fstat ordering (no second path lookup).
+    // readFileSync on the open fd, never readSync: a short read NUL-pads the tail,
+    // and a BEGIN marker past that boundary (a .pem with a leading `Bag Attributes`
+    // header) would test false and drop a real key. Also preserves open→fstat order.
     const content = fs.readFileSync(fd, "utf8");
     return PEM_PRIVATE_KEY_MARKER.test(content);
   } catch {
@@ -110,37 +82,21 @@ const IAC_EXTS = new Set([".tf", ".tfvars", ".bicep"]);
 const IAC_EXACT = new Set(["terraform.tfstate", "values.yaml", "secret.yaml"]);
 const IAC_GLOB_PREFIX = ["pulumi.", "arm."];
 
-// Indicator regex set — must mirror data/playbooks/secrets.json's
-// detect.indicators[].value embedded patterns. The playbook is the
-// source of truth for what counts as a hit; the collector
-// implements the same patterns so its signal_overrides match what
-// the runner would compute.
-// AWS-published documentation/example access-key IDs. These appear verbatim
-// throughout AWS docs, SDK samples, and countless READMEs, so a literal match
-// is example material, not a leaked credential. `cred-stores` demotes the same
-// value (its FP[0]); secrets.js must too or it false-positives on any README
-// that quotes the AWS docs. The 40-char example secret
-// (`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`) carries the literal `EXAMPLE`
-// token, which the AWS-secret-access-key pattern already requires elsewhere;
-// the access-key ID is the one that needs an explicit allowlist.
+// The patterns and demotions below mirror data/playbooks/secrets.json's
+// detect.indicators[] — the playbook is the source of truth for what counts as a hit.
+// AWS's published example access-key ID appears verbatim across docs and READMEs;
+// `cred-stores` demotes the same value in its FP[0].
 const AWS_EXAMPLE_ACCESS_KEY_IDS = new Set([
   "AKIAIOSFODNN7EXAMPLE",
 ]);
 
-// AWS-published sample secret-access-key (paired with AKIAIOSFODNN7EXAMPLE
-// throughout the AWS docs). aws-secret-access-key false_positive_checks_required[1]
-// demotes this exact value.
+// AWS's published sample secret key; aws-secret-access-key FP[1] demotes it.
 const AWS_EXAMPLE_SECRET_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY";
 
-// Placeholder/fixture substrings the API-key indicators' FP[0] checks demote.
-// A literal `PLACEHOLDER` / `EXAMPLE` / `XXXX` run / a `dummy`/`test` infix
-// marks documentation material rather than a live credential.
+// Substrings the API-key indicators' FP[0] checks demote as documentation material.
 const PLACEHOLDER_RE = /placeholder|example|redacted|dummy|x{4,}|0{6,}|1234567890/i;
 
-// Path segments the per-indicator FP path checks treat as documentation /
-// fixture material in addition to TEST_PATH_SEGMENTS (which already covers
-// /examples/, /fixtures/, /test/ etc.). The secret indicators' FP prose adds
-// /docs/ and quickstart/snippet paths.
+// Documentation paths the FP checks treat as fixture material, atop TEST_PATH_SEGMENTS.
 const DOC_PATH_SEGMENTS = [
   "/docs/", "/doc/", "/sdk-quickstart/", "/quickstart/", "/docs-snippet/",
 ];
@@ -151,13 +107,9 @@ function isDocOrTestPath(rel) {
   return DOC_PATH_SEGMENTS.some((seg) => norm.includes(seg));
 }
 
-// Per-indicator deterministic false_positive_checks_required evaluation.
-// Returns the set of FP-check indices (as strings) the collector can attest
-// for a single hit — i.e. the checks it actually ran and that the hit
-// survives. Indices requiring network reachability or operator judgement are
-// deliberately omitted so the runner honestly downgrades to inconclusive.
-// `value` is the matched credential, `file` the relative path, `window` a
-// few-line context slice around the match.
+// The false_positive_checks_required indices (as strings) this hit survives. Indices
+// needing network reachability or operator judgement are omitted, so the runner
+// downgrades to inconclusive rather than over-attesting. `window` is a context slice.
 function fpIndicesSatisfied(indicatorId, value, file, window) {
   const sat = new Set();
   const notDocPath = !isDocOrTestPath(file);
@@ -165,51 +117,37 @@ function fpIndicesSatisfied(indicatorId, value, file, window) {
     case "aws-secret-access-key": {
       // [0] co-occurrence with an AKIA*/ASIA*/AGPA*/AIDA* id in a 10-line window
       if (/\b(?:AKIA|ASIA|AGPA|AIDA)[0-9A-Z]{12,}\b/.test(window)) sat.add("0");
-      // [1] not the AWS-published sample secret
       if (value !== AWS_EXAMPLE_SECRET_KEY) sat.add("1");
-      // [2] not under examples/ docs/ fixtures/ / a test snapshot
       if (notDocPath) sat.add("2");
       break;
     }
     case "slack-bot-or-user-token": {
-      // [0] not a placeholder / published doc fixture
       if (!PLACEHOLDER_RE.test(value)) sat.add("0");
-      // [1] conforms to a current Slack token shape: at least three
-      //     dash-separated segments after the xox? prefix
+      // [1] current Slack shape: 3+ dash-separated segments after the prefix
       if (value.split("-").length >= 4) sat.add("1");
-      // [2] not under examples/ docs/ fixtures/
       if (notDocPath) sat.add("2");
       break;
     }
     case "stripe-secret-key": {
-      // [0] not a sk_test_ published sample (deterministic only for the
-      //     test prefix; live keys are handled by [2])
+      // [0] not a published sk_test_ sample; live keys fall to [2]
       if (!(value.startsWith("sk_test_") && PLACEHOLDER_RE.test(value))) sat.add("0");
-      // [1] not under examples/ fixtures/ docs/ / a quickstart template
       if (notDocPath) sat.add("1");
-      // [2] the live-validity probe applies only to sk_live_*; a sk_test_
-      //     key carries no live financial exposure, so the check is moot and
-      //     the collector can attest it deterministically. sk_live_* still
-      //     needs operator-authorised network validation — left unattested.
+      // [2] live-validity probe is moot for a test key; sk_live_* needs operator auth
       if (value.startsWith("sk_test_") || value.startsWith("rk_test_")) sat.add("2");
       break;
     }
     case "openai-api-key": {
-      // [0] not a placeholder / sk-test- / sk-dummy- fixture
       if (!PLACEHOLDER_RE.test(value) && !/^sk-(?:test|dummy)-/i.test(value)) sat.add("0");
-      // [1] post-prefix length meets the entropy floor (>= 48 chars)
+      // [1] post-prefix length meets the entropy floor
       if (value.replace(/^sk-(?:proj-|svcacct-|admin-)?/, "").length >= 48) sat.add("1");
       // [2] vendor disambiguation — sk-ant-* is Anthropic, not OpenAI
       if (!/^sk-ant-/i.test(value)) sat.add("2");
       break;
     }
     case "anthropic-api-key": {
-      // [0] not a placeholder / sk-ant-test- fixture
       if (!PLACEHOLDER_RE.test(value) && !/^sk-ant-test-/i.test(value)) sat.add("0");
-      // [1] not under examples/ fixtures/ sdk-quickstart/ docs-snippet/
       if (notDocPath) sat.add("1");
-      // [2] post-prefix length meets the entropy floor (>= 80 chars after
-      //     sk-ant-(api03|admin01)-)
+      // [2] post-prefix length meets the entropy floor
       if (value.replace(/^sk-ant-(?:api03|admin01)-/, "").length >= 80) sat.add("2");
       break;
     }
@@ -222,33 +160,22 @@ function fpIndicesSatisfied(indicatorId, value, file, window) {
 const INDICATOR_PATTERNS = [
   { id: "aws-access-key-id",          re: /\bAKIA[0-9A-Z]{16}\b/g },
   { id: "aws-secret-access-key",      re: /\baws_secret_access_key\s*[=:]\s*['"]?([A-Za-z0-9/+=]{40})['"]?/gi },
-  // Require a full PEM block (header, base64 body, closing marker) — not just
-  // the `-----BEGIN PRIVATE KEY-----` header — so a service-account JSON shown
-  // as a doc placeholder or a redaction/DLP library's detection-pattern literal
-  // does not register as a real embedded key. A real key is JSON-encoded with
-  // `\n` escapes, so the body class includes backslash; `-` is excluded so the
-  // run halts at `-----END` (no backtracking, ReDoS-safe). Mirrors
-  // ssh-private-key-block below.
+  // A full PEM block, not just the BEGIN header, so a doc placeholder or a DLP
+  // library's own detection pattern does not register. The body class admits
+  // backslash for JSON `\n` escapes and excludes `-` so the run halts — ReDoS-safe.
   { id: "gcp-service-account-json",   re: /"type"\s*:\s*"service_account"[\s\S]{0,1200}?"private_key"\s*:\s*"-----BEGIN PRIVATE KEY-----[A-Za-z0-9+/=\s\\]{40,4000}-----END/g },
   { id: "github-personal-access-token", re: /\bghp_[A-Za-z0-9]{36}\b/g },
   { id: "github-fine-grained-pat",    re: /\bgithub_pat_[A-Za-z0-9_]{82}\b/g },
   { id: "slack-bot-or-user-token",    re: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/g },
   { id: "stripe-secret-key",          re: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{24,}\b/g },
   { id: "jwt-token-with-secret-context", re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
-  // Require a complete PEM block — header, base64 body, closing marker —
-  // so a bare `BEGIN ... PRIVATE KEY` header used as a detection pattern (a
-  // redaction/DLP library's regex literal) or a doc placeholder does not
-  // register as an embedded key. `-` is excluded from the body class so the
-  // run halts at the first `-` of `-----END` (no backtracking, ReDoS-safe).
-  // Private-key *files* (.pem/.key) are detected separately by file presence.
+  // A complete PEM block, so a bare BEGIN header used as a DLP library's own
+  // detection pattern does not register. `-` excluded from the body class halts
+  // the run at `-----END` — no backtracking. Key *files* are found by presence.
   { id: "ssh-private-key-block",      re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |ENCRYPTED |)PRIVATE KEY-----[A-Za-z0-9+/=\s]{20,4000}-----END/g },
-  // The `(?!ant-)` lookahead keeps an Anthropic `sk-ant-*` key from also
-  // matching here. Without it the trailing empty alternative made the prefix
-  // optional (`sk-<20+ chars>`), so one Anthropic key double-fired as both
-  // openai-api-key and anthropic-api-key — inflating the hit count and
-  // mislabeling the vendor. The optional `(?:proj-|svcacct-|admin-)?` group
-  // still admits every real OpenAI shape (proj/svcacct/admin and the bare
-  // legacy `sk-` key); the lookahead is anchored, so no backtracking / ReDoS.
+  // `(?!ant-)` stops an Anthropic key double-firing as openai-api-key too. The
+  // optional prefix group still admits every real OpenAI shape, including the bare
+  // legacy `sk-` key; the lookahead is anchored, so no ReDoS.
   { id: "openai-api-key",             re: /\bsk-(?!ant-)(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}\b/g },
   { id: "anthropic-api-key",          re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
 ];
@@ -310,12 +237,8 @@ function redactMatch(literal) {
 function scanContent(full, rel) {
   let buf;
   try {
-    // Read raw bytes first, then enforce the 1 MB cap on the buffer length.
-    // The previous statSync-before-read doubled the per-file syscall count on
-    // the hot path; reading the buffer and measuring it is byte-accurate (the
-    // cap is a byte limit) without the extra stat. Reading as a Buffer rather
-    // than decoding to a string up front means an oversized file is rejected
-    // before any UTF-8 decode work.
+    // The cap is a byte limit, so measure the Buffer rather than stat first —
+    // byte-accurate, and oversize is rejected before any UTF-8 decode.
     const raw = fs.readFileSync(full);
     if (raw.length > MAX_FILE_BYTES) return { skipped: "file_too_large", bytes: raw.length, hits: [] };
     buf = raw.toString("utf8");
@@ -327,26 +250,21 @@ function scanContent(full, rel) {
     const matches = buf.matchAll(p.re);
     let count = 0;
     for (const m of matches) {
-      // Demote AWS-published example access-key IDs (e.g. the docs' canonical
-      // AKIAIOSFODNN7EXAMPLE). A README quoting the AWS docs must not hit.
+      // A README quoting the AWS docs must not hit.
       if (p.id === "aws-access-key-id" && AWS_EXAMPLE_ACCESS_KEY_IDS.has(m[0])) continue;
-      // The captured credential is group 1 when the pattern brackets it
-      // (aws_secret_access_key=<value>); otherwise the whole match.
+      // Group 1 when the pattern brackets the credential; else the whole match.
       const value = m[1] != null ? m[1] : m[0];
-      // ±600-byte context window (a deterministic proxy for "nearby lines")
-      // used by the co-occurrence FP check.
+      // ±600 bytes — a deterministic proxy for "nearby lines" in the FP check.
       const winStart = Math.max(0, m.index - 600);
       const window = buf.slice(winStart, m.index + 600);
       hits.push({
         indicator_id: p.id,
         file: rel,
         offset: m.index,
-        // 1-based line of the match so buildEvidenceLocations emits a region
-        // (SARIF startLine) instead of a bare file-level location.
+        // 1-based, so buildEvidenceLocations emits a SARIF startLine region.
         line: lineFromOffset(buf, m.index),
         redacted_match: redactMatch(m[0]),
-        // The false_positive_checks_required indices this hit deterministically
-        // survives — attested so the runner doesn't downgrade hit → inconclusive.
+        // Attested so the runner does not downgrade hit → inconclusive.
         fp_satisfied: fpIndicesSatisfied(p.id, value, rel, window),
       });
       if (++count >= 5) break; // cap per-indicator-per-file
@@ -368,10 +286,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     errors.push({ kind: "walk_failed", reason: e.message });
     files = [];
   }
-  // Subtrees pruned for exceeding the depth cap are NOT scanned. Surface them
-  // so an unscanned deep .env / id_rsa / api-key file is an observable gap,
-  // not a silent miss indistinguishable from "scanned, found nothing" —
-  // symmetric with the per-file `file_too_large_skipped` reporting below.
+  // Subtrees pruned at the depth cap are NOT scanned; surface them so an unscanned
+  // deep .env or id_rsa is an observable gap, not a silent miss.
   if (truncations.length) {
     errors.push({
       artifact_id: "repo-tree",
@@ -423,9 +339,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     if (r.skipped === "read_error") {
       errors.push({ artifact_id: "secret-regex-scan-text-files", kind: "read_failed", reason: `${f.rel}: ${r.reason}` });
     } else if (r.skipped === "file_too_large") {
-      // A secret in the first bytes of a large file would otherwise be
-      // dropped silently. Record the skip so the operator knows this file
-      // was NOT scanned (mirrors crypto-codebase's >1 MB read_failed entry).
+      // Record the skip, or a secret in an oversized file is dropped silently.
       errors.push({
         artifact_id: "secret-regex-scan-text-files",
         kind: "file_too_large_skipped",
@@ -434,9 +348,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     }
   }
 
-  // Split hits into production vs test-path. The indicator fires
-  // only when at least one PROD hit exists. Test-only hits stay in
-  // the artifact for operator inspection but don't flip the signal.
+  // The indicator fires only on a PROD hit; test-path hits stay in the artifact.
   const hitsByIndicator = {};
   const prodHitsByIndicator = {};
   for (const h of allHits) {
@@ -445,23 +357,16 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       (prodHitsByIndicator[h.indicator_id] = prodHitsByIndicator[h.indicator_id] || []).push(h);
     }
   }
-  // Same split for the file-presence indicators (ssh-private-keys
-  // artifact backs the ssh-private-key-block content scan AND the
-  // ssh-key-bad-perms posture check below). Filter out test-named
-  // private-key files (e.g. cosign-test.key) for the signal too.
+  // The same split for the file-presence indicators, so a fixture key raises neither.
   const prodSshPrivateKeys = sshPrivateKeys.filter(f => !isTestPath(f.rel));
 
   const signal_overrides = {};
   for (const p of INDICATOR_PATTERNS) {
     signal_overrides[p.id] = prodHitsByIndicator[p.id] && prodHitsByIndicator[p.id].length > 0 ? "hit" : "miss";
   }
-  // Per-indicator __fp_checks attestation. For each FP-gated indicator that
-  // fired, attest the false_positive_checks_required indices the collector
-  // deterministically ran AND that EVERY surviving hit satisfies (the
-  // intersection — an index is only universally true if no hit fails it).
-  // Network / operator-judgement indices are never in the set, so the runner
-  // still downgrades indicators that carry one. Without this, a real secret
-  // surfaced by `collect` is downgraded to inconclusive after `run`.
+  // For each fired indicator, attest the FP indices EVERY surviving hit satisfies —
+  // the intersection, since an index is universally true only if no hit fails it.
+  // Without this, a real secret found by `collect` is downgraded after `run`.
   for (const p of INDICATOR_PATTERNS) {
     if (signal_overrides[p.id] !== "hit") continue;
     const hits = prodHitsByIndicator[p.id] || [];
@@ -478,46 +383,26 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       signal_overrides[`${p.id}__fp_checks`] = att;
     }
   }
-  // ssh-private-key-block is also flipped by file presence (a private
-  // key file with the matching magic bytes counts even without a
-  // content scan match — e.g. binary-only key formats). Re-flip when
-  // any non-test private-key file was discovered.
+  // Also flipped by file presence: a binary-only key format has no content match.
   if (prodSshPrivateKeys.length > 0) signal_overrides["ssh-private-key-block"] = "hit";
-  // world-writable-env-file predicate (per data/playbooks/secrets.json):
-  //   restricted to env-files artifact entries
-  //   any .env / .env.* / .envrc with mode 0666 or 0664 (group/world writable)
-  // i.e. group-write OR world-write bit set (mode & 0o022).
+  // Per the playbook: any env-files entry with the group-write or world-write bit set.
   const envFilePostures = process.platform === "win32" ? [] : envFiles.map(f => ({ file: f.rel, ...statPosture(f.full) }));
-  // POSIX mode bits are unreadable on win32, so this posture cannot be checked
-  // there. OMIT the signal on Windows (mirroring cred-stores' credentials-file-
-  // bad-perms) so the runner returns `inconclusive` rather than a deterministic
-  // false `miss` for a check that physically cannot run. (The posture array is
-  // still declared — empty on win32 — for the SARIF per-indicator locations.)
+  // POSIX mode bits are unreadable on win32, so the signal is OMITTED there — the
+  // runner returns `inconclusive`, not a false `miss`. Same as cred-stores' bad-perms.
   if (process.platform !== "win32") {
     signal_overrides["world-writable-env-file"] = envFilePostures.some(p => p.error == null && (p.mode & 0o022) !== 0) ? "hit" : "miss";
   }
 
-  // ssh-key-bad-perms predicate (per playbook):
-  //   restricted to ssh-private-keys artifact + ~/.ssh/id_* paths
-  //   any private-key file with mode != 0600
-  // The collector scope is the cwd; ~/.ssh enumeration is outside this
-  // walk root. Within cwd, flag any discovered private key whose mode
-  // is anything other than 0600 (strict). Use the test-path-filtered set
-  // (prodSshPrivateKeys) — matching ssh-private-key-block — so a fixture
-  // key checked in under a test/ path doesn't raise a bad-perms posture.
+  // Per the playbook: any private key whose mode is not exactly 0600. ~/.ssh lies
+  // outside the cwd walk root, so only keys discovered here are checked.
   const sshKeyPostures = process.platform === "win32" ? [] : prodSshPrivateKeys.map(f => ({ file: f.rel, ...statPosture(f.full) }));
-  // Same as world-writable-env-file: omit on win32 (mode bits unreadable) so the
-  // runner returns inconclusive instead of a forced false `miss`.
+  // Omitted on win32 for the same reason as world-writable-env-file.
   if (process.platform !== "win32") {
     signal_overrides["ssh-key-bad-perms"] = sshKeyPostures.some(p => p.error == null && p.mode !== 0o600) ? "hit" : "miss";
   }
 
-  // Per-indicator file locations for every indicator flipped to "hit", so
-  // a SARIF result points at the file carrying the secret / bad posture.
-  // Content-regex hits carry a 1-based `line` (derived from the match offset),
-  // so these locations include a startLine region. The file-presence and
-  // posture indicators contribute the carrier file path directly (file-level,
-  // no line).
+  // Locations for every indicator flipped to "hit", so a SARIF result points at the
+  // carrying file. A content hit carries a line and becomes a region.
   const evidence_locations = {};
   for (const p of INDICATOR_PATTERNS) {
     if (signal_overrides[p.id] === "hit") {
@@ -525,8 +410,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       if (locs.length) evidence_locations[p.id] = locs;
     }
   }
-  // ssh-private-key-block also fires on private-key file presence — fold in
-  // the discovered key files alongside any content-scan hits, de-duplicated.
+  // Fold the discovered key files in alongside content hits, de-duplicated.
   if (signal_overrides["ssh-private-key-block"] === "hit") {
     const locs = buildEvidenceLocations([
       ...(prodHitsByIndicator["ssh-private-key-block"] || []),