@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/collectors/cicd-pipeline-compromise.js

@@ -1,91 +1,85 @@
 "use strict";
 
 /**
- * lib/collectors/cicd-pipeline-compromise.js
- *
- * Companion collector for the `cicd-pipeline-compromise` playbook.
- * Consumer-side CI/CD posture: walks .github/workflows/*.yml,
- * .gitlab-ci.yml, .circleci/config.yml, and the project's
- * infra/terraform/policies dirs for OIDC trust JSON. Flips
- * deterministic indicators that detect the published-Action and
- * fork-PR attack classes documented in the playbook.
- *
- * Skipped indicators (require GitHub API or HSM/KMS access, left
- * unflipped so the runner returns inconclusive):
- *
- *   self-hosted-runner-non-ephemeral    needs GitHub API (runners list)
- *   runner-scoped-signing-key           needs HSM/KMS inspection
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `cicd-pipeline-compromise` playbook: walks CI
+ * workflow YAML and the infra / terraform / policies dirs for OIDC trust JSON.
+ * `self-hosted-runner-non-ephemeral` and `runner-scoped-signing-key` are left
+ * unflipped (GitHub runners API / HSM inspection), so they report inconclusive.
+ * Interface: lib/collectors/README.md.
  */
 
 const fs = require("node:fs");
 const path = require("node:path");
 const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
 
-// Shared code-scope name exclusions (dependency caches, build output, VCS +
-// agent scratch). Threaded into the OIDC-policy descent so a trust JSON in a
-// build-output dir (e.g. `dist/`) is not scanned — consistent with the other
-// tree-walking collectors.
+// Shared code-scope exclusions, so a trust JSON under `dist/` is not scanned.
 const OIDC_WALK_EXCLUDES = codeExcludeSet();
 
 const COLLECTOR_ID = "cicd-pipeline-compromise";
 
+// Returns { text } when the file was read, otherwise { skipped, reason }: a file
+// that is never scanned reads as a "miss" on every indicator it would have
+// flipped, so the caller has to record the skip rather than drop it.
 function readSafe(p, max = 512 * 1024) {
   let fd;
   try {
     fd = fs.openSync(p, "r");
     const s = fs.fstatSync(fd);
-    if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
-    return fs.readFileSync(fd, "utf8");
-  } catch { return null; }
+    if (s.size > max) return { skipped: "file_too_large", reason: `${s.size} bytes exceeds the ${max}-byte scan limit; not scanned` };
+    // readFileSync(fd) loops read() to EOF; a single readSync can return short on
+    // a network or FUSE fd. Reading the open fd keeps fstat-then-read TOCTOU-free.
+    return { text: fs.readFileSync(fd, "utf8") };
+  } catch (e) { return { skipped: "read_error", reason: (e && e.message) || String(e) }; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
 }
 
