@goodandready/dsh-approval-gate 0.1.13 → 0.1.15

package/lib/rules-loader.js

@@ -0,0 +1,175 @@
+// lib/rules-loader.js
+// Cascading declarative YAML rules loader and evaluator for dsh-approval-gate (#38, #45, #44, #93).
+// Evaluates rules cascading from workspace (.dsh/rules.yaml), user (~/.dsh/rules.yaml) and builtin threats.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseYaml } from "./yaml-parser.js";
+import { evaluateWhen } from "./when-matcher.js";
+import { HotwordsMatcher } from "./hotwords.js";
+
+export const BUILTIN_RULES_FILE = path.join("rules", "builtin-high-risk.yaml");
+export const WORKSPACE_RULES_REL = path.join(".dsh", "rules.yaml");
+export const USER_RULES_REL = path.join(".dsh", "rules.yaml");
+
+/**
+ * @typedef {Object} CompiledRule
+ * @property {string} id
+ * @property {string} [tool]
+ * @property {RegExp} regex
+ * @property {"allow" | "deny" | "ask"} verdict
+ * @property {string} reason
+ * @property {string} [description]
+ * @property {Record<string, any>} [when]
+ * @property {string} source - "workspace" | "user" | "builtin"
+ */
+
+export class DeclarativeRulesEngine {
+  /**
+   * @param {{
+   *   workspaceDir?: string,
+   *   userHomeDir?: string,
+   *   builtinCatalogPath?: string,
+   *   customRules?: any[],
+   *   hotwords?: HotwordsMatcher
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+    this.userHomeDir = options.userHomeDir || (os.homedir ? os.homedir() : (process.env.HOME || process.env.USERPROFILE || ""));
+    this.builtinCatalogPath = options.builtinCatalogPath || "";
+    this.hotwords = options.hotwords || new HotwordsMatcher();
+
+    /** @type {CompiledRule[]} */
+    this.rules = [];
+    this.load(options);
+  }
+
+  /**
+   * Loads and merges all rule sources (workspace -> user -> builtin).
+   *
+   * @param {{ customRules?: any[] }} [options]
+   */
+  load(options = {}) {
+    this.rules = [];
+    const rawList = [];
+
+    // 1. Workspace local rules (.dsh/rules.yaml)
+    if (this.workspaceDir) {
+      const wsPath = path.isAbsolute(this.workspaceDir)
+        ? path.join(this.workspaceDir, WORKSPACE_RULES_REL)
+        : path.resolve(this.workspaceDir, WORKSPACE_RULES_REL);
+      const wsRules = this._loadFile(wsPath, "workspace");
+      rawList.push(...wsRules);
+    }
+
+    // 2. User global rules (~/.dsh/rules.yaml)
+    if (this.userHomeDir) {
+      const userPath = path.join(this.userHomeDir, USER_RULES_REL);
+      const userRules = this._loadFile(userPath, "user");
+      rawList.push(...userRules);
+    }
+
+    // 3. Builtin threat catalog
+    const builtinPath = this.builtinCatalogPath || path.resolve(process.cwd(), BUILTIN_RULES_FILE);
+    const builtinRules = this._loadFile(builtinPath, "builtin");
+    rawList.push(...builtinRules);
+
+    // 4. In-memory / custom rules passed via options
+    if (Array.isArray(options.customRules)) {
+      rawList.unshift(...options.customRules.map((r) => ({ ...r, source: "custom" })));
+    }
+
+    // Compile and deduplicate by rule ID (first defined wins!)
+    const seenIds = new Set();
+    for (const r of rawList) {
+      if (!r || !r.id || !r.verdict) continue;
+      if (seenIds.has(r.id)) continue;
+      seenIds.add(r.id);
+
+      const patternStr = r.pattern || r.regex || r.command;
+      if (!patternStr) continue;
+
+      try {
+        const regex = patternStr instanceof RegExp ? patternStr : new RegExp(patternStr, r.flags || "");
+        this.rules.push({
+          id: String(r.id),
+          tool: r.tool ? String(r.tool).toLowerCase() : undefined,
+          regex,
+          verdict: r.verdict,
+          reason: r.reason || r.id,
+          description: r.description,
+          when: r.when,
+          source: r.source || "custom",
+        });
+      } catch {
+        // Invalid regex in user file must not crash the loader
+      }
+    }
+  }
+
+  /**
+   * Safely reads and parses a rules file.
+   * @private
+   */
+  _loadFile(filePath, source) {
+    if (!filePath || !fs.existsSync(filePath)) return [];
+    try {
+      const text = fs.readFileSync(filePath, "utf8");
+      const doc = parseYaml(text);
+      const rules = Array.isArray(doc) ? doc : (doc && Array.isArray(doc.rules) ? doc.rules : []);
+      return rules.map((r) => ({ ...r, source }));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Evaluates a command against the declarative rule chain.
+   *
+   * @param {string} toolName
+   * @param {string} command
+   * @param {{ os?: string, branch?: string, env?: Record<string, string>, cwd?: string }} [context]
+   * @returns {{ match: boolean, ruleId?: string, verdict?: "allow"|"deny"|"ask", reason?: string, source?: string }}
+   */
+  evaluate(toolName, command, context = {}) {
+    if (!command || typeof command !== "string") {
+      return { match: false };
+    }
+
+    const normTool = String(toolName || "").toLowerCase();
+    const envContext = { ...context, tool: normTool };
+
+    for (let i = 0; i < this.rules.length; i += 1) {
+      const rule = this.rules[i];
+
+      // Tool filter
+      if (rule.tool && rule.tool !== normTool) {
+        continue;
+      }
+
+      // Context predicate (when) filter
+      if (rule.when && !evaluateWhen(rule.when, envContext)) {
+        continue;
+      }
+
+      // Pattern match
+      if (rule.regex.test(command)) {
+        return {
+          match: true,
+          ruleId: rule.id,
+          verdict: rule.verdict,
+          reason: rule.reason,
+          source: rule.source,
+        };
+      }
+    }
+
+    return { match: false };
+  }
+
+  get ruleCount() {
+    return this.rules.length;
+  }
+}

package/lib/when-matcher.js

@@ -0,0 +1,89 @@
+// lib/when-matcher.js
+// Conditional predicates (when) evaluator for dsh-approval-gate rules (#44).
+// Evaluates OS, git branch, environment variables, and tool context.
+
+/**
+ * Checks a string or regex value against a target with negation support.
+ *
+ * @param {string | RegExp} expected
+ * @param {string} actual
+ * @returns {boolean}
+ */
+export function matchConditionValue(expected, actual) {
+  if (expected === undefined || expected === null) return true;
+  const actualStr = String(actual || "");
+
+  if (typeof expected === "string") {
+    const trimmed = expected.trim();
+    if (trimmed.startsWith("!")) {
+      const negated = trimmed.slice(1).trim();
+      return actualStr !== negated;
+    }
+    return actualStr === trimmed;
+  }
+
+  if (expected instanceof RegExp) {
+    return expected.test(actualStr);
+  }
+
+  return expected === actual;
+}
+
+/**
+ * Evaluates a rule's `when` section against runtime facts.
+ *
+ * @param {Record<string, any>} [when] - When clause from rule
+ * @param {{
+ *   os?: string,
+ *   branch?: string,
+ *   tool?: string,
+ *   env?: Record<string, string | undefined>
+ * }} [context] - Environmental context
+ * @returns {boolean}
+ */
+export function evaluateWhen(when, context = {}) {
+  if (!when || typeof when !== "object" || Object.keys(when).length === 0) {
+    return true;
+  }
+
+  const currentOs = context.os || process.platform;
+  const currentBranch = context.branch || "";
+  const currentTool = (context.tool || "").toLowerCase();
+  const currentEnv = context.env || process.env || {};
+
+  // 1. OS check
+  if (when.os !== undefined) {
+    if (!matchConditionValue(when.os, currentOs)) {
+      return false;
+    }
+  }
+
+  // 2. Branch check
+  if (when.branch !== undefined) {
+    if (!matchConditionValue(when.branch, currentBranch)) {
+      return false;
+    }
+  }
+
+  // 3. Tool check
+  if (when.tool !== undefined) {
+    if (!matchConditionValue(String(when.tool).toLowerCase(), currentTool)) {
+      return false;
+    }
+  }
+
+  // 4. Environment variables check
+  if (when.env && typeof when.env === "object") {
+    for (const [varName, expectedVal] of Object.entries(when.env)) {
+      const actualVal = currentEnv[varName];
+      if (typeof expectedVal === "boolean") {
+        const isPresent = actualVal !== undefined && actualVal !== "" && actualVal !== "0" && actualVal !== "false";
+        if (isPresent !== expectedVal) return false;
+      } else if (!matchConditionValue(expectedVal, actualVal)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}

package/lib/yaml-parser.js

@@ -0,0 +1,210 @@
+// lib/yaml-parser.js
+// Compact zero-dependency YAML subset parser for dsh-approval-gate (#38).
+// Supports scalar values, lists, mappings, nested blocks, and comments.
+
+/**
+ * Parses scalar string into JS primitive (string, number, boolean, null).
+ *
+ * @param {string} val
+ * @returns {any}
+ */
+export function parseScalar(val) {
+  if (val === undefined || val === null) return null;
+  const trimmed = val.trim();
+  if (trimmed === "" || trimmed === "~" || trimmed === "null") return null;
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+
+  // Single or double quoted strings
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    const quote = trimmed[0];
+    const inner = trimmed.slice(1, -1);
+    if (quote === '"') {
+      return inner
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, "\\")
+        .replace(/\\n/g, "\n")
+        .replace(/\\t/g, "\t");
+    }
+    return inner.replace(/''/g, "'");
+  }
+
+  // Numbers
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+
+  return trimmed;
+}
+
+/**
+ * Strips comments from a line, preserving comments inside quotes.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function stripComment(line) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+    } else if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+    } else if (ch === "#" && !inSingle && !inDouble) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+/**
+ * Parses a simple YAML string into JavaScript objects and arrays.
+ *
+ * @param {string} yamlText
+ * @returns {any}
+ */
+export function parseYaml(yamlText) {
+  if (typeof yamlText !== "string" || !yamlText.trim()) return {};
+
+  const trimmedText = yamlText.trim();
+  // Fast path for JSON-compatible YAML
+  if (trimmedText.startsWith("{") || trimmedText.startsWith("[")) {
+    try {
+      return JSON.parse(trimmedText);
+    } catch {
+      // Fallback to YAML line parser
+    }
+  }
+
+  const rawLines = yamlText.split(/\r?\n/);
+  const lines = [];
+
+  for (let i = 0; i < rawLines.length; i += 1) {
+    const clean = stripComment(rawLines[i]);
+    if (!clean.trim()) continue; // skip blank / comment-only lines
+    const indent = clean.match(/^(\s*)/)[0].length;
+    lines.push({ indent, text: clean.trim(), lineNum: i + 1 });
+  }
+
+  if (lines.length === 0) return {};
+
+  let index = 0;
+
+  function parseBlock(currentIndent) {
+    if (index >= lines.length) return null;
+
+    const firstLine = lines[index];
+    if (firstLine.text.startsWith("- ") || firstLine.text === "-") {
+      // It's a sequence (array)
+      const list = [];
+      while (index < lines.length) {
+        const line = lines[index];
+        if (line.indent < currentIndent) break;
+        if (line.indent > currentIndent) {
+          // Handled within child elements
+          break;
+        }
+
+        if (line.text.startsWith("- ") || line.text === "-") {
+          const itemPayload = line.text.slice(2).trim();
+          index += 1;
+
+          if (!itemPayload) {
+            // Nested block under list item
+            if (index < lines.length && lines[index].indent > line.indent) {
+              list.push(parseBlock(lines[index].indent));
+            } else {
+              list.push(null);
+            }
+          } else if (itemPayload.includes(":") && !itemPayload.startsWith("{")) {
+            // Key-value on the same line as list dash: e.g. "- id: my-rule"
+            const colonIdx = itemPayload.indexOf(":");
+            const k = itemPayload.slice(0, colonIdx).trim();
+            const v = itemPayload.slice(colonIdx + 1).trim();
+            const obj = {};
+            if (v) {
+              obj[k] = parseScalar(v);
+            } else {
+              // Nested under this key
+              if (index < lines.length && lines[index].indent > line.indent) {
+                obj[k] = parseBlock(lines[index].indent);
+              } else {
+                obj[k] = null;
+              }
+            }
+
+            // Read subsequent keys belonging to this list item
+            const itemIndent = line.indent + 2;
+            while (index < lines.length) {
+              const nextLine = lines[index];
+              if (nextLine.indent < itemIndent) break;
+              if (nextLine.text.startsWith("- ") && nextLine.indent <= line.indent) break;
+
+              if (nextLine.text.includes(":")) {
+                const cIdx = nextLine.text.indexOf(":");
+                const subK = nextLine.text.slice(0, cIdx).trim();
+                const subV = nextLine.text.slice(cIdx + 1).trim();
+                index += 1;
+                if (subV) {
+                  obj[subK] = parseScalar(subV);
+                } else {
+                  if (index < lines.length && lines[index].indent > nextLine.indent) {
+                    obj[subK] = parseBlock(lines[index].indent);
+                  } else {
+                    obj[subK] = null;
+                  }
+                }
+              } else {
+                index += 1;
+              }
+            }
+            list.push(obj);
+          } else {
+            // Scalar list item: e.g. "- item1"
+            list.push(parseScalar(itemPayload));
+          }
+        } else {
+          break;
+        }
+      }
+      return list;
+    } else {
+      // It's a mapping (object)
+      const obj = {};
+      while (index < lines.length) {
+        const line = lines[index];
+        if (line.indent < currentIndent) break;
+        if (line.indent > currentIndent) {
+          break;
+        }
+
+        if (line.text.includes(":")) {
+          const colonIdx = line.text.indexOf(":");
+          const key = line.text.slice(0, colonIdx).trim();
+          const rest = line.text.slice(colonIdx + 1).trim();
+          index += 1;
+
+          if (rest) {
+            obj[key] = parseScalar(rest);
+          } else {
+            // Value is a nested block
+            if (index < lines.length && lines[index].indent > line.indent) {
+              obj[key] = parseBlock(lines[index].indent);
+            } else {
+              obj[key] = null;
+            }
+          }
+        } else {
+          index += 1;
+        }
+      }
+      return obj;
+    }
+  }
+
+  const result = parseBlock(lines[0].indent);
+  return result || {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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",
@@ -11,6 +11,7 @@
   },
   "files": [
     "lib",
+    "rules",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",
@@ -51,4 +52,4 @@
     "approval-gate",
     "safety"
   ]
-}
+}

package/rules/builtin-high-risk.yaml

@@ -0,0 +1,81 @@
+version: 1
+catalog: builtin-high-risk
+description: Core Band 0 critical security threat definitions for dsh-approval-gate
+
+rules:
+  - id: builtin-recursive-rm
+    tool: bash
+    pattern: '(?:^|[;&|\s])rm\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+(?:/(?:$|\s|\*)|/(?:var|etc|usr|bin|sbin|boot|lib|root|home)(?:/|$|\s|\*))'
+    verdict: deny
+    reason: recursive-rm
+    description: Recursive deletion of critical system directory
+
+  - id: builtin-process-signal
+    tool: bash
+    pattern: '(?:^|[;&|\s])kill\s+-[a-zA-Z0-9]*9\s+1(?:$|\s)'
+    verdict: deny
+    reason: process-signal
+    description: SIGKILL targeted at PID 1 / init
+
+  - id: builtin-service-stop
+    tool: bash
+    pattern: '(?:^|[;&|\s])systemctl\s+(?:stop|disable|mask|poweroff|reboot|halt)(?:$|\s)'
+    verdict: deny
+    reason: service-control
+    description: System service shutdown, masking, or machine halt
+
+  - id: builtin-mkfs-format
+    tool: bash
+    pattern: '(?:^|[;&|\s])(?:mkfs|fdisk|parted)\b'
+    verdict: deny
+    reason: mkfs-device
+    description: Block device partitioning or filesystem formatting
+
+  - id: builtin-curl-pipe-shell
+    tool: bash
+    pattern: '(?:curl|wget)\s+[^|;]+?\|\s*(?:sudo\s+)?(?:bash|sh|zsh|python|perl|ruby)'
+    verdict: deny
+    reason: curl-pipe
+    description: Piping downloaded remote web content directly into shell interpreter
+
+  - id: builtin-reverse-shell-nc
+    tool: bash
+    pattern: '(?:^|[;&|\s])(?:nc|netcat|ncat)\s+.*-[a-zA-Z0-9]*e\s+(?:/bin/(?:ba)?sh|sh)'
+    verdict: deny
+    reason: band-hard-deny
+    description: Netcat reverse shell execution
+
+  - id: builtin-reverse-shell-tcp
+    tool: bash
+    pattern: '/dev/tcp/\d+\.\d+\.\d+\.\d+/\d+'
+    verdict: deny
+    reason: band-hard-deny
+    description: Direct bash TCP socket reverse shell attempt
+
+  - id: builtin-git-reset-hard
+    tool: bash
+    pattern: '(?:^|[;&|\s])git\s+reset\s+--hard'
+    verdict: deny
+    reason: git-reset-hard
+    description: Destructive git reset --hard discarding working tree
+
+  - id: builtin-git-clean-force
+    tool: bash
+    pattern: '(?:^|[;&|\s])git\s+clean\s+-[a-zA-Z0-9]*f'
+    verdict: deny
+    reason: git-clean
+    description: Destructive git clean -f discarding untracked files
+
+  - id: builtin-git-force-push
+    tool: bash
+    pattern: '(?:^|[;&|\s])git\s+push\s+.*(?:--force|-f\b|\+refs/)'
+    verdict: deny
+    reason: git-force-push
+    description: Destructive forced push to git repository
+
+  - id: builtin-chmod-chown-root
+    tool: bash
+    pattern: '(?:^|[;&|\s])(?:chmod|chown)\s+-[a-zA-Z]*[rR].*\s+/(?:$|\s|\*|etc|var|usr|root)'
+    verdict: deny
+    reason: chmod-chown
+    description: Recursive permission mutation of system root directories