@goodandready/dsh-approval-gate 0.1.12 → 0.1.13

package/lib/parsers/git.js

@@ -0,0 +1,321 @@
+// lib/parsers/git.js
+// Specialized Git AST and semantics parser with classification of read, local mutation,
+// remote operations, and destructive commands.
+// Resolves: #125, #103
+
+export const GIT_CATEGORY_READ = "read";
+export const GIT_CATEGORY_MUTATE_LOCAL = "mutate_local";
+export const GIT_CATEGORY_REMOTE = "remote";
+export const GIT_CATEGORY_DESTRUCTIVE = "destructive";
+
+const GLOBAL_FLAGS_WITH_VALUE = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+  "--super-prefix",
+  "--config-env",
+]);
+
+const READ_ONLY_VERBS = new Set([
+  "status",
+  "log",
+  "diff",
+  "show",
+  "rev-parse",
+  "describe",
+  "cat-file",
+  "ls-files",
+  "ls-tree",
+  "shortlog",
+  "blame",
+  "check-ignore",
+  "check-ref-format",
+  "var",
+  "version",
+  "help",
+  "symbolic-ref",
+  "name-rev",
+  "merge-base",
+  "count-objects",
+  "diff-index",
+  "diff-tree",
+  "for-each-ref",
+  "rev-list",
+]);
+
+const LOCAL_MUTATE_VERBS = new Set([
+  "add",
+  "commit",
+  "checkout",
+  "switch",
+  "branch",
+  "tag",
+  "stash",
+  "merge",
+  "rebase",
+  "cherry-pick",
+  "revert",
+  "mv",
+  "rm",
+  "init",
+  "apply",
+  "am",
+]);
+
+const REMOTE_VERBS = new Set([
+  "push",
+  "pull",
+  "fetch",
+  "clone",
+  "remote",
+  "submodule",
+]);
+
+/**
+ * Extracts global git options and isolates the git subcommand verb and its arguments.
+ *
+ * @param {string[]} argv - Array of tokens starting with 'git' or the first flag/verb.
+ * @returns {{ verb: string, args: string[], globalOptions: Record<string, string>, rawArgv: string[] }}
+ */
+export function parseGitArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return { verb: "", args: [], globalOptions: {}, rawArgv: [] };
+  }
+
+  const rawArgv = [...argv];
+  let idx = rawArgv[0] === "git" ? 1 : 0;
+  const globalOptions = {};
+
+  while (idx < rawArgv.length && rawArgv[idx].startsWith("-")) {
+    const flag = rawArgv[idx];
+    if (flag === "--") {
+      idx += 1;
+      break;
+    }
+    if (GLOBAL_FLAGS_WITH_VALUE.has(flag)) {
+      globalOptions[flag] = rawArgv[idx + 1] || "";
+      idx += 2;
+    } else if (flag.startsWith("--") && flag.includes("=")) {
+      const eqIdx = flag.indexOf("=");
+      globalOptions[flag.slice(0, eqIdx)] = flag.slice(eqIdx + 1);
+      idx += 1;
+    } else if (flag.length > 2 && flag[1] !== "-" && flag.startsWith("-C")) {
+      globalOptions["-C"] = flag.slice(2);
+      idx += 1;
+    } else {
+      globalOptions[flag] = "true";
+      idx += 1;
+    }
+  }
+
+  const verb = rawArgv[idx] || "";
+  const args = rawArgv.slice(idx + 1);
+
+  return { verb, args, globalOptions, rawArgv };
+}
+
+/**
+ * Checks whether an argument contains a specific short flag (e.g. 'f' in '-fdx').
+ *
+ * @param {string[]} args
+ * @param {string} flagChar
+ * @returns {boolean}
+ */
+function hasShortFlag(args, flagChar) {
+  for (const a of args) {
+    if (a === "--") break;
+    if (a.length > 1 && a[0] === "-" && a[1] !== "-" && a.includes(flagChar)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Analyzes and classifies a git subcommand and its arguments.
+ *
+ * @param {string} verb
+ * @param {string[]} args
+ * @returns {{
+ *   verb: string,
+ *   category: "read" | "mutate_local" | "remote" | "destructive",
+ *   isDestructive: boolean,
+ *   isRemote: boolean,
+ *   isForce: boolean,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function classifyGitOperation(verb, args = []) {
+  if (!verb) {
+    return {
+      verb: "",
+      category: GIT_CATEGORY_READ,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  const subArgs = Array.isArray(args) ? args : [];
+
+  // 1. Destructive operations check
+  if (verb === "reset" && subArgs.includes("--hard")) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-reset-hard",
+      detail: "Destructive git reset --hard discards all uncommitted modifications",
+    };
+  }
+
+  if (verb === "clean" && (subArgs.includes("-f") || subArgs.includes("--force") || hasShortFlag(subArgs, "f"))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-clean",
+      detail: "Destructive git clean removes untracked files irreversibly",
+    };
+  }
+
+  if (verb === "branch" && (subArgs.includes("-D") || (subArgs.includes("-d") && (subArgs.includes("-f") || subArgs.includes("--force"))))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-branch-force-delete",
+      detail: "Forceful git branch deletion (-D) risks losing unmerged commits",
+    };
+  }
+
+  // 2. Remote operations (#103: git push vs local git operations)
+  if (verb === "push") {
+    const isForce = subArgs.some((a) => (
+      a === "--force" ||
+      a === "-f" ||
+      a.startsWith("--force-with-lease") ||
+      a === "--delete" ||
+      (a[0] === "+" && a.length > 1)
+    )) || hasShortFlag(subArgs, "f");
+
+    if (isForce) {
+      return {
+        verb,
+        category: GIT_CATEGORY_DESTRUCTIVE,
+        isDestructive: true,
+        isRemote: true,
+        isForce: true,
+        reason: "git-force-push",
+        detail: "Forceful git push overwrites remote repository commit history",
+      };
+    }
+
+    return {
+      verb,
+      category: GIT_CATEGORY_REMOTE,
+      isDestructive: false,
+      isRemote: true,
+      isForce: false,
+      reason: "git-remote-push",
+      detail: "Publishing commits to a remote repository via git push requires confirmation",
+    };
+  }
+
+  if (verb === "checkout" && (subArgs.includes("-f") || subArgs.includes("--force") || (subArgs.includes("--") && subArgs.includes(".")))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-checkout-force",
+      detail: "Forceful checkout discards local working tree changes",
+    };
+  }
+
+  if (verb === "restore" && subArgs.includes("--worktree") && (subArgs.includes(".") || subArgs.includes("--staged"))) {
+    return {
+      verb,
+      category: GIT_CATEGORY_DESTRUCTIVE,
+      isDestructive: true,
+      isRemote: false,
+      isForce: true,
+      reason: "git-restore-worktree",
+      detail: "Restoring working tree files discards local changes",
+    };
+  }
+
+  if (REMOTE_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_REMOTE,
+      isDestructive: false,
+      isRemote: true,
+      isForce: false,
+    };
+  }
+
+  if (LOCAL_MUTATE_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_MUTATE_LOCAL,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  if (READ_ONLY_VERBS.has(verb)) {
+    return {
+      verb,
+      category: GIT_CATEGORY_READ,
+      isDestructive: false,
+      isRemote: false,
+      isForce: false,
+    };
+  }
+
+  return {
+    verb,
+    category: GIT_CATEGORY_MUTATE_LOCAL,
+    isDestructive: false,
+    isRemote: false,
+    isForce: false,
+  };
+}
+
+/**
+ * Full inspection of a git command invocation.
+ *
+ * @param {string[]} argv - Tokenized arguments
+ * @returns {{
+ *   verb: string,
+ *   args: string[],
+ *   category: "read" | "mutate_local" | "remote" | "destructive",
+ *   isDestructive: boolean,
+ *   isRemote: boolean,
+ *   isForce: boolean,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function inspectGitCommand(argv) {
+  const parsed = parseGitArgv(argv);
+  const classification = classifyGitOperation(parsed.verb, parsed.args);
+  return {
+    ...classification,
+    args: parsed.args,
+    globalOptions: parsed.globalOptions,
+  };
+}

package/lib/parsers/shell-cmds.js

@@ -0,0 +1,267 @@
+// lib/parsers/shell-cmds.js
+// Specialized shell AST parser for redirections, subshells, pipelines, and error masking.
+// Resolves: #126, #90
+
+import { REDIR_OPS, SPLIT_OPS } from "../tokenizer.js";
+import { isProtectedConfigPath, isPathTraversal, normalizeSeparators } from "../paths.js";
+
+const SHELLS = new Set(["bash", "sh", "dash", "zsh", "ksh", "ash"]);
+const INTERPRETERS = new Set(["python", "python2", "python3", "node", "nodejs", "perl", "ruby", "php"]);
+const DB_CLIENTS = new Set([
+  "sqlite3", "mysql", "psql", "pg_restore", "mongo", "mongosh", "redis-cli", "clickhouse-client",
+]);
+const DESTRUCTIVE_SQL = /\b(?:ALTER|DROP|TRUNCATE|DELETE\s+FROM|CREATE\s+(?:TABLE|DATABASE|INDEX))\b/i;
+const WRAPPERS = new Set(["sudo", "command", "builtin", "nohup", "time", "nice", "ionice", "stdbuf", "timeout", "exec"]);
+
+const SILENT_STDERR_PATTERN = /(?:2\s*>\s*\/dev\/null|&>\s*\/dev\/null|2>&1\s*>\s*\/dev\/null|>\s*\/dev\/null\s*2>&1)/i;
+const SILENT_EXIT_ZERO_PATTERN = /\|\|\s*(?:true|:|exit\s+0)\b/i;
+const SET_PLUS_E_PATTERN = /\bset\s+(?:\+[eE]|\+o\s+errexit)\b/i;
+
+/**
+ * Checks whether a path represents a raw physical or virtual disk device.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isDevicePath(path) {
+  if (typeof path !== "string" || !path.startsWith("/dev/")) return false;
+  const device = path.slice(5);
+  if (["null", "zero", "full", "random", "urandom", "stdin", "stdout", "stderr", "tty"].includes(device)) {
+    return false;
+  }
+  if (/^(?:sd[a-z]+\d*|hd[a-z]+\d*|vd[a-z]+\d*|xvd[a-z]+\d*|nvme\d+n\d+(?:p\d+)?|mmcblk\d+(?:p\d+)?|loop\d+)$/i.test(device)) {
+    return true;
+  }
+  return device.startsWith("mapper/") || device.startsWith("disk/by-id/") || device.startsWith("disk/by-uuid/");
+}
+
+/**
+ * Extracts redirection operators and their target paths from segment tokens.
+ *
+ * @param {Array<{ kind: string, value: string, dynamic?: boolean }>} seg
+ * @returns {Array<{ operator: string, path: string, dynamic: boolean }>}
+ */
+export function extractRedirects(seg) {
+  if (!Array.isArray(seg)) return [];
+  const redirects = [];
+  for (let i = 0; i < seg.length; i += 1) {
+    const t = seg[i];
+    if (t.kind === "op" && REDIR_OPS.has(t.value)) {
+      const next = seg[i + 1];
+      if (next && next.kind === "word") {
+        redirects.push({
+          operator: t.value,
+          path: next.value,
+          dynamic: Boolean(next.dynamic),
+        });
+      }
+    }
+  }
+  return redirects;
+}
+
+/**
+ * Evaluates security of extracted redirections (device writes, secret writes, path traversals).
+ *
+ * @param {Array<{ operator: string, path: string, dynamic: boolean }>} redirects
+ * @param {{ workspaceDir?: string, env?: Record<string, string> }} [options]
+ * @returns {{ deny?: boolean, ask?: boolean, reason?: string, detail?: string, path?: string } | null}
+ */
+export function inspectRedirectSecurity(redirects, options = {}) {
+  const workspaceDir = options.workspaceDir || process.cwd();
+  const env = options.env || process.env;
+
+  for (const redir of redirects) {
+    if (redir.dynamic) {
+      return {
+        ask: true,
+        reason: "dynamic-redirect",
+        detail: "The expanded redirect target cannot be verified; review before allowing",
+        path: redir.path,
+      };
+    }
+
+    const norm = normalizeSeparators(redir.path);
+
+    // Block device redirection
+    if (isDevicePath(norm)) {
+      return {
+        deny: true,
+        reason: "device-write",
+        detail: `Redirection targets block device ${norm}`,
+        path: redir.path,
+      };
+    }
+
+    // Block protected secrets redirection
+    if (isProtectedConfigPath(norm, env)) {
+      return {
+        deny: true,
+        reason: "secret-write",
+        detail: `Redirection targets protected configuration or credentials file ${norm}`,
+        path: redir.path,
+      };
+    }
+
+    // Block path traversal outside workspace
+    const isRel = !/^(?:\/|[A-Za-z]:\/|\/\/)/.test(norm);
+    const isExempt = !isRel && (
+      /^\/dev\/(?:null|zero|stdout|stderr|fd\/\d+)$/.test(norm) ||
+      /^(?:\/tmp|\/var\/tmp)(?:\/|$)/i.test(norm)
+    );
+
+    if (!isExempt && isPathTraversal(redir.path, workspaceDir)) {
+      return {
+        deny: true,
+        reason: "path-traversal",
+        detail: `Redirection escapes workspace boundary: ${redir.path}`,
+        path: redir.path,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects error masking and suppressed failures in shell commands.
+ * Resolves: #90 (SilentErrorGuard).
+ *
+ * @param {string} command - Raw command line
+ * @param {string[]} [argv] - Optional parsed argv
+ * @returns {{
+ *   masked: boolean,
+ *   kind?: "stderr-suppressed" | "exit-zero-forced" | "errexit-disabled",
+ *   pattern?: string,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function inspectSilentErrors(command, argv = []) {
+  if (typeof command !== "string" || !command.trim()) {
+    return { masked: false };
+  }
+
+  // 1. Check stderr suppression to /dev/null
+  if (SILENT_STDERR_PATTERN.test(command)) {
+    return {
+      masked: true,
+      kind: "stderr-suppressed",
+      pattern: "2>/dev/null",
+      reason: "silent-error-masked",
+      detail: "Command suppresses error output via stderr redirection to /dev/null",
+    };
+  }
+
+  // 2. Check forced success masking (|| true, || :)
+  if (SILENT_EXIT_ZERO_PATTERN.test(command)) {
+    return {
+      masked: true,
+      kind: "exit-zero-forced",
+      pattern: "|| true",
+      reason: "silent-error-masked",
+      detail: "Command forces a success exit code via logical OR fallback (|| true or || :)",
+    };
+  }
+
+  // 3. Check shell errexit unsetting (set +e)
+  if (SET_PLUS_E_PATTERN.test(command)) {
+    return {
+      masked: true,
+      kind: "errexit-disabled",
+      pattern: "set +e",
+      reason: "silent-error-masked",
+      detail: "Command disables shell error-exit checking (set +e)",
+    };
+  }
+
+  return { masked: false };
+}
+
+function unwrapExecutableFromSegment(seg) {
+  const words = seg.filter((t) => t.kind === "word").map((t) => t.value);
+  const takesValue = new Set(["-u", "--user", "-g", "--group", "-p", "-s", "--signal", "-k", "--kill-after", "-o", "-e", "-i"]);
+  let i = 0;
+  while (i < words.length) {
+    const val = words[i];
+    if (val === "then" || val === "do" || val === "{" || val === "!" || val === "}") {
+      i += 1;
+      continue;
+    }
+    if (val === "env") {
+      i += 1;
+      while (i < words.length && words[i].includes("=") && !words[i].startsWith("-")) i += 1;
+      continue;
+    }
+    if (val.includes("=") && !val.startsWith("-")) {
+      i += 1;
+      continue;
+    }
+    if (!WRAPPERS.has(val)) {
+      const parts = val.replace(/\\/g, "/").split("/");
+      return parts[parts.length - 1] || "";
+    }
+    i += 1;
+    while (i < words.length && words[i].startsWith("-")) {
+      const flag = words[i];
+      if (flag === "--") { i += 1; break; }
+      if (takesValue.has(flag)) i += 2;
+      else i += 1;
+    }
+    if (val === "timeout" && i < words.length) i += 1;
+    if (val === "nice" && i < words.length && /^[0-9-]+$/.test(words[i])) i += 1;
+  }
+  return "";
+}
+
+/**
+ * Scans tokens for dangerous downloader-to-shell or destructive SQL pipelines.
+ *
+ * @param {Array<{ kind: string, value: string }>} tokens
+ * @returns {{ dangerousPipeline: boolean, kind?: "curl-pipe" | "destructive-sql", reason?: string }}
+ */
+export function inspectPipelines(tokens) {
+  if (!Array.isArray(tokens)) return { dangerousPipeline: false };
+
+  let segment = [];
+  let pipelineHasDownloader = false;
+  let pipelineHasDestructiveSql = false;
+  let inPipeline = false;
+
+  for (const token of tokens) {
+    if (token.kind === "op" && SPLIT_OPS.has(token.value)) {
+      const cmd = unwrapExecutableFromSegment(segment);
+      if (inPipeline && (SHELLS.has(cmd) || INTERPRETERS.has(cmd)) && pipelineHasDownloader) {
+        return { dangerousPipeline: true, kind: "curl-pipe", reason: "curl-pipe" };
+      }
+      if (inPipeline && DB_CLIENTS.has(cmd) && pipelineHasDestructiveSql) {
+        return { dangerousPipeline: true, kind: "destructive-sql", reason: "destructive-sql" };
+      }
+
+      const continues = token.value === "|" || token.value === "|&";
+      if (continues) {
+        pipelineHasDownloader = pipelineHasDownloader || cmd === "curl" || cmd === "wget";
+        const segText = segment.filter((t) => t.kind === "word").map((t) => t.value).join(" ");
+        pipelineHasDestructiveSql = pipelineHasDestructiveSql || DESTRUCTIVE_SQL.test(segText);
+        inPipeline = true;
+      } else {
+        pipelineHasDownloader = false;
+        pipelineHasDestructiveSql = false;
+        inPipeline = false;
+      }
+      segment = [];
+      continue;
+    }
+    segment.push(token);
+  }
+
+  const finalCmd = unwrapExecutableFromSegment(segment);
+  if (inPipeline && (SHELLS.has(finalCmd) || INTERPRETERS.has(finalCmd)) && pipelineHasDownloader) {
+    return { dangerousPipeline: true, kind: "curl-pipe", reason: "curl-pipe" };
+  }
+  if (inPipeline && DB_CLIENTS.has(finalCmd) && pipelineHasDestructiveSql) {
+    return { dangerousPipeline: true, kind: "destructive-sql", reason: "destructive-sql" };
+  }
+
+  return { dangerousPipeline: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",
@@ -51,4 +51,4 @@
     "approval-gate",
     "safety"
   ]
-}
+}