@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/collectors/containers.js

@@ -1,19 +1,10 @@
 "use strict";
 
 /**
- * lib/collectors/containers.js
- *
- * Companion collector for the `containers` playbook. Walks the cwd
- * for Dockerfile / Containerfile, docker-compose, and k8s manifest
- * files; applies the catalogued indicator predicates against their
- * contents.
- *
- * YAML parsing strategy: heuristic line-scanning, not a full YAML
- * parser. The catalogued indicators (privileged: true, hostNetwork:
- * true, runAsUser: 0, etc.) are well-known text patterns whose
- * misuse is unambiguous at the line level. False positives are rare
- * — e.g. `# privileged: true` in a comment would match, but those
- * are also worth surfacing.
+ * Companion collector for the `containers` playbook: walks the cwd for
+ * Dockerfile / Containerfile, compose and k8s manifest files and applies the
+ * catalogued indicator predicates. YAML is line-scanned, never parsed — every
+ * catalogued indicator is an unambiguous single-line pattern.
  *
  * Interface: see lib/collectors/README.md
  */
@@ -25,8 +16,7 @@ const { codeExcludeSet, walkTree, buildEvidenceLocations } = require("./scan-exc
 const COLLECTOR_ID = "containers";
 
 const DEFAULT_MAX_DEPTH = 6;
-// Shared code-scope exclusions (dependency caches, build output, VCS +
-// agent/editor scratch including `.claude/`); no container-specific extras.
+// Shared code-scope exclusions; no container-specific extras.
 const DEFAULT_EXCLUDES = codeExcludeSet();
 
 const DOCKERFILE_NAMES = new Set(["Dockerfile", "Containerfile"]);
@@ -55,21 +45,14 @@ function classify(file) {
 
 function readSafe(full, max = 512 * 1024) {
   try {
-    // Read raw bytes, enforce the cap on the buffer length, then decode.
-    // Replaces a statSync-before-read with a single read; the cap is
-    // byte-based, so Buffer.length is the correct measure and an oversized
-    // file is rejected before any UTF-8 decode.
+    // Byte-based cap on Buffer.length: oversized files are rejected before decode.
     const raw = fs.readFileSync(full);
     if (raw.length > max) return null;
     return raw.toString("utf8");
   } catch { return null; }
 }
 
-/**
- * Recognise a YAML document as a k8s resource by `apiVersion: ...` +
- * `kind: ...` lines. Doesn't require full parsing — the two lines
- * appear at top-level indent.
- */
+// Top-level `apiVersion:` + `kind:` is enough to recognise one without parsing.
 function looksLikeK8sManifest(content) {
   if (!/^apiVersion:\s+\S/m.test(content)) return false;
   if (!/^kind:\s+\S/m.test(content)) return false;
@@ -81,9 +64,8 @@ function extractKind(content) {
   return m ? m[1] : null;
 }
 
-/**
- * Dockerfile pattern matchers. Returns { id, hits: [{line, snippet}] }.
- */
+// Returns { <indicator id>: [{ file, line, snippet }] }; line 0 means the hit
+// is whole-file rather than a specific line.
 function scanDockerfile(content, rel) {
   const lines = content.split(/\r?\n/);
   const hits = {
@@ -93,12 +75,8 @@ function scanDockerfile(content, rel) {
     "dockerfile-curl-pipe-bash": [],
   };
 
-  // Metadata-only Dockerfile heuristic — when the file has a FROM
-  // line but no RUN / COPY / ADD / CMD / ENTRYPOINT / EXPOSE / VOLUME
-  // / WORKDIR / USER directives, it's not a runtime image. Examples:
-  // the go-version-scraping Dockerfile (cosign style) or a base-image-
-  // probe used only by `docker build` to extract a version label.
-  // The runs-as-root predicate is meaningless on those — demote.
+  // A FROM line with no execution-shape directive is a build-time probe, not a
+  // runtime image; the runs-as-root predicate means nothing there.
   const isMetadataOnly = (() => {
     let sawFrom = false;
     let sawBuildOrRuntime = false;
@@ -107,8 +85,7 @@ function scanDockerfile(content, rel) {
       if (!t || t.startsWith("#")) continue;
       if (/^FROM\b/i.test(t)) { sawFrom = true; continue; }
       if (/^(RUN|COPY|ADD|CMD|ENTRYPOINT|EXPOSE|VOLUME|WORKDIR|USER|HEALTHCHECK|ONBUILD|STOPSIGNAL|SHELL|ARG|ENV|LABEL)\b/i.test(t)) {
-        // ARG / ENV / LABEL alone aren't enough to make this a runtime
-        // image — only the directives that define execution shape do.
+        // ARG / ENV / LABEL alone do not make a runtime image.
         if (/^(RUN|COPY|ADD|CMD|ENTRYPOINT|EXPOSE|VOLUME|WORKDIR|USER|HEALTHCHECK|ONBUILD|SHELL)\b/i.test(t)) {
           sawBuildOrRuntime = true;
           break;
@@ -120,18 +97,12 @@ function scanDockerfile(content, rel) {
 
   let sawNonRootUser = false;
   let sawAnyUser = false;
-  // Build-stage aliases declared via `FROM <image> AS <alias>`. A later
-  // `FROM <alias> AS <next>` is an INTERNAL multi-stage reference, not a
-  // registry image — it needs no tag/digest. Without tracking these, every
-  // `FROM build-stage` in a normal multi-stage Dockerfile false-fired
-  // from-latest / no-digest-pin.
+  // Aliases from `FROM <image> AS <alias>`. A later `FROM <alias>` is an internal
+  // multi-stage reference, not a registry image, and owes no tag or digest.
   const stageAliases = new Set();
-  // ARG defaults declared earlier in the file, used to resolve interpolated
-  // base references like `FROM node:${NODE_VERSION}` or `FROM ${BASE_IMAGE}`.
-  // A digest pinned through an ARG default (`ARG BASE=img@sha256:...` then
-  // `FROM ${BASE}`) is a legitimate pinning pattern that was invisible to the
-  // raw-text check; and an unresolvable interpolation can't be proven to be
-  // `:latest`, so flagging it from-latest was a false positive.
+  // ARG defaults, used to resolve `FROM node:${NODE_VERSION}`. A digest pinned
+  // through one is real pinning, and an unresolvable interpolation cannot be
+  // proven to be `:latest`, so neither may be flagged from raw text.
   const argDefaults = new Map();
   const resolveArgs = (s) => {
     let interpolatedUnresolved = false;
@@ -149,9 +120,7 @@ function scanDockerfile(content, rel) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith("#")) continue;
 
-    // Track `ARG NAME=default` (and bare `ARG NAME`) so a later FROM that
-    // interpolates the name can resolve it. Quotes around the default are
-    // stripped so `ARG BASE="img@sha256:..."` resolves cleanly.
+    // `ARG NAME=default` and bare `ARG NAME`; quotes come off the default.
     const argMatch = trimmed.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)(?:=(.*))?\s*$/i);
     if (argMatch) {
       const name = argMatch[1];
@@ -163,57 +132,39 @@ function scanDockerfile(content, rel) {
       continue;
     }
 
-    // FROM <image>:latest  OR  FROM <image>  (no tag)  → from-latest
-    // FROM <image>:<tag>  (no @sha256:digest)         → no-digest-pin
     const fromMatch = trimmed.match(/^FROM\s+(\S+)(?:\s+AS\s+(\S+))?/i);
     if (fromMatch) {
       const rawRef = fromMatch[1];
       const alias = fromMatch[2];
       const { resolved: ref, interpolatedUnresolved } = resolveArgs(rawRef);
-      // Skip `scratch` (special base) AND references to a previously-declared
-      // build stage (internal multi-stage reference — not a registry image, so
-      // a tag/digest is neither present nor required).
+      // `scratch` and stage aliases are not registry images.
       if (ref !== "scratch" && !stageAliases.has(ref.toLowerCase())) {
         const hasDigest = /@sha256:[0-9a-f]{64}/i.test(ref);
-        // When an interpolation could not be resolved, the actual image
-        // reference is unknown — it may carry a digest supplied via
-        // `--build-arg` at build time. Suppress both signals rather than
-        // emit a guess; a resolvable ARG default still produces a precise
-        // verdict below.
+        // An unresolved interpolation may carry a `--build-arg` digest: stay silent.
         if (!hasDigest && !interpolatedUnresolved) {
           hits["dockerfile-no-digest-pin"].push({ file: rel, line: i + 1, snippet: trimmed.slice(0, 120) });
         }
-        // latest tag check: either explicit :latest OR no tag at all
-        // (Docker defaults to :latest when omitted).
+        // No tag counts as :latest — that is Docker's default.
         const tagMatch = ref.match(/:([^@]+)(?:@|$)/);
         const tag = tagMatch ? tagMatch[1] : null;
         if (!interpolatedUnresolved && (tag === "latest" || tag === null)) {
           hits["dockerfile-from-latest"].push({ file: rel, line: i + 1, snippet: trimmed.slice(0, 120) });
         }
       }
-      // USER does NOT carry across Docker build stages: each stage starts
-      // from its base image's default user (root) until its own USER
-      // directive. A `FROM <prior-stage-alias>` is the one exception — it
-      // inherits the parent stage's USER, so it must NOT reset. Any other
-      // FROM (registry image, or `scratch`) begins a fresh stage and resets
-      // the per-stage USER tracking, so the runs-as-root predicate reflects
-      // only the FINAL stage. Evaluate internal-vs-external against the
-      // ARG-resolved `ref` and BEFORE the current alias is recorded.
+      // USER does not carry across build stages: a stage runs as its base image's
+      // user (root) until its own USER directive, so an external FROM resets the
+      // tracking. A `FROM <prior-stage-alias>` inherits and must not reset. Both
+      // tests read the ARG-resolved `ref`, before this stage's alias is recorded.
       const isInternalStageRef = stageAliases.has(ref.toLowerCase());
       if (!isInternalStageRef) {
         sawNonRootUser = false;
         sawAnyUser = false;
       }
-      // Record this stage's alias so later `FROM <alias>` lines are recognized
-      // as internal references.
       if (alias) stageAliases.add(alias.toLowerCase());
       continue;
     }
 
-    // USER directive — looks for explicit non-root user.
-    // Recognises USER <uid>, USER <uid>:<gid>, USER <name>, USER <name>:<group>.
-    // Root forms (all count as root): "root", "0", "root:<anything>",
-    // "0:<anything>". Any other UID/name is non-root.
+    // Root is "root" or "0", with any group suffix; every other uid is non-root.
     const userMatch = trimmed.match(/^USER\s+(\S+)/i);
     if (userMatch) {
       sawAnyUser = true;
@@ -223,7 +174,6 @@ function scanDockerfile(content, rel) {
       continue;
     }
 
-    // curl|wget | sh|bash pattern
     if (
       /\b(?:curl|wget)\b[^|]*\|\s*(?:sh|bash|zsh)\b/.test(trimmed) ||
       /\b(?:curl|wget)\b[^&|;]*\s+&&\s+(?:sh|bash)\b/.test(trimmed)
@@ -232,10 +182,7 @@ function scanDockerfile(content, rel) {
     }
   }
 
-  // runs-as-root indicator: file fires if NO non-root USER directive
-  // was seen anywhere. (sawAnyUser=false also counts — image defaults
-  // to root.) Demoted on metadata-only Dockerfiles (FROM-only, no
-  // execution-shape directives) — those aren't runtime images.
+  // Fires when the final stage carries no non-root USER; none defaults to root.
   if (!sawNonRootUser && !isMetadataOnly) {
     hits["dockerfile-runs-as-root"].push({ file: rel, line: 0, snippet: sawAnyUser ? "USER directive sets root/0" : "no USER directive (defaults to root)" });
   }
@@ -243,11 +190,6 @@ function scanDockerfile(content, rel) {
   return hits;
 }
 
-/**
- * docker-compose pattern matchers. Heuristic: match `key: true` /
- * `key: <value>` lines, capturing the service block path where
- * possible.
- */
 function scanCompose(content, rel) {
   const lines = content.split(/\r?\n/);
   const hits = {
@@ -259,22 +201,17 @@ function scanCompose(content, rel) {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    // A real compose line is never multiple KB. Skip overlong lines so a
-    // crafted whitespace run can't drive regex backtracking.
+    // Skipping overlong lines keeps a crafted whitespace run from backtracking.
     if (line.length > 4096) continue;
     if (/^\s*#/.test(line)) continue;
     if (/^\s*privileged:\s*true\b/i.test(line)) hits["compose-privileged"].push({ file: rel, line: i + 1, snippet: line.trim() });
-    // compose-host-network: per playbook, fires on any of
-    // network_mode: host, pid: host, ipc: host.
+    // Per the playbook, any of network_mode / pid / ipc set to host.
     if (/^\s*network_mode:\s*['"]?host\b/i.test(line) ||
         /^\s*pid:\s*['"]?host['"]?\s*$/i.test(line) ||
         /^\s*ipc:\s*['"]?host['"]?\s*$/i.test(line)) {
       hits["compose-host-network"].push({ file: rel, line: i + 1, snippet: line.trim() });
     }
-    // compose-cap-add-sys-admin: per playbook, fires on
-    // SYS_ADMIN, SYS_PTRACE, or SYS_MODULE under cap_add. Either
-    // inline (cap_add: [SYS_ADMIN, SYS_PTRACE]) or multi-line
-    // (cap_add:\n  - SYS_PTRACE).
+    // Per the playbook: risky caps under cap_add, inline list or `- ` items.
     const RISKY_CAPS_RE = /\b(?:CAP_)?(?:SYS_ADMIN|SYS_PTRACE|SYS_MODULE)\b/i;
     if (/cap_add:.*\[/i.test(line) && RISKY_CAPS_RE.test(line)) {
       hits["compose-cap-add-sys-admin"].push({ file: rel, line: i + 1, snippet: line.trim() });
@@ -282,7 +219,6 @@ function scanCompose(content, rel) {
                lines.slice(Math.max(0, i - 5), i).some(l => /cap_add:/i.test(l))) {
       hits["compose-cap-add-sys-admin"].push({ file: rel, line: i + 1, snippet: line.trim() });
     }
-    // docker-sock mount: /var/run/docker.sock anywhere in the value
     if (/\/var\/run\/docker\.sock/.test(line)) {
       hits["compose-docker-sock-mount"].push({ file: rel, line: i + 1, snippet: line.trim() });
     }
@@ -290,10 +226,6 @@ function scanCompose(content, rel) {
   return hits;
 }
 
-/**
- * k8s manifest pattern matchers. Heuristic line-scanning + kind-
- * level guards (e.g. ClusterRoleBinding for cluster-admin check).
- */
 function scanK8s(content, rel) {
   const lines = content.split(/\r?\n/);
   const kind = extractKind(content);
@@ -308,36 +240,28 @@ function scanK8s(content, rel) {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    // A real manifest line is never multiple KB. Skip overlong lines so a
-    // crafted whitespace run can't drive regex backtracking.
+    // Skipping overlong lines keeps a crafted whitespace run from backtracking.
     if (line.length > 4096) continue;
     if (/^\s*#/.test(line)) continue;
     if (/^\s*privileged:\s*true\b/i.test(line)) hits["k8s-privileged"].push({ file: rel, line: i + 1, snippet: line.trim() });
     if (/^\s*(hostNetwork|hostPID|hostIPC):\s*true\b/.test(line)) hits["k8s-host-namespaces"].push({ file: rel, line: i + 1, snippet: line.trim() });
-    // k8s-run-as-root: per playbook, fires on runAsUser: 0 OR
-    // runAsNonRoot: false. (The "runAsUser unset AND image runs as
-    // root" clause requires image inspection the collector can't do
-    // without a container runtime; leave that to the runner when
-    // operator-supplied image-inspection evidence is available.)
+    // Only the two clauses visible in the manifest; the playbook's third needs a
+    // container runtime, so it stays with the runner.
     if (/^\s*runAsUser:\s*0\b/.test(line) ||
         /^\s*runAsNonRoot:\s*false\b/.test(line)) {
       hits["k8s-run-as-root"].push({ file: rel, line: i + 1, snippet: line.trim() });
     }
-    // hostPath sensitive: /, /etc, /var/lib/docker, /proc, /sys
     const hpMatch = line.match(/^\s*path:\s*['"]?(\/(?:etc|proc|sys|var\/lib\/docker|var\/run|root|home)?\/?)['"]?\s*$/);
     if (hpMatch && lines.slice(Math.max(0, i - 3), i).some(l => /hostPath:/i.test(l))) {
       hits["k8s-hostpath-sensitive"].push({ file: rel, line: i + 1, snippet: line.trim() });
     }
-    // image: ...:latest OR image: ... (no tag, defaults to latest)
-    // Allow optional leading `-` from a YAML list item: `- image: ...`.
-    // `^[ \t]*(?:-[ \t]*)?` anchors the indentation once, then an optional
-    // `- ` list marker — no overlapping `\s*` runs that backtrack.
+    // Indentation and the `- ` marker are anchored once each: no overlapping runs.
     const imageMatch = line.match(/^[ \t]*(?:-[ \t]*)?image:\s*['"]?([^'"@\s]+)(?:@[^'"]+)?['"]?\s*$/);
     if (imageMatch) {
       const ref = imageMatch[1];
       const tagMatch = ref.match(/:([^/]+)$/);
       const tag = tagMatch ? tagMatch[1] : null;
-      // Skip if @sha256:... pinned (the full regex captured ref without @-suffix).
+      // Tested against the whole line: the capture above drops the @-suffix.
       const hasDigest = /@sha256:[0-9a-f]{64}/.test(line);
       if (!hasDigest && (tag === "latest" || tag === null)) {
         hits["k8s-image-latest"].push({ file: rel, line: i + 1, snippet: line.trim() });
@@ -345,7 +269,6 @@ function scanK8s(content, rel) {
     }
   }
 
-  // ClusterRoleBinding referencing cluster-admin
   if (kind === "ClusterRoleBinding" || kind === "RoleBinding") {
     if (/name:\s*['"]?cluster-admin['"]?/m.test(content)) {
       hits["k8s-cluster-admin-binding"].push({ file: rel, line: 0, snippet: `${kind} binds cluster-admin` });
@@ -377,7 +300,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     }
   }
 
-  // Aggregate hits per indicator.
   const allHits = {};
   for (const id of [
     "dockerfile-from-latest", "dockerfile-no-digest-pin", "dockerfile-runs-as-root", "dockerfile-curl-pipe-bash",
@@ -409,21 +331,14 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     for (const [id, list] of Object.entries(fileHits)) allHits[id].push(...list);
   }
 
-  // signal_overrides — flip every indicator the collector can decide
-  // deterministically. (k8s-no-seccomp-profile / psa-policy-* /
-  // network-policies-absent require cluster-API access the collector
-  // doesn't have; leave them unflipped so the runner returns
-  // inconclusive rather than a forced miss.)
+  // Only the indicators decidable from files on disk; the ones needing
+  // cluster-API access stay unflipped, so the runner returns inconclusive.
   const signal_overrides = {};
   for (const [id, list] of Object.entries(allHits)) {
     signal_overrides[id] = list.length > 0 ? "hit" : "miss";
   }
 
-  // Per-indicator file locations for every indicator flipped to "hit", so a
-  // SARIF result points at the Dockerfile / compose / k8s manifest line that
-  // triggered it. Line-scanned hits carry a real line number (emitted as
-  // startLine); whole-file hits (e.g. runs-as-root, cluster-admin-binding)
-  // record line 0 and surface as file-level locations.
+  // Line 0 surfaces as a file-level SARIF location rather than a startLine.
   const evidence_locations = {};
   for (const [id, list] of Object.entries(allHits)) {
     if (signal_overrides[id] === "hit") {
@@ -490,13 +405,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   };
 }
 
-// Shared with `discover`: the relative paths of container artifacts
-// (Dockerfiles / Containerfiles / compose files, including variants like
-// docker-compose.test.yml or examples/wiki/Dockerfile) anywhere in the bounded
-// tree this playbook walks — so `discover` recommends `containers` for exactly
-// the surface the collector scans, not just a root-level exact-name Dockerfile
-// or docker-compose.yml. Filename-only (no content reads), capped, and
-// fault-tolerant so a walk error can't break discovery.
+// `discover` calls this to decide whether to recommend `containers`, so it walks
+// the same bounded tree and classifier the collector does. Filenames only,
+// capped, and swallows a walk error so discovery cannot break on one.
 function hasContainerArtifacts(cwd, { cap = 8 } = {}) {
   let files;
   try { files = walkTree(path.resolve(cwd || "."), { maxDepth: DEFAULT_MAX_DEPTH, excludes: DEFAULT_EXCLUDES }); }