dsh-desktop-kit 2.2.0 → 2.7.2

package/plugins/dsh-guardrails/lib/scan.js

@@ -0,0 +1,451 @@
+/**
+ * Bounded, read-only worktree scanning for the guardrails `check` action.
+ *
+ * The scanner walks a project, reads text files up to a per-file byte cap,
+ * detects secrets, dotenv files, protected paths, oversized files and dangerous
+ * commands in shell scripts, then runs `git diff --check` (read-only) when the
+ * tree is a git worktree. Every emitted string passes through redaction; the
+ * raw secret value never leaves `lib/secrets.js`.
+ *
+ * Node built-ins only. The scanner never executes a scanned file: the only
+ * subprocess is `git` with fixed read-only arguments.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { redactText, scanTextForSecrets } from "./secrets.js";
+import { DEFAULT_LIMITS, evaluateCommand, matchProtectedPath } from "./policy.js";
+
+/** Directories that never produce findings and are never descended into. */
+export const SKIP_DIRECTORIES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "bower_components",
+  "dist",
+  "build",
+  "out",
+  "target",
+  "vendor",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".cache",
+  ".turbo",
+  ".parcel-cache",
+  "__pycache__",
+  ".mypy_cache",
+  ".pytest_cache",
+  ".ruff_cache",
+  ".venv",
+  "venv",
+  "virtualenv",
+  ".tox",
+  ".gradle",
+  ".dsh",
+  "pgruntime",
+  "tmp",
+]);
+
+/** Extensions scanned for dangerous command lines. */
+export const SCRIPT_EXTENSIONS = new Set([
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ksh",
+  ".fish",
+  ".ps1",
+  ".psm1",
+  ".bat",
+  ".cmd",
+]);
+
+/** Cap for whitespace findings from one `git diff --check` run. */
+export const GIT_DIFF_MAX_FINDINGS = 50;
+
+const BINARY_SAMPLE_BYTES = 4_096;
+const MAX_COMMAND_LINE_CHARS = 2_000;
+const MAX_SCRIPT_FINDINGS_PER_FILE = 5;
+const ENV_FILE_NAME = /^\.env(?:\..+)?$/iu;
+const ENV_EXAMPLE_NAME = /^\.env\.(?:example|sample|template|dist)$/iu;
+
+/** Cheap binary sniff: a NUL byte in the sample marks the file as unreadable text. */
+export function isProbablyBinary(buffer) {
+  return buffer.subarray(0, BINARY_SAMPLE_BYTES).includes(0);
+}
+
+/**
+ * Clamp caller overrides onto the policy limits. Used by the `check` tool and
+ * directly testable without filesystem access.
+ *
+ * @param {object} policy - effective policy.
+ * @param {object} [overrides] - `maxFiles`, `maxFileSizeBytes`, `maxFindings` overrides.
+ * @returns {object} resolved limits.
+ */
+export function resolveLimits(policy, overrides = {}) {
+  const base = policy?.limits ?? DEFAULT_LIMITS;
+  const pick = (key, minimum, maximum) => {
+    const candidate = Number(overrides?.[key]);
+    if (!Number.isFinite(candidate)) return base[key];
+    return Math.min(maximum, Math.max(minimum, Math.floor(candidate)));
+  };
+  return {
+    maxFiles: pick("maxFiles", 1, 5_000),
+    maxFileSizeBytes: pick("maxFileSizeBytes", 256, 16_777_216),
+    maxTotalBytes: pick("maxTotalBytes", 1_024, 67_108_864),
+    maxFindings: pick("maxFindings", 1, 2_000),
+    maxDepth: pick("maxDepth", 1, 64),
+    maxScriptBytes: pick("maxScriptBytes", 1_024, 2_097_152),
+    gitTimeoutMs: pick("gitTimeoutMs", 500, 60_000),
+  };
+}
+
+function readFileBounded(absolutePath, limitBytes) {
+  const handle = fs.openSync(absolutePath, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(limitBytes + 1);
+    let total = 0;
+    while (total < buffer.length) {
+      const read = fs.readSync(handle, buffer, total, buffer.length - total, total);
+      if (read === 0) break;
+      total += read;
+    }
+    return buffer.subarray(0, total);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function listDirectory(directory) {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  } catch {
+    return [];
+  }
+}
+
+function spawnGit(cwd, args, timeoutMs) {
+  try {
+    const result = spawnSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      windowsHide: true,
+      maxBuffer: 512 * 1024,
+    });
+    const timedOut = result.error !== undefined && result.error !== null;
+    return {
+      status: result.status,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      error: result.error instanceof Error ? result.error.message : null,
+      timedOut,
+    };
+  } catch (error) {
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      error: error instanceof Error ? error.message : String(error),
+      timedOut: false,
+    };
+  }
+}
+
+/**
+ * Run `git diff --check` against the staged + unstaged worktree.
+ *
+ * @param {{root?: string, timeoutMs?: number}} [options] - worktree root and subprocess deadline.
+ * @returns {{available: boolean, ok: boolean, clean: boolean, findings: object[], message: string, truncated: boolean}} bounded result.
+ */
+export function runGitDiffCheck(options = {}) {
+  const cwd = path.resolve(typeof options.root === "string" ? options.root : process.cwd());
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(500, Number(options.timeoutMs)) : DEFAULT_LIMITS.gitTimeoutMs;
+  const empty = { available: false, ok: false, clean: true, findings: [], message: "", truncated: false };
+  const inside = spawnGit(cwd, ["rev-parse", "--is-inside-work-tree"], timeoutMs);
+  if (inside.error !== null) return { ...empty, message: `git unavailable: ${inside.error}` };
+  if (inside.status !== 0 || inside.stdout.trim() !== "true") return { ...empty, message: "not a git worktree" };
+  const head = spawnGit(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], timeoutMs);
+  const args = head.status === 0 ? ["diff", "--check", "HEAD"] : ["diff", "--check"];
+  const result = spawnGit(cwd, args, timeoutMs);
+  if (result.error !== null) {
+    return { ...empty, available: true, message: `git diff --check failed: ${result.error}` };
+  }
+  const output = `${result.stdout}\n${result.stderr}`.trim();
+  const findings = [];
+  const notes = [];
+  const lines = output.length === 0 ? [] : output.split(/\r?\n/u);
+  for (const line of lines) {
+    if (findings.length >= GIT_DIFF_MAX_FINDINGS) break;
+    const match = /^(.+?):(\d+):\s*(.+)$/u.exec(line);
+    if (match === null) {
+      if (notes.length < 5) notes.push(redactText(line.slice(0, 200)));
+      continue;
+    }
+    findings.push({
+      kind: "git-diff-check",
+      severity: "low",
+      rule: "git-diff-check",
+      path: redactText(match[1].replaceAll("\\", "/")),
+      line: Number(match[2]),
+      message: redactText(match[3].slice(0, 200)),
+    });
+  }
+  const clean = findings.length === 0;
+  const detail = notes.length > 0 ? `; ${notes.join("; ")}` : "";
+  return {
+    available: true,
+    ok: true,
+    clean,
+    findings,
+    message: clean ? `clean${detail}` : `${findings.length} whitespace problem(s)${detail}`,
+    truncated: findings.length >= GIT_DIFF_MAX_FINDINGS,
+  };
+}
+
+/**
+ * Scan one worktree. The function is async only to observe cancellation between
+ * files; file I/O itself is synchronous and bounded by the resolved limits.
+ *
+ * @param {{root?: string, policy: object, env?: object, signal?: AbortSignal, overrides?: object, logger?: object}} options - scan inputs.
+ * @returns {Promise<object>} losslessly JSON-serializable report; findings never contain raw secret values.
+ */
+export async function scanProject(options = {}) {
+  const policy = options.policy;
+  const env = options.env ?? process.env;
+  const signal = options.signal;
+  const limits = resolveLimits(policy, options.overrides);
+  const resolvedRoot = path.resolve(typeof options.root === "string" && options.root.length > 0 ? options.root : process.cwd());
+  const report = {
+    ok: true,
+    root: resolvedRoot,
+    scannedAt: new Date().toISOString(),
+    limits,
+    stats: {
+      filesConsidered: 0,
+      filesScanned: 0,
+      bytesRead: 0,
+      directoriesVisited: 0,
+      skipped: { directories: 0, symlinks: 0, binary: 0, oversized: 0, unreadable: 0, depthLimit: 0, other: 0 },
+      limitsHit: { files: false, bytes: false, findings: false },
+    },
+    findings: [],
+    findingsTruncated: false,
+    aborted: false,
+    gitDiffCheck: null,
+  };
+
+  let rootStat;
+  try {
+    rootStat = fs.statSync(resolvedRoot);
+  } catch {
+    return { ...report, ok: false, error: `root does not exist: ${resolvedRoot}` };
+  }
+  if (!rootStat.isDirectory()) return { ...report, ok: false, error: `root is not a directory: ${resolvedRoot}` };
+
+  const findings = report.findings;
+  let stopWalk = false;
+
+  const addFinding = (finding) => {
+    if (findings.length >= limits.maxFindings) {
+      report.findingsTruncated = true;
+      report.stats.limitsHit.findings = true;
+      return false;
+    }
+    findings.push(finding);
+    return true;
+  };
+
+  const queue = [{ directory: resolvedRoot, depth: 0 }];
+  let cursor = 0;
+
+  const scanFile = (absolutePath, relativePath) => {
+    let fileStat;
+    try {
+      fileStat = fs.statSync(absolutePath);
+    } catch {
+      report.stats.skipped.unreadable += 1;
+      return;
+    }
+    if (fileStat.size > limits.maxFileSizeBytes) {
+      report.stats.skipped.oversized += 1;
+      addFinding({
+        kind: "oversized",
+        severity: "low",
+        rule: "oversized-file",
+        path: relativePath,
+        bytes: fileStat.size,
+        limit: limits.maxFileSizeBytes,
+        message: `file is ${fileStat.size} bytes (limit ${limits.maxFileSizeBytes}); content not scanned`,
+      });
+      return;
+    }
+    if (report.stats.bytesRead + fileStat.size > limits.maxTotalBytes) {
+      report.stats.limitsHit.bytes = true;
+      stopWalk = true;
+      return;
+    }
+    const protectedHit = matchProtectedPath(relativePath, { policy, env });
+    if (protectedHit !== undefined) {
+      addFinding({
+        kind: "protected-path",
+        severity: "high",
+        rule: protectedHit.id,
+        path: relativePath,
+        message: `protected path (${protectedHit.description}) present in the worktree`,
+      });
+    }
+    let buffer;
+    try {
+      buffer = readFileBounded(absolutePath, limits.maxFileSizeBytes);
+    } catch {
+      report.stats.skipped.unreadable += 1;
+      return;
+    }
+    if (buffer.length > limits.maxFileSizeBytes) {
+      report.stats.skipped.oversized += 1;
+      addFinding({
+        kind: "oversized",
+        severity: "low",
+        rule: "oversized-file",
+        path: relativePath,
+        bytes: fileStat.size,
+        limit: limits.maxFileSizeBytes,
+        message: `file grew past the ${limits.maxFileSizeBytes}-byte limit while scanning; content not scanned`,
+      });
+      return;
+    }
+    if (isProbablyBinary(buffer)) {
+      report.stats.skipped.binary += 1;
+      return;
+    }
+    const text = buffer.toString("utf8");
+    report.stats.filesScanned += 1;
+    report.stats.bytesRead += buffer.length;
+
+    const baseName = path.basename(relativePath);
+    const isEnvExample = ENV_EXAMPLE_NAME.test(baseName);
+    if (ENV_FILE_NAME.test(baseName) && !isEnvExample) {
+      const assignments = text.split(/\r?\n/u).filter((line) => /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=/u.test(line)).length;
+      addFinding({
+        kind: "env-file",
+        severity: "medium",
+        rule: "env-file",
+        path: relativePath,
+        entries: assignments,
+        message: `dotenv file with ${assignments} assignment(s); values are never copied to scan output`,
+      });
+    }
+    if (!isEnvExample) {
+      const remaining = Math.max(1, limits.maxFindings - findings.length);
+      for (const secret of scanTextForSecrets(text, { maxFindings: remaining })) {
+        if (!addFinding({ kind: "secret", ...secretFinding(relativePath, secret) })) return;
+      }
+    }
+
+    const extension = path.extname(baseName).toLowerCase();
+    if (SCRIPT_EXTENSIONS.has(extension) && text.length <= limits.maxScriptBytes) {
+      const lines = text.split(/\r?\n/u);
+      let perFile = 0;
+      for (let index = 0; index < lines.length && perFile < MAX_SCRIPT_FINDINGS_PER_FILE; index += 1) {
+        const line = lines[index].slice(0, MAX_COMMAND_LINE_CHARS);
+        if (line.trim().length === 0) continue;
+        const verdict = evaluateCommand(line, { policy });
+        if (verdict.action === "allow") continue;
+        const added = addFinding({
+          kind: "dangerous-command",
+          severity: verdict.action === "deny" ? "high" : "medium",
+          rule: verdict.primary.id,
+          path: relativePath,
+          line: index + 1,
+          action: verdict.action,
+          message: verdict.primary.description,
+          preview: redactText(line.slice(0, 160)),
+        });
+        if (!added) return;
+        perFile += 1;
+      }
+    }
+  };
+
+  while (cursor < queue.length) {
+    if (signal?.aborted) {
+      report.aborted = true;
+      break;
+    }
+    const current = queue[cursor];
+    cursor += 1;
+    report.stats.directoriesVisited += 1;
+    const entries = listDirectory(current.directory);
+    for (const entry of entries) {
+      if (signal?.aborted) {
+        report.aborted = true;
+        stopWalk = true;
+        break;
+      }
+      const absolutePath = path.join(current.directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        report.stats.skipped.symlinks += 1;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (SKIP_DIRECTORIES.has(entry.name)) {
+          report.stats.skipped.directories += 1;
+          continue;
+        }
+        if (current.depth + 1 > limits.maxDepth) {
+          report.stats.skipped.depthLimit += 1;
+          continue;
+        }
+        queue.push({ directory: absolutePath, depth: current.depth + 1 });
+        continue;
+      }
+      if (!entry.isFile()) {
+        report.stats.skipped.other += 1;
+        continue;
+      }
+      if (report.stats.filesConsidered >= limits.maxFiles) {
+        report.stats.limitsHit.files = true;
+        stopWalk = true;
+        break;
+      }
+      report.stats.filesConsidered += 1;
+      scanFile(absolutePath, path.relative(resolvedRoot, absolutePath).replaceAll("\\", "/"));
+      if (stopWalk) break;
+      if (findings.length >= limits.maxFindings) {
+        report.findingsTruncated = true;
+        report.stats.limitsHit.findings = true;
+        stopWalk = true;
+        break;
+      }
+    }
+    if (stopWalk) break;
+  }
+
+  if (!report.aborted) {
+    report.gitDiffCheck = runGitDiffCheck({ root: resolvedRoot, timeoutMs: limits.gitTimeoutMs });
+    for (const finding of report.gitDiffCheck.findings ?? []) {
+      if (!addFinding({ ...finding })) break;
+    }
+  }
+
+  report.findingsTotal = report.findings.length;
+  options.logger?.debug?.(
+    `[guardrails] scan files=${report.stats.filesScanned} findings=${report.findingsTotal} aborted=${report.aborted}`,
+  );
+  return report;
+}
+
+function secretFinding(relativePath, secret) {
+  return {
+    severity: secret.severity,
+    rule: secret.rule,
+    path: relativePath,
+    line: secret.line,
+    column: secret.column,
+    masked: secret.masked,
+    message: `${secret.label} detected (value redacted)`,
+  };
+}