@goodandready/dsh-approval-gate 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.6
+
+- Security: автоматическое раскрытие домашних путей `expandHome` (`~`, `$HOME`, `${HOME}`, `%USERPROFILE%`) в путях файлов, аргументах инструментов записи и перенаправлениях shell (Refs: #114).
+- Security: синтаксический разбор составных цепочек shell-команд `splitSubcommands` по операторам `&&`, `||`, `;`, `|`, `&` с сохранением кавычек и подстановок (Refs: #113).
+- Security: автоматический предохранитель сессии `CircuitBreaker` (блокировка зацикливания агента при 3 подряд или 20 общих отказах с принудительным запросом человека) (Refs: #110).
+- Engine: двухполосная предварительная фильтрация `BandsEngine`: Band 0 (Hard Deny regex) для мгновенной блокировки деструктивных команд и Band 1 (Safe Allow glob) для нулевой задержки на рутинных командах инспекции (Refs: #112).
+- Engine: 5-уровневый каскад принятия решений `SecurityEngine` (P0 Hard-Deny -> P1 Grants -> P2 Static Rules -> P3 LLM -> P4 Human Ask) с координацией предохранителя и правил (Refs: #122).
+
 ## 0.1.5
 
 - Security: block recursive `rm` with uppercase `-R` and `-Rf` flags in compliance with POSIX standard (Refs: #28).

package/lib/bands.js

@@ -0,0 +1,125 @@
+// lib/bands.js
+// Two-band deterministic filtering engine for dsh-approval-gate.
+// Band 0: Hard Deny (fast regexes for exfiltration, fork-bombs, disk wipes)
+// Band 1: Safe Allow (prefix globs & curated safe inspection commands)
+
+export const DEFAULT_DENY_PATTERNS = Object.freeze([
+  /\b(?:nc|ncat|netcat)\s+.*-e\s+/i,
+  /\/dev\/tcp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\/dev\/udp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\bmkfs(?:\.[a-z0-9]+)?\s+/i,
+  /\bdd\s+.*of=\/dev\/(?:sd|hd|vd|xvd|nvme|mmcblk|loop|mapper)/i,
+  /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
+  /\bchmod\s+(?:-R\s+)?(?:0?777|a\+rwx)\s+\/(?!tmp)/i,
+  /\bchown\s+(?:-R\s+)?root\b/i,
+  /\b(?:shutdown|reboot|poweroff|halt)\s*(?:-|$)/i,
+]);
+
+export const DEFAULT_ALLOW_GLOBS = Object.freeze([
+  "git status*",
+  "git diff*",
+  "git log*",
+  "git branch*",
+  "git show*",
+  "ls*",
+  "pwd*",
+  "cat *",
+  "head *",
+  "tail *",
+  "wc *",
+  "which *",
+  "whereis *",
+  "whoami*",
+  "node --version*",
+  "node -v*",
+  "npm test*",
+  "npm --version*",
+  "npm -v*",
+  "pnpm test*",
+  "pnpm --version*",
+  "pnpm -v*",
+  "yarn test*",
+  "cargo test*",
+  "cargo check*",
+  "cargo --version*",
+  "pytest*",
+  "python --version*",
+  "python3 --version*",
+  "echo *",
+]);
+
+export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
+  "read",
+  "read_file",
+  "readFile",
+  "view_file",
+  "glob",
+  "grep",
+  "find_files",
+  "search_code",
+  "file_search",
+  "list_dir",
+  "list_directory",
+]);
+
+/**
+ * Compile a prefix-glob into an anchored RegExp.
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function compileGlob(pattern) {
+  let source = "";
+  for (const ch of pattern) {
+    if (ch === "*") source += ".*";
+    else if (ch === "?") source += ".";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`, "i");
+}
+
+export class BandsEngine {
+  /**
+   * @param {{ denyPatterns?: Array<RegExp|string>, allowGlobs?: Array<RegExp|string>, readOnlyTools?: Array<string> }} [options]
+   */
+  constructor(options = {}) {
+    this.denyPatterns = (options.denyPatterns || DEFAULT_DENY_PATTERNS).map((p) =>
+      typeof p === "string" ? new RegExp(p, "i") : p
+    );
+    this.allowGlobs = (options.allowGlobs || DEFAULT_ALLOW_GLOBS).map((g) =>
+      typeof g === "string" ? compileGlob(g) : g
+    );
+    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+  }
+
+  /**
+   * Evaluates an execution request through Band 0 and Band 1.
+   * @param {string} tool - Tool name
+   * @param {string} [command] - Normalized command text (for bash)
+   * @returns {"deny" | "allow" | "unmatched"}
+   */
+  evaluate(tool, command) {
+    if (this.readOnlyTools.has(tool)) {
+      return "allow";
+    }
+
+    if (typeof command === "string" && command.trim().length > 0) {
+      const text = command.trim();
+
+      // Band 0: Hard Deny
+      for (const pattern of this.denyPatterns) {
+        if (pattern.test(text)) {
+          return "deny";
+        }
+      }
+
+      // Band 1: Safe Allow
+      for (const glob of this.allowGlobs) {
+        if (glob.test(text)) {
+          return "allow";
+        }
+      }
+    }
+
+    return "unmatched";
+  }
+}

package/lib/breaker.js

@@ -0,0 +1,97 @@
+// lib/breaker.js
+// Session-scoped Circuit Breaker for dsh-approval-gate.
+// Protects against agent thrashing / loops when blocked by security gates.
+
+export const DEFAULT_MAX_CONSECUTIVE_DENIES = 3;
+export const DEFAULT_MAX_TOTAL_DENIES = 20;
+
+export class CircuitBreaker {
+  /**
+   * @param {{ maxConsecutive?: number, maxTotal?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxConsecutive = options.maxConsecutive || DEFAULT_MAX_CONSECUTIVE_DENIES;
+    this.maxTotal = options.maxTotal || DEFAULT_MAX_TOTAL_DENIES;
+    /** @type {Map<string, { consecutive: number, total: number, tripped: boolean }>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * Get current state snapshot for a session.
+   * @param {string} [sessionId]
+   * @returns {{ consecutive: number, total: number, tripped: boolean }}
+   */
+  get(sessionId) {
+    const key = sessionId || "default";
+    let state = this.sessions.get(key);
+    if (!state) {
+      state = { consecutive: 0, total: 0, tripped: false };
+      this.sessions.set(key, state);
+    }
+    return { ...state };
+  }
+
+  /**
+   * Whether the breaker is currently tripped for this session.
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  isTripped(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return Boolean(state && state.tripped);
+  }
+
+  /**
+   * Record a security denial. Returns true if this call tripped the breaker.
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  countDeny(sessionId) {
+    const key = sessionId || "default";
+    let state = this.sessions.get(key);
+    if (!state) {
+      state = { consecutive: 0, total: 0, tripped: false };
+      this.sessions.set(key, state);
+    }
+    state.consecutive += 1;
+    state.total += 1;
+    const wasTripped = state.tripped;
+    if (state.consecutive >= this.maxConsecutive || state.total >= this.maxTotal) {
+      state.tripped = true;
+      return !wasTripped;
+    }
+    return false;
+  }
+
+  /**
+   * Reset the consecutive counter on an allowed operation.
+   * @param {string} [sessionId]
+   */
+  resetConsecutive(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state) state.consecutive = 0;
+  }
+
+  /**
+   * Fully resume auto-mode after human approval.
+   * @param {string} [sessionId]
+   */
+  resume(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state) {
+      state.consecutive = 0;
+      state.total = 0;
+      state.tripped = false;
+    }
+  }
+
+  /**
+   * Clear all session tracking states.
+   */
+  clear() {
+    this.sessions.clear();
+  }
+}

package/lib/engine.js

@@ -0,0 +1,108 @@
+// lib/engine.js
+// 5-tier Security Decision Engine for dsh-approval-gate.
+// Waterfall:
+// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files)
+// P1: Session Grants (scoped temporary allowances)
+// P2: Static Rules / Safe Allow (Bands Band 1 + safe read-only commands)
+// P3: Optional Semantic Classifier
+// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker)
+
+import { BandsEngine } from "./bands.js";
+import { CircuitBreaker } from "./breaker.js";
+import { inspectExecution } from "./inspect.js";
+
+export class SecurityEngine {
+  /**
+   * @param {{
+   *   bands?: BandsEngine,
+   *   breaker?: CircuitBreaker,
+   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[] },
+   *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
+   *   grantRegistry?: { decide: (tool: string, args: any) => "allow"|"no-match" }
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.bands = options.bands || new BandsEngine(options);
+    this.breaker = options.breaker || new CircuitBreaker(options);
+    this.inspectConfig = options.inspectConfig || {};
+    this.classifier = options.classifier || null;
+    this.grantRegistry = options.grantRegistry || null;
+  }
+
+  /**
+   * Evaluates an execution request through the P0-P4 waterfall.
+   *
+   * @param {{ name: string, arguments?: any }} execution - Tool call
+   * @param {{ sessionId?: string, knobs?: any }} [context] - Context options
+   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string }}
+   */
+  decide(execution, context = {}) {
+    const sessionId = context.sessionId || "default";
+    const toolName = execution && execution.name;
+    const command = execution && execution.arguments && execution.arguments.command;
+
+    // Fast-path Band 0 Hard Deny
+    const bandVerdict = this.bands.evaluate(toolName, command);
+    if (bandVerdict === "deny") {
+      this.breaker.countDeny(sessionId);
+      return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command };
+    }
+
+    // Inspect execution for hard denials and syntax checks
+    const hit = inspectExecution(execution, this.inspectConfig);
+    if (hit.deny) {
+      this.breaker.countDeny(sessionId);
+      return { verdict: "deny", stage: "P0", reason: hit.reason || "hard-deny", detail: hit.detail || hit.snippet };
+    }
+
+    // P1: Session Grants
+    if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
+      const grantMatch = this.grantRegistry.decide(toolName, execution.arguments);
+      if (grantMatch === "allow") {
+        this.breaker.resetConsecutive(sessionId);
+        return { verdict: "allow", stage: "P1", reason: "session-grant" };
+      }
+    }
+
+    // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
+    if (this.breaker.isTripped(sessionId)) {
+      return {
+        verdict: "ask",
+        stage: "P4",
+        reason: "circuit-breaker-tripped",
+        detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required."
+      };
+    }
+
+    // P2: Static Rules / Safe Allow
+    if (bandVerdict === "allow") {
+      this.breaker.resetConsecutive(sessionId);
+      return { verdict: "allow", stage: "P2", reason: "safe-allow" };
+    }
+
+    // P3: Optional Semantic Classifier
+    if (this.classifier && typeof this.classifier === "function") {
+      try {
+        const cls = this.classifier(execution, context);
+        if (cls && cls.verdict === "allow") {
+          this.breaker.resetConsecutive(sessionId);
+          return { verdict: "allow", stage: "P3", reason: cls.reason || "classifier-allow" };
+        }
+        if (cls && cls.verdict === "deny") {
+          this.breaker.countDeny(sessionId);
+          return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny" };
+        }
+      } catch (err) {
+        // Classifier error fails closed to P4 Ask
+      }
+    }
+
+    // P4: Human Ask (uncertain syntax or unlisted command)
+    if (hit.ask) {
+      return { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet };
+    }
+
+    // Safe default for unclassified commands
+    return { verdict: "allow", stage: "P2", reason: "unmatched-allow" };
+  }
+}