-function walkWorkflows(root) {
+function skipEntry(artifact_id, rel, r) {
+  return {
+    artifact_id,
+    kind: r.skipped === "file_too_large" ? "file_too_large_skipped" : "read_failed",
+    reason: `${rel}: ${r.reason}`,
+  };
+}
+
+function walkWorkflows(root, errors = []) {
   const out = [];
   const wfDir = path.join(root, ".github", "workflows");
   if (fs.existsSync(wfDir)) {
     let entries;
     try { entries = fs.readdirSync(wfDir, { withFileTypes: true }); }
-    catch { entries = []; }
+    catch (e) {
+      entries = [];
+      errors.push({ artifact_id: "workflow-yaml-inventory", kind: "readdir_failed", reason: `.github/workflows: ${e.message}` });
+    }
     for (const e of entries) {
       if (!e.isFile()) continue;
       if (!/\.(ya?ml)$/i.test(e.name)) continue;
       const full = path.join(wfDir, e.name);
-      const content = readSafe(full);
-      if (content != null) out.push({ full, rel: path.relative(root, full).replace(/\\/g, "/"), content });
+      const rel = path.relative(root, full).replace(/\\/g, "/");
+      const r = readSafe(full);
+      if (r.text != null) out.push({ full, rel, content: r.text });
+      else errors.push(skipEntry("workflow-yaml-inventory", rel, r));
     }
   }
   // Also recognise the most common single-file CI YAMLs at repo root.
   for (const top of [".gitlab-ci.yml", ".circleci/config.yml"]) {
     const full = path.join(root, top);
     if (fs.existsSync(full)) {
-      const content = readSafe(full);
-      if (content != null) out.push({ full, rel: top, content });
+      const r = readSafe(full);
+      if (r.text != null) out.push({ full, rel: top, content: r.text });
+      else errors.push(skipEntry("workflow-yaml-inventory", top, r));
     }
   }
   return out;
 }
 
-// `on:` trigger detection. Workflows declare triggers via four
-// canonical YAML shapes:
-//   - scalar:     `on: push`
-//   - inline list: `on: [push, pull_request_target]`
-//   - block list:  `on:\n  - push\n  - pull_request_target`
-//   - mapping:     `on:\n  push:\n  pull_request_target:`
-// Heuristic accepts all four.
+// Trigger detection across the four canonical `on:` shapes: scalar
+// (`on: push`), inline list, block list, and mapping.
 function workflowHasTrigger(content, name) {
   if (new RegExp(`^\\s*on:\\s*['"]?${name}['"]?\\s*(?:#.*)?$`, "m").test(content)) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal (pull_request_target / issue_comment / pull_request), never operator/file input
   const listMatch = content.match(/^\s*on:\s*\[([^\]]*)\]/m);
   if (listMatch && new RegExp(`(?:^|,)\\s*['"]?${name}['"]?\\s*(?:,|$)`).test(listMatch[1])) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal, never operator/file input
-  // block list AND mapping forms both follow `on:\n` with indented
-  // continuation lines. Capture the block and inspect for either
-  // `- <name>` (list) or `<name>:` (mapping) within it.
+  // Block-list and mapping forms both follow `on:\n` with indented continuations.
   const blockMatch = content.match(/^\s*on:\s*\n((?:[ \t]+[^\n]+\n?)+)/m);
   if (blockMatch) {
     if (new RegExp(`^[ \\t]+-\\s+['"]?${name}['"]?\\s*(?:#.*)?\\s*$`, "m").test(blockMatch[1])) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal, never operator/file input
@@ -94,13 +88,9 @@ function workflowHasTrigger(content, name) {
   return false;
 }
 
-// Find `actions/checkout` step blocks and return true when any one
-// of them carries a `ref:` line referencing the PR head. Each step
-// block is delimited by the next sibling `- ` at the same
-// indentation (or de-indented line, meaning we've left steps[]).
-// Binding the ref match to the checkout step prevents false hits
-// when another unrelated step references the PR head while the
-// actual checkout is safely fetching the base ref.
+// True when an `actions/checkout` step block carries a `ref:` naming the PR head.
+// Binding the ref to the checkout step keeps an unrelated step's reference to the
+// PR head from reading as a hit while the checkout fetches the base ref.
 function checkoutBindsPrHead(content) {
   const lines = content.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
@@ -114,8 +104,7 @@ function checkoutBindsPrHead(content) {
       const indentM = line.match(/^(\s*)\S/);
       if (!indentM) continue;
       const indent = indentM[1].length;
-      // Next sibling step starts with `-` at the same indent, or
-      // any line de-indented past the step base ends the block.
+      // The block ends at a sibling `-` on the same indent, or any de-indent.
       if (indent < baseIndent) { blockEnd = j; break; }
       if (indent === baseIndent && line.trim().startsWith("- ")) { blockEnd = j; break; }
     }
@@ -139,18 +128,12 @@ function scanWorkflow(content, rel) {
   const hasPRTarget = workflowHasTrigger(content, "pull_request_target");
   const hasIssueComment = workflowHasTrigger(content, "issue_comment");
 
-  // pull-request-target-with-pr-checkout: PRT trigger AND the
-  // PR-head ref reference is bound to an actions/checkout step
-  // (not to an unrelated step that happens to read head_ref).
   if (hasPRTarget && checkoutBindsPrHead(content)) {
     hits["pull-request-target-with-pr-checkout"].push({ file: rel, snippet: "pull_request_target trigger + checkout of PR head" });
   }
 
-  // workflow-injection-sink: ${{ github.event.<title|body|...> }}
-  // interpolated directly inside a `run:` block. Conservative form:
-  // file-wide presence of one of the dangerous expressions AND the
-  // expression appears outside an `env:` mapping context that would
-  // have made it safe.
+  // workflow-injection-sink: an attacker-controlled `${{ github.event.* }}`
+  // interpolated inside a `run:` block, outside a safe `env:` mapping.
   if (hasPRTarget || hasIssueComment || workflowHasTrigger(content, "pull_request")) {
     const dangerousExprs = [
       /\$\{\{\s*github\.event\.pull_request\.(?:title|body|head\.ref)\s*\}\}/,
@@ -162,17 +145,12 @@ function scanWorkflow(content, rel) {
     const lines = content.split(/\r?\n/);
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
-      // Quick filter: dangerous expression on this line?
       const matchedExpr = dangerousExprs.find(re => re.test(line));
       if (!matchedExpr) continue;
-      // If the dangerous expr is inside an `env:` mapping (key: value
-      // shape on a YAML env block), the shell sees it as a variable
-      // and it's not an injection sink. Walk back up to 3 lines to
-      // find the nearest preceding YAML key indicator.
+      // Inside an `env:` mapping the shell sees a variable, not a sink.
       const ctx = lines.slice(Math.max(0, i - 3), i + 1).join("\n");
       const isEnvBinding = /^\s+[A-Z_][A-Z0-9_]*:\s*['"]?\$\{\{\s*github\.event/m.test(ctx);
-      // Detect `run:` proximity. The expression must land inside a
-      // run-block; otherwise it's an `env:` binding or `with:` arg.
+      // The expression counts only inside a run-block.
       const inRun = /^\s+run:/m.test(ctx) || /^\s+\|/m.test(ctx) || lines[i].trim().startsWith("- run:");
       if (inRun && !isEnvBinding) {
         hits["workflow-injection-sink"].push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 160) });
@@ -181,17 +159,14 @@ function scanWorkflow(content, rel) {
     }
   }
 
-  // actions-floating-tag-pin: `uses: <owner>/<repo>@<ref>` where ref
-  // isn't a 40-char hex SHA AND owner isn't `actions` (first-party
-  // GitHub repos excluded by the playbook predicate). Excludes local
-  // composite actions (`uses: ./`).
+  // actions-floating-tag-pin: `uses: <owner>/<repo>@<ref>` where ref is not a
+  // 40-char hex SHA; owner `actions` and local composite actions are excluded.
   const lines2 = content.split(/\r?\n/);
   for (let i = 0; i < lines2.length; i++) {
-    // A real `uses:` line is never multiple KB. Skip overlong lines so a
-    // crafted whitespace run can't drive regex backtracking.
+    // A real `uses:` line is never multiple KB; skipping overlong ones keeps a
+    // crafted whitespace run from driving regex backtracking.
     if (lines2[i].length > 4096) continue;
-    // `^[ \t]*(?:-[ \t]*)?` anchors the indentation once, then an optional
-    // `- ` list marker — no overlapping `\s*` runs that backtrack.
+    // Indentation is anchored once, then an optional `- ` — no overlapping `\s*`.
     const m = lines2[i].match(/^[ \t]*(?:-[ \t]*)?uses:\s*['"]?([^'"\s#]+)['"]?/);
     if (!m) continue;
     const refStr = m[1];
@@ -208,15 +183,12 @@ function scanWorkflow(content, rel) {
     }
   }
 
-  // secret-exposed-to-fork-pr: pull_request_target trigger + the
-  // workflow references `secrets.X` for any X other than GITHUB_TOKEN.
-  // Pull-request-from-forks (without target) requires runtime info
-  // to detect fork status — left to operator evidence.
+  // secret-exposed-to-fork-pr: a pull_request_target trigger plus a `secrets.X`
+  // reference for any X other than GITHUB_TOKEN. A plain pull_request from a fork
+  // needs runtime fork status, so it stays operator evidence.
   if (hasPRTarget) {
-    // Compare the captured secret NAME exactly to GITHUB_TOKEN. An unanchored
-    // /secrets\.GITHUB_TOKEN/ substring test also matched custom secrets such
-    // as GITHUB_TOKEN_PROD, silently treating them as the built-in token and
-    // dropping a real fork-PR secret exposure (false negative).
+    // The captured secret NAME is compared exactly: an unanchored
+    // /secrets\.GITHUB_TOKEN/ also matches a custom GITHUB_TOKEN_PROD.
     const nonDefault = [];
     for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_][A-Z0-9_]*)\s*\}\}/g)) {
       if (m[1] !== "GITHUB_TOKEN") nonDefault.push(m[0]);
@@ -229,46 +201,44 @@ function scanWorkflow(content, rel) {
   return hits;
 }
 
-function scanOidcPolicies(root) {
-  // Walk infra/ + terraform/ + policies/ (depth 4) for *.json that
-  // names token.actions.githubusercontent.com AND has a wildcarded
-  // sub-claim. The playbook lists `repo:<org>/*:*`, `repo:*:*`, and
-  // bare `*` as wildcard shapes.
+function scanOidcPolicies(root, errors = []) {
+  // Walks the infra dirs to depth 4 for *.json naming
+  // token.actions.githubusercontent.com with a wildcarded sub-claim.
   const rootDirs = ["infra", "terraform", "policies", ".aws", ".github"].map(d => path.join(root, d));
   const finds = [];
   function walk(dir, depth) {
     if (depth > 4 || finds.length > 5) return;
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
-    catch { return; }
+    catch (e) {
+      errors.push({
+        artifact_id: "oidc-trust-policy-inventory",
+        kind: "readdir_failed",
+        reason: `${path.relative(root, dir).replace(/\\/g, "/")}: ${e.message}`,
+      });
+      return;
+    }
     for (const e of entries) {
       if (OIDC_WALK_EXCLUDES.has(e.name)) continue;
       const full = path.join(dir, e.name);
       if (e.isDirectory()) {
-        // Skip linked git worktrees (gitdir-pointer `.git` file), e.g.
-        // agent-created repo copies under `.claude/worktrees/<id>/`
-        // nested below a scanned policy/infra dir — rescanning them
-        // double-counts the same OIDC trust documents.
+        // A linked worktree holds the same trust documents; rescanning double-counts.
         if (isLinkedWorktreeDir(full)) continue;
         walk(full, depth + 1);
         continue;
       }
       if (!e.isFile() || !/\.json$/i.test(e.name)) continue;
-      const text = readSafe(full);
-      if (!text) continue;
-      // The authoritative OIDC sub-claim detection is the self-anchored patterns
-      // below — each is bound to the leading `"` of the JSON key
-      // (`"token.actions.githubusercontent.com:sub"`), so a lookalike issuer
-      // such as `"eviltoken.actions…"` cannot match. No separate substring
-      // pre-filter on the issuer host: it added nothing the anchored patterns
-      // don't already enforce, and a bare host-substring check reads as an
-      // incomplete URL sanitization.
-      // sub-claim wildcards. Cover the three shapes the playbook lists.
+      const rel = path.relative(root, full).replace(/\\/g, "/");
+      const r = readSafe(full);
+      if (r.text == null) { errors.push(skipEntry("oidc-trust-policy-inventory", rel, r)); continue; }
+      const text = r.text;
+      // Each pattern is bound to the leading `"` of the JSON key, so a lookalike
+      // issuer like `"eviltoken.actions…"` cannot match.
       const subWildcard =
         /"token\.actions\.githubusercontent\.com:sub"\s*:\s*"\*"/.test(text) ||
         /"token\.actions\.githubusercontent\.com:sub"\s*:\s*"repo:\*[^"]*"/.test(text) ||
         /"token\.actions\.githubusercontent\.com:sub"\s*:\s*"repo:[^"]*\/\*:[^"]*"/.test(text);
-      if (subWildcard) finds.push({ file: path.relative(root, full).replace(/\\/g, "/"), snippet: "OIDC sub-claim wildcarded across repos or branches" });
+      if (subWildcard) finds.push({ file: rel, snippet: "OIDC sub-claim wildcarded across repos or branches" });
     }
   }
   for (const rd of rootDirs) if (fs.existsSync(rd)) walk(rd, 0);
@@ -280,8 +250,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const startTime = Date.now();
   const root = path.resolve(cwd);
 
-  // cwd-is-repo precondition: .git directory present. Outside a
-  // repo we have no workflows / no OIDC trust JSON to walk.
+  // Outside a repo there are no workflows and no OIDC trust JSON to walk.
   const cwdIsRepo = fs.existsSync(path.join(root, ".git"));
   if (!cwdIsRepo) {
     return {
@@ -302,7 +271,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     };
   }
 
-  const workflows = walkWorkflows(root);
+  const workflows = walkWorkflows(root, errors);
   const aggregateHits = {
     "workflow-injection-sink": [],
     "pull-request-target-with-pr-checkout": [],
@@ -314,21 +283,29 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     for (const [k, v] of Object.entries(h)) aggregateHits[k].push(...v);
   }
 
-  const oidcWildcards = scanOidcPolicies(root);
+  const oidcWildcards = scanOidcPolicies(root, errors);
+
+  // A workflow this collector could not read may hold the very thing each
+  // indicator looks for, so `miss` over an incomplete inventory is a clean
+  // verdict on evidence that was never examined. collector_errors are advisory
+  // and change no verdict on their own; the gap has to reach the signal. A hit
+  // stands on what WAS read and is unaffected.
+  const workflowScanIncomplete = errors.some(
+    (e) => e.artifact_id === "workflow-yaml-inventory");
+  const oidcScanIncomplete = errors.some(
+    (e) => e.artifact_id === "oidc-trust-policy-inventory");
+  const verdict = (found, incomplete) => (found ? "hit" : incomplete ? "inconclusive" : "miss");
 
   const signal_overrides = {
-    "workflow-injection-sink": aggregateHits["workflow-injection-sink"].length > 0 ? "hit" : "miss",
-    "pull-request-target-with-pr-checkout": aggregateHits["pull-request-target-with-pr-checkout"].length > 0 ? "hit" : "miss",
-    "actions-floating-tag-pin": aggregateHits["actions-floating-tag-pin"].length > 0 ? "hit" : "miss",
-    "secret-exposed-to-fork-pr": aggregateHits["secret-exposed-to-fork-pr"].length > 0 ? "hit" : "miss",
-    "wildcarded-oidc-sub-claim": oidcWildcards.length > 0 ? "hit" : "miss",
+    "workflow-injection-sink": verdict(aggregateHits["workflow-injection-sink"].length > 0, workflowScanIncomplete),
+    "pull-request-target-with-pr-checkout": verdict(aggregateHits["pull-request-target-with-pr-checkout"].length > 0, workflowScanIncomplete),
+    "actions-floating-tag-pin": verdict(aggregateHits["actions-floating-tag-pin"].length > 0, workflowScanIncomplete),
+    "secret-exposed-to-fork-pr": verdict(aggregateHits["secret-exposed-to-fork-pr"].length > 0, workflowScanIncomplete),
+    "wildcarded-oidc-sub-claim": verdict(oidcWildcards.length > 0, oidcScanIncomplete),
   };
 
-  // Per-indicator file locations for every indicator flipped to "hit", so a
-  // SARIF result points at the workflow YAML (or OIDC trust JSON) that
-  // triggered it. Line-scanned indicators (workflow-injection-sink,
-  // actions-floating-tag-pin) carry a real line; the trigger-shape and
-  // OIDC-wildcard indicators record the file only and surface as file-level.
+  // File locations for every indicator flipped to "hit", so a SARIF result points
+  // at the YAML or trust JSON behind it; without a line it surfaces as file-level.
   const evidence_locations = {};
   const evidenceSources = { ...aggregateHits, "wildcarded-oidc-sub-claim": oidcWildcards };
   for (const [id, list] of Object.entries(evidenceSources)) {
@@ -340,14 +317,20 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
 
   const artifacts = {
     "workflow-yaml-inventory": {
-      value: workflows.length ? workflows.map(w => w.rel).join(", ") : "no workflow files found at cwd",
-      captured: true,
+      value: workflowScanIncomplete
+        ? `${workflows.length} workflow(s) read, at least one skipped — inventory incomplete, see collector_errors`
+        : workflows.length ? workflows.map(w => w.rel).join(", ") : "no workflow files found at cwd",
+      captured: !workflowScanIncomplete,
+      ...(workflowScanIncomplete ? { reason: "one or more workflow files or the workflow directory could not be read" } : {}),
     },
     "oidc-trust-policy-inventory": {
-      value: oidcWildcards.length
-        ? `${oidcWildcards.length} wildcarded sub-claim(s): ${oidcWildcards.map(f => f.file).join(", ")}`
-        : "no wildcarded OIDC sub-claim found in infra / terraform / policies",
-      captured: true,
+      value: oidcScanIncomplete
+        ? `${oidcWildcards.length} wildcarded sub-claim(s) found, at least one policy file skipped — inventory incomplete, see collector_errors`
+        : oidcWildcards.length
+          ? `${oidcWildcards.length} wildcarded sub-claim(s): ${oidcWildcards.map(f => f.file).join(", ")}`
+          : "no wildcarded OIDC sub-claim found in infra / terraform / policies",
+      captured: !oidcScanIncomplete,
+      ...(oidcScanIncomplete ? { reason: "one or more trust-policy files or directories could not be read" } : {}),
     },
     "actions-sha-pinning": {
       value: `${aggregateHits["actions-floating-tag-pin"].length} non-SHA third-party uses: reference(s) across ${workflows.length} workflow(s)`,
@@ -374,20 +357,14 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   };
 
   return {
-    // Attest preconditions.
-    //   ci-config-readable — the collector just walked workflow YAML
-    //     + OIDC trust JSON; filesystem reads succeeded. Auto-true.
-    //   operator-owns-ci-fleet — REQUIRES explicit operator opt-in via
-    //     `--attest-ownership` (or args.attestOwnership === true). The
-    //     playbook gates this `on_fail: halt`; running collect against
-    //     any cwd (e.g. `--cwd /other/repo`) does NOT implicitly attest
-    //     ownership of that fleet's CI authorization scope. Operators
-    //     who own the CI fleet they're auditing pass the flag; running
-    //     collect | run without the flag halts at the runner's
-    //     preflight gate (as the playbook intends).
+    // operator-owns-ci-fleet requires explicit opt-in through `--attest-ownership`:
+    // pointing collect at any cwd does NOT attest ownership of that fleet's CI
+    // authorization scope, and the playbook gates the precondition `on_fail: halt`.
     precondition_checks: {
       "cwd-is-repo": true,
-      "ci-config-readable": true,
+      // An attestation that the CI configuration was readable, so it cannot
+      // stay true over a file this collector failed to open.
+      "ci-config-readable": !workflowScanIncomplete,
       "operator-owns-ci-fleet": args.attestOwnership === true || args["attest-ownership"] === true,
     },
     artifacts,