@goodandready/dsh-approval-gate 0.1.14 → 0.1.16

package/lib/engine.js

@@ -1,11 +1,11 @@
 // lib/engine.js
 // 5-tier Security Decision Engine for dsh-approval-gate.
 // Waterfall:
-// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files + retry exhaustion)
-// P1: Session Grants (scoped temporary allowances)
+// P0: Hard Deny (Bands Band 0 + Declarative Rules Deny + inspectExecution hard denials + protected files + retry exhaustion + fail-closed audit)
+// P1: Session Grants & Declarative Allow (scoped temporary allowances and whitelists)
 // 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)
+// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker / declarative ask / lockedAsk)
 
 import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
@@ -15,6 +15,57 @@ import { VerdictCache } from "./cache.js";
 import { RetryExhaustionGuard } from "./retry-exhaustion.js";
 import { QualityLedger } from "./ledger.js";
 import { AuditLogger } from "./audit-log.js";
+import { DeclarativeRulesEngine } from "./rules-loader.js";
+import { BlockCounters } from "./counters.js";
+
+/**
+ * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
+ * Locked ask operations can never be auto-approved by unattended timeouts or fallback heuristics.
+ *
+ * @param {string} [toolName]
+ * @param {string} [command]
+ * @param {any} [execution]
+ * @returns {boolean}
+ */
+export function isCriticalOperation(toolName, command, execution) {
+  const cmd = String(command || "").trim();
+  const tool = String(toolName || "").trim();
+  if (!cmd && !tool) return false;
+
+  // 1. Root and privilege escalation
+  if (/^(sudo|su|doas)\b/i.test(cmd)) return true;
+  if (/\b(chmod\s+(-[a-zA-Z]*\s+)?777|chown\s+(-[a-zA-Z]*\s+)?root)\b/i.test(cmd)) return true;
+
+  // 2. Recursive or bulk destructive deletion
+  if (/\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+|--recursive\s+)/i.test(cmd)) return true;
+  if (/\b(shred|wipefs)\b/i.test(cmd)) return true;
+
+  // 3. Sensitive credentials and SSH access
+  if (/(\.ssh\/(id_|authorized_keys|known_hosts)|\.gnupg\/|\/etc\/shadow)/i.test(cmd)) return true;
+
+  // 4. Raw disk and filesystem manipulation
+  if (/\b(mkfs|fdisk|parted)\b/i.test(cmd)) return true;
+  if (/\bdd\s+.*of=\/dev\/(sd[a-z]|nvme|vd[a-z]|hd[a-z]|loop)/i.test(cmd)) return true;
+
+  // 5. Remote shell piping and reverse shells
+  if (/curl\s+.*\|\s*(bash|sh|python|perl)/i.test(cmd)) return true;
+  if (/\b(nc|ncat|netcat)\s+.*-e\s+/i.test(cmd)) return true;
+  if (/>&\s*\/dev\/tcp\//i.test(cmd)) return true;
+
+  // 6. System halts and service shutdowns
+  if (/\b(shutdown|reboot|poweroff|halt|init\s+0)\b/i.test(cmd)) return true;
+  if (/systemctl\s+(stop|disable|mask)\s+(sshd|systemd|ufw|iptables)/i.test(cmd)) return true;
+
+  // 7. Protected file writes via tools
+  if (tool === "write_to_file" || tool === "edit" || tool === "replace_file_content" || tool === "str_replace_editor") {
+    const target = execution && execution.arguments && (execution.arguments.TargetFile || execution.arguments.target_file || execution.arguments.path || "");
+    if (typeof target === "string" && /(\/etc\/|\.ssh\/|\/boot\/|\/sys\/|\/proc\/)/i.test(target)) {
+      return true;
+    }
+  }
+
+  return false;
+}
 
 export class SecurityEngine {
   /**
@@ -25,6 +76,9 @@ export class SecurityEngine {
    *   retryGuard?: RetryExhaustionGuard,
    *   ledger?: QualityLedger,
    *   auditLogger?: AuditLogger,
+   *   declarativeRules?: DeclarativeRulesEngine,
+   *   counters?: BlockCounters,
+   *   auditFailClosed?: boolean,
    *   inspectConfig?: { toolName?: string, fileWriteTools?: string[], workspaceDir?: string },
    *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
    *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" },
@@ -42,10 +96,20 @@ export class SecurityEngine {
     this.defaultVerdict = options.defaultVerdict || "allow";
 
     this.dryRun = Boolean(options.dryRun || options.shadowMode);
+    this.auditFailClosed = options.auditFailClosed === true;
     this.cache = options.cache !== undefined ? options.cache : new VerdictCache();
     this.retryGuard = options.retryGuard !== undefined ? options.retryGuard : new RetryExhaustionGuard();
     this.ledger = options.ledger !== undefined ? options.ledger : new QualityLedger();
-    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger();
+    this.counters = options.counters || new BlockCounters();
+    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger({
+      failClosed: this.auditFailClosed,
+    });
+    if (this.auditFailClosed && this.auditLogger) {
+      this.auditLogger.failClosed = true;
+    }
+    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({
+      workspaceDir: this.inspectConfig?.workspaceDir,
+    });
   }
 
   /**
@@ -53,7 +117,7 @@ export class SecurityEngine {
    *
    * @param {{ name: string, arguments?: any }} execution - Tool call
    * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context] - Context options
-   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any, dryRun?: boolean, cached?: boolean }}
+   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any, dryRun?: boolean, cached?: boolean, lockedAsk?: boolean, lockedReason?: string, auditFailed?: boolean }}
    */
   decide(execution, context = {}) {
     try {
@@ -71,7 +135,8 @@ export class SecurityEngine {
         };
         const exhDecision = { verdict: "deny", stage: "P0", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
         if (this.ledger) this.ledger.record(sessionId, "exhaustion", { reason: "retry-exhaustion", tool: toolName });
-        if (this.auditLogger) this.auditLogger.log({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
+        if (this.counters) this.counters.record(exhDecision, execution);
+        if (this.auditLogger) this.auditLogger.appendAuditLine({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
 
         if (this.dryRun) {
           return { verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
@@ -96,13 +161,14 @@ export class SecurityEngine {
               cached: true,
             };
           }
+          if (this.counters) this.counters.record(cached, execution);
           return cached;
         }
       }
 
-      const decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+      let decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
 
-      // Post-decision hooks: ledger, retryGuard, cache, audit
+      // Post-decision hooks: ledger, retryGuard, cache
       if (decision.verdict === "deny") {
         if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "deny");
         if (this.ledger) this.ledger.record(sessionId, "deny", { reason: decision.reason, detail: decision.detail, tool: toolName });
@@ -115,8 +181,30 @@ export class SecurityEngine {
         if (this.ledger) this.ledger.record(sessionId, "ask", { reason: decision.reason, detail: decision.detail, tool: toolName });
       }
 
+      // Audit Logger (#56) with fail-closed audit verification (#53)
       if (this.auditLogger) {
-        this.auditLogger.log({ sessionId, execution, decision, dryRun: this.dryRun });
+        const auditOk = this.auditLogger.appendAuditLine({ sessionId, execution, decision, dryRun: this.dryRun });
+        if (!auditOk && this.auditFailClosed && !this.dryRun) {
+          const auditDenyHit = {
+            deny: true,
+            reason: "fail-closed-audit",
+            detail: "Audit log write failed. Execution blocked by fail-closed audit policy (#53).",
+            snippet: command || toolName,
+          };
+          decision = {
+            verdict: "deny",
+            stage: "P0",
+            reason: "fail-closed-audit",
+            detail: auditDenyHit.detail,
+            hit: auditDenyHit,
+            auditFailed: true,
+          };
+        }
+      }
+
+      // Record block counters (#48)
+      if (this.counters) {
+        this.counters.record(decision, execution);
       }
 
       // Shadow Mode (#128)
@@ -129,18 +217,21 @@ export class SecurityEngine {
           reason: decision.reason,
           detail: decision.detail,
           hit: decision.hit,
+          lockedAsk: decision.lockedAsk,
         };
       }
 
       return decision;
     } catch (err) {
-      return {
+      const errDecision = {
         verdict: "ask",
         stage: "P4",
         reason: "inspect-error",
         detail: String(err && err.message || err),
         hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
       };
+      if (this.counters) this.counters.record(errDecision, execution);
+      return errDecision;
     }
   }
 
@@ -157,6 +248,28 @@ export class SecurityEngine {
       return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command, hit };
     }
 
+    // Declarative YAML Rules evaluation (#38, #45, #44)
+    if (this.declarativeRules && command) {
+      const decl = this.declarativeRules.evaluate(toolName, command, context);
+      if (decl.match) {
+        if (decl.verdict === "deny") {
+          this.breaker.countDeny(sessionId);
+          const hit = { deny: true, reason: decl.reason || "declarative-deny", detail: command, snippet: command, ruleId: decl.ruleId };
+          return { verdict: "deny", stage: "P0", reason: decl.reason || "declarative-deny", detail: command, hit };
+        }
+        if (decl.verdict === "allow") {
+          this.breaker.resetConsecutive(sessionId);
+          return { verdict: "allow", stage: "P1", reason: decl.reason || "declarative-allow", hit: null, ruleId: decl.ruleId };
+        }
+        if (decl.verdict === "ask") {
+          const hit = { ask: true, reason: decl.reason || "declarative-ask", detail: command, snippet: command, ruleId: decl.ruleId };
+          const res = { verdict: "ask", stage: "P4", reason: decl.reason || "declarative-ask", detail: command, hit, ruleId: decl.ruleId };
+          this._applyLockedAskIfCritical(res, toolName, command, execution);
+          return res;
+        }
+      }
+    }
+
     // Inspect execution for hard denials and syntax checks
     const hit = inspectExecution(execution, this.inspectConfig);
     if (hit.deny) {
@@ -173,7 +286,7 @@ export class SecurityEngine {
       }
     }
 
-    // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
+    // If Circuit Breaker is tripped, force P4 Human Ask
     if (this.breaker.isTripped(sessionId)) {
       if (this.ledger) this.ledger.record(sessionId, "breaker", { reason: "circuit-breaker-tripped", tool: toolName });
       const breakerHit = {
@@ -182,18 +295,22 @@ export class SecurityEngine {
         detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required.",
         snippet: command || toolName,
       };
-      return {
+      const res = {
         verdict: "ask",
         stage: "P4",
         reason: "circuit-breaker-tripped",
         detail: breakerHit.detail,
         hit: breakerHit,
       };
+      this._applyLockedAskIfCritical(res, toolName, command, execution);
+      return res;
     }
 
     // P4: Human Ask if syntax is unparseable or uncertain
     if (hit.ask) {
-      return { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet, hit };
+      const res = { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet, hit };
+      this._applyLockedAskIfCritical(res, toolName, command, execution);
+      return res;
     }
 
     // P2: Static Rules / Safe Allow
@@ -218,18 +335,36 @@ export class SecurityEngine {
       } catch (err) {
         // Classifier error fails closed to P4 Ask (#111: does not trip breaker)
         if (this.ledger) this.ledger.record(sessionId, "error", { reason: "classifier-error", detail: String(err && err.message || err), tool: toolName });
-        return { verdict: "ask", stage: "P4", reason: "classifier-error", detail: String(err && err.message || err), hit: null };
+        const res = { verdict: "ask", stage: "P4", reason: "classifier-error", detail: String(err && err.message || err), hit: null };
+        this._applyLockedAskIfCritical(res, toolName, command, execution);
+        return res;
       }
     }
 
     // Default verdict for unclassified commands (#163)
     if (this.defaultVerdict === "ask") {
       const askHit = { ask: true, reason: "unmatched-ask", snippet: command || toolName };
-      return { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
+      const res = { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
+      this._applyLockedAskIfCritical(res, toolName, command, execution);
+      return res;
     }
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
   }
 
+  /**
+   * Helper to check and mark lockedAsk for critical operations (#52).
+   * @private
+   */
+  _applyLockedAskIfCritical(decision, toolName, command, execution) {
+    if (decision && decision.verdict === "ask" && isCriticalOperation(toolName, command, execution)) {
+      decision.lockedAsk = true;
+      decision.lockedReason = "critical-operation";
+      if (decision.hit) {
+        decision.hit.lockedAsk = true;
+      }
+    }
+  }
+
   addGrant(options) {
     if (this.grantRegistry && typeof this.grantRegistry.addGrant === "function") {
       return this.grantRegistry.addGrant(options);
@@ -256,6 +391,14 @@ export class SecurityEngine {
     if (this.cache) this.cache.clear();
   }
 
+  getCounters() {
+    return this.counters ? this.counters.getSnapshot() : null;
+  }
+
+  resetCounters() {
+    if (this.counters) this.counters.reset();
+  }
+
   resume(sessionId, reason) {
     if (this.retryGuard) this.retryGuard.reset(sessionId);
     if (this.cache) this.cache.clearSession(sessionId);

package/lib/hotwords.js

@@ -0,0 +1,122 @@
+// lib/hotwords.js
+// High-speed keyword pre-filter (Hotwords / Lexicon Matcher) for dsh-approval-gate (#93).
+// Provides sub-microsecond pre-check to bypass heavy AST/regex parsing for clean commands.
+
+export const DEFAULT_HOTWORDS = Object.freeze([
+  "rm",
+  "mkfs",
+  "fdisk",
+  "parted",
+  "dd",
+  "shadow",
+  "sudoers",
+  "passwd",
+  "kill",
+  "pkill",
+  "killall",
+  "systemctl",
+  "service",
+  "curl",
+  "wget",
+  "bash",
+  "sh",
+  "zsh",
+  "nc",
+  "netcat",
+  "ncat",
+  "socat",
+  "chmod",
+  "chown",
+  "eval",
+  "printenv",
+  "drop",
+  "truncate",
+  "format",
+  "sudo",
+  "su",
+  "ssh",
+]);
+
+/**
+ * Splits text into normalized lowercase word tokens.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function extractWords(text) {
+  if (typeof text !== "string") return [];
+  // Split on whitespace and common shell operators/delimiters
+  const tokens = text.toLowerCase().split(/[^a-z0-9_-]+/);
+  return tokens.filter((t) => t.length > 0);
+}
+
+export class HotwordsMatcher {
+  /**
+   * @param {string[]} [customHotwords]
+   */
+  constructor(customHotwords) {
+    /** @type {Set<string>} */
+    this.lexicon = new Set();
+    const words = Array.isArray(customHotwords) && customHotwords.length > 0
+      ? customHotwords
+      : DEFAULT_HOTWORDS;
+
+    for (const w of words) {
+      if (typeof w === "string" && w.trim()) {
+        this.lexicon.add(w.trim().toLowerCase());
+      }
+    }
+  }
+
+  /**
+   * Add new words to lexicon.
+   * @param {string | string[]} words
+   */
+  add(words) {
+    const list = Array.isArray(words) ? words : [words];
+    for (const w of list) {
+      if (typeof w === "string" && w.trim()) {
+        this.lexicon.add(w.trim().toLowerCase());
+      }
+    }
+  }
+
+  /**
+   * Checks if text contains any word present in the hotwords lexicon.
+   *
+   * @param {string} text
+   * @returns {boolean} True if any high-risk keyword matched
+   */
+  hasMatch(text) {
+    if (!text || typeof text !== "string") return false;
+    const words = extractWords(text);
+    for (let i = 0; i < words.length; i += 1) {
+      if (this.lexicon.has(words[i])) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Returns list of matching hotwords found in text.
+   *
+   * @param {string} text
+   * @returns {string[]}
+   */
+  findMatches(text) {
+    if (!text || typeof text !== "string") return [];
+    const words = extractWords(text);
+    const matches = [];
+    for (let i = 0; i < words.length; i += 1) {
+      if (this.lexicon.has(words[i]) && !matches.includes(words[i])) {
+        matches.push(words[i]);
+      }
+    }
+    return matches;
+  }
+
+  get size() {
+    return this.lexicon.size;
+  }
+}