package/lib/index.js

@@ -130,3 +130,9 @@ export function apply(ctx, config) {
   }
   return mount();
 }
+
+export { SecurityEngine } from "./engine.js";
+export { BandsEngine } from "./bands.js";
+export { CircuitBreaker } from "./breaker.js";
+export { expandHome } from "./paths.js";
+export { splitSubcommands } from "./tokenizer.js";

package/lib/inspect.js

@@ -1,8 +1,10 @@
 import { DYNAMIC_MARKER, HEREDOC_OPS, REDIR_OPS, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
+import { expandHome } from "./paths.js";
 import { askMessage, denyMessage, sessionTag } from "./messages.js";
 
-export { DYNAMIC_MARKER, tokenize } from "./tokenizer.js";
+export { DYNAMIC_MARKER, tokenize, splitSubcommands } from "./tokenizer.js";
 export { askMessage, denyMessage, sessionTag } from "./messages.js";
+export { expandHome } from "./paths.js";
 
 // Pure command/path inspector for dsh-approval-gate.
 // No Cordis imports: unit tests run this without the harness.
@@ -36,11 +38,12 @@ export function basename(path) {
   return parts[parts.length - 1] || "";
 }
 
-export function isProtectedPath(path) {
+export function isProtectedPath(path, env = process.env) {
   if (typeof path !== "string" || path.trim() === "") return false;
-  const normalized = path.replace(/\\/g, "/");
+  const expanded = expandHome(path, env);
+  const normalized = expanded.replace(/\\/g, "/");
   if (normalized.includes("/etc/sudoers.d/")) return true;
-  const base = basename(path);
+  const base = basename(normalized);
   if (base === ".env" || base.startsWith(".env.")) return true;
   if (/^credentials\.ya?ml$/i.test(base)) return true;
   if (/^settings\.ya?ml$/i.test(base)) return true;

package/lib/paths.js

@@ -0,0 +1,25 @@
+// lib/paths.js
+// Home path expansion and path boundary helpers for dsh-approval-gate.
+
+/**
+ * Expand `~`, `${HOME}`, `$HOME`, and `%USERPROFILE%` at the start of or within a path.
+ *
+ * @param {string} p - Path or string containing path references
+ * @param {Record<string, string|undefined>} [env] - Environment dictionary (defaults to process.env)
+ * @returns {string} Normalized path with home expanded
+ */
+export function expandHome(p, env = process.env) {
+  if (typeof p !== "string" || p.trim() === "") return p;
+  const home = (env && (env.HOME || env.USERPROFILE)) || "";
+  if (!home) return p;
+  const cleanHome = home.replace(/[/\\]+$/, "");
+
+  let res = p;
+  // Expand leading ~ or ~/ or ~\
+  res = res.replace(/^~(?=$|[/\\])/, cleanHome);
+  // Expand ${HOME} and $HOME
+  res = res.replace(/\$\{HOME\}|\$HOME/g, cleanHome);
+  // Expand %USERPROFILE% (Windows)
+  res = res.replace(/%USERPROFILE%/gi, cleanHome);
+  return res;
+}

package/lib/tokenizer.js

@@ -317,3 +317,64 @@ export function tokenize(src) {
   return { ok: true, tokens: tokens };
 }
 
+
+/**
+ * Splits a complex shell command line into individual subcommands across pipeline
+ * and sequence operators (&&, ||, ;, |, &).
+ * Respects single quotes, double quotes, subshells $(...), backticks, and heredocs.
+ *
+ * @param {string} command - Raw shell command
+ * @returns {Array<{ command: string, argv: string[], operator: string|null, tokens: Array<any>, ok: boolean }>}
+ */
+export function splitSubcommands(command) {
+  if (typeof command !== "string" || command.trim() === "") return [];
+  const tok = tokenize(command);
+  const result = [];
+  let currentTokens = [];
+  let prevOp = null;
+
+  function pushSub(tokens, op) {
+    if (!tokens.length) return;
+    const words = tokens
+      .filter((t) => t.kind === "word")
+      .map((t) => t.value);
+    const subStr = tokens
+      .map((t) => {
+        if (t.kind === "heredoc") return `<<${t.marker}`;
+        return t.value;
+      })
+      .join(" ")
+      .trim();
+    result.push({
+      command: subStr,
+      argv: words,
+      operator: op,
+      tokens: tokens,
+      ok: tok.ok,
+    });
+  }
+
+  for (const t of tok.tokens) {
+    if (t.kind === "op" && SPLIT_OPS.has(t.value)) {
+      pushSub(currentTokens, prevOp);
+      currentTokens = [];
+      prevOp = t.value;
+      continue;
+    }
+    currentTokens.push(t);
+  }
+
+  pushSub(currentTokens, prevOp);
+
+  if (result.length === 0 && command.trim().length > 0) {
+    result.push({
+      command: command.trim(),
+      argv: command.trim().split(/\s+/),
+      operator: null,
+      tokens: [],
+      ok: false,
+    });
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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",