@goodandready/dsh-approval-gate 0.1.13 → 0.1.15

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;
+  }
+}

package/lib/index.js

@@ -1,5 +1,7 @@
 import { SecurityEngine } from "./engine.js";
 import { BandsEngine } from "./bands.js";
+import { AuditLogger } from "./audit-log.js";
+import { DeclarativeRulesEngine } from "./rules-loader.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -205,6 +207,14 @@ export const Config = Schema.object({
   workspaceDir: Schema.string().default("").volatile(),
   /** Default verdict for unclassified commands: 'allow' (default) or 'ask' (fail-closed) (#163). */
   defaultVerdict: Schema.union(["allow", "ask"]).default("allow").volatile(),
+  /** Dry-run / shadow mode for safe testing of rules on production (#128). */
+  dryRun: Schema.boolean().default(false).volatile(),
+  /** Shadow mode alias for dryRun (#128). */
+  shadowMode: Schema.boolean().default(false).volatile(),
+  /** Path to append-only audit log file (#56). */
+  auditLogPath: Schema.string().default("").volatile(),
+  /** Optional custom declarative rules YAML file path (#38). */
+  rulesFile: Schema.string().default("").volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -248,12 +258,23 @@ export function apply(ctx, config) {
     inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools, workspaceDir: cfg.workspaceDir || "" },
     bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
     defaultVerdict: cfg.defaultVerdict || "allow",
+    dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
+    auditLogger: new AuditLogger({ logPath: cfg.auditLogPath || undefined }),
+    declarativeRules: new DeclarativeRulesEngine({
+      workspaceDir: cfg.workspaceDir || "",
+      builtinCatalogPath: cfg.rulesFile || undefined,
+    }),
   });
 
   const gateService = {
     engine,
     addGrant: (options) => engine.addGrant(options),
     resume: (sessionId, reason) => engine.resume(sessionId, reason),
+    cache: engine.cache,
+    retryGuard: engine.retryGuard,
+    ledger: engine.ledger,
+    declarativeRules: engine.declarativeRules,
+    getLedgerSummary: (sessionId) => engine.getLedgerSummary(sessionId),
   };
   if (ctx && typeof ctx === "object") {
     if (typeof ctx.provide === "function") {
@@ -282,6 +303,13 @@ export function apply(ctx, config) {
         return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
       }
 
+      if (decision.dryRun) {
+        if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
+          ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
+        }
+        return next();
+      }
+
       if (decision.verdict === "ask") {
         if (decision.reason === "circuit-breaker-tripped") {
           const hit = decision.hit || {
@@ -325,6 +353,13 @@ export function apply(ctx, config) {
       return denyMessage(hit, who, translate, ctx && ctx.logger);
     }
 
+    if (decision.dryRun) {
+      if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
+        ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
+      }
+      return undefined;
+    }
+
     if (decision.verdict === "deny" || (decision.verdict === "ask" && !hasPreExecute)) {
       const hit = decision.hit || {
         deny: true,
@@ -400,4 +435,46 @@ export {
   isLoopbackHost,
   isLoopbackUrl,
   isLoopbackCommand,
-} from "./loopback.js";
+} from "./loopback.js";
+export {
+  computeFingerprint,
+  computeFingerprintHash,
+  normalizeCommandString,
+} from "./fingerprint.js";
+export {
+  VerdictCache,
+  DEFAULT_CACHE_MAX_SIZE,
+  DEFAULT_CACHE_TTL_MS,
+} from "./cache.js";
+export {
+  RetryExhaustionGuard,
+  DEFAULT_MAX_RETRY_ATTEMPTS,
+} from "./retry-exhaustion.js";
+export {
+  QualityLedger,
+  MAX_LEDGER_EVENTS_PER_SESSION,
+} from "./ledger.js";
+export {
+  AuditLogger,
+  DEFAULT_AUDIT_LOG_RELATIVE,
+} from "./audit-log.js";
+export {
+  parseYaml,
+  parseScalar,
+  stripComment,
+} from "./yaml-parser.js";
+export {
+  matchConditionValue,
+  evaluateWhen,
+} from "./when-matcher.js";
+export {
+  HotwordsMatcher,
+  DEFAULT_HOTWORDS,
+  extractWords,
+} from "./hotwords.js";
+export {
+  DeclarativeRulesEngine,
+  BUILTIN_RULES_FILE,
+  WORKSPACE_RULES_REL,
+  USER_RULES_REL,
+} from "./rules-loader.js";

package/lib/ledger.js

@@ -0,0 +1,164 @@
+// lib/ledger.js
+// Quality and Anomaly Ledger for dsh-approval-gate (#88).
+// Tracks session health, consecutive denials, and execution anomalies.
+
+export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
+
+/**
+ * @typedef {Object} LedgerEvent
+ * @property {number} timestamp
+ * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+ * @property {string} reason
+ * @property {string} [detail]
+ * @property {string} [tool]
+ */
+
+/**
+ * @typedef {Object} SessionLedger
+ * @property {string} sessionId
+ * @property {number} totalDecisions
+ * @property {number} allowedCount
+ * @property {number} deniedCount
+ * @property {number} askCount
+ * @property {number} anomalyCount
+ * @property {number} consecutiveDenies
+ * @property {boolean} breakerTripped
+ * @property {boolean} retryExhausted
+ * @property {LedgerEvent[]} recentEvents
+ */
+
+export class QualityLedger {
+  constructor() {
+    /** @type {Map<string, SessionLedger>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let ledger = this.sessions.get(key);
+    if (!ledger) {
+      ledger = {
+        sessionId: key,
+        totalDecisions: 0,
+        allowedCount: 0,
+        deniedCount: 0,
+        askCount: 0,
+        anomalyCount: 0,
+        consecutiveDenies: 0,
+        breakerTripped: false,
+        retryExhausted: false,
+        recentEvents: [],
+      };
+      this.sessions.set(key, ledger);
+    }
+    return ledger;
+  }
+
+  /**
+   * Record a decision or system event in the ledger.
+   *
+   * @param {string} sessionId
+   * @param {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+   * @param {{ reason?: string, detail?: string, tool?: string }} [details]
+   */
+  record(sessionId, type, details = {}) {
+    const ledger = this._getOrCreate(sessionId);
+    const now = Date.now();
+
+    const event = {
+      timestamp: now,
+      type,
+      reason: details.reason || "",
+      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
+      tool: details.tool || "",
+    };
+
+    ledger.recentEvents.push(event);
+    if (ledger.recentEvents.length > MAX_LEDGER_EVENTS_PER_SESSION) {
+      ledger.recentEvents.shift();
+    }
+
+    if (type === "allow") {
+      ledger.totalDecisions += 1;
+      ledger.allowedCount += 1;
+      ledger.consecutiveDenies = 0;
+    } else if (type === "deny") {
+      ledger.totalDecisions += 1;
+      ledger.deniedCount += 1;
+      ledger.consecutiveDenies += 1;
+      if (ledger.consecutiveDenies > 1) {
+        ledger.anomalyCount += 1;
+      }
+    } else if (type === "ask") {
+      ledger.totalDecisions += 1;
+      ledger.askCount += 1;
+    } else if (type === "exhaustion") {
+      ledger.retryExhausted = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "breaker") {
+      ledger.breakerTripped = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "error") {
+      ledger.anomalyCount += 1;
+    }
+  }
+
+  /**
+   * Returns a quality summary for the session.
+   *
+   * @param {string} sessionId
+   * @returns {{
+   *   sessionId: string,
+   *   totalDecisions: number,
+   *   allowedCount: number,
+   *   deniedCount: number,
+   *   askCount: number,
+   *   anomalyCount: number,
+   *   consecutiveDenies: number,
+   *   qualityScore: number,
+   *   degradationWarning: boolean,
+   *   recentEvents: LedgerEvent[]
+   * }}
+   */
+  getSummary(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    const total = ledger.totalDecisions;
+
+    // Quality score: 1.0 down towards 0.0 based on denial & anomaly ratio
+    let score = 1.0;
+    if (total > 0) {
+      const penalty = (ledger.deniedCount * 0.2 + ledger.anomalyCount * 0.3) / total;
+      score = Math.max(0, Math.min(1.0, 1.0 - penalty));
+    }
+
+    const degradationWarning = ledger.consecutiveDenies >= 2 ||
+      ledger.retryExhausted ||
+      ledger.breakerTripped ||
+      (total >= 3 && ledger.deniedCount / total >= 0.5);
+
+    return {
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      qualityScore: Number(score.toFixed(2)),
+      degradationWarning,
+      recentEvents: ledger.recentEvents.map((e) => ({ ...e })),
+    };
+  }
+
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}

package/lib/messages.js

@@ -60,6 +60,7 @@ export const MESSAGES = Object.freeze({
     ruleSilentErrorMasked: "Suppression of command failure or error stream",
     ruleChmodChown: "Permission or ownership mutation",
     ruleReviewerReadOnly: "Reviewer agent is strictly isolated in read-only mode",
+    ruleRetryExhaustion: "Exhausted repeated attempts to bypass safety gate",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -72,6 +73,7 @@ export const MESSAGES = Object.freeze({
     hintSilentErrorMasked: "Allow standard error output to be captured and handle non-zero exit codes explicitly",
     hintChmodChown: "Avoid modifying file permissions or system directory ownership directly",
     hintReviewerReadOnly: "Reviewer agents may only read repository files, not run commands or modify files",
+    hintRetryExhaustion: "Repeated denials detected; manual operator intervention required",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -99,7 +101,7 @@ export const MESSAGES = Object.freeze({
     askDynamicCommand: "无法验证展开后的命令名；请在允许前进行审查",
     askDynamicArguments: "敏感命令的展开参数无法验证；请在允许前进行审查",
     askDynamicRedirect: "展开后的重定向目标无法验证；请在允许前进行审查",
-    askScriptFile: "卫兵无法获取脚本文件内容；请在允许前进行审查",
+    askScriptFile: "脚本文件内容不可见；请在允许前进行审查",
     askShellStdin: "卫兵无法完整获取 Shell 输入；请在允许前进行审查",
     askInterpreterPayload: "解释器副作用未完全分析；请在允许前进行审查",
     askCredentialInArgv: "展开后的授权凭据作为进程参数传递；请使用凭据安全的 API 辅助工具，或在允许前进行审查",
@@ -131,6 +133,7 @@ export const MESSAGES = Object.freeze({
     ruleSilentErrorMasked: "屏蔽错误输出或强制忽略退出码",
     ruleChmodChown: "修改权限或所有权",
     ruleReviewerReadOnly: "审查者代理处于只读隔离模式",
+    ruleRetryExhaustion: "多次尝试绕过安全网关已达上限",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -143,6 +146,7 @@ export const MESSAGES = Object.freeze({
     hintSilentErrorMasked: "请保留标准错误输出，并明确处理非零退出码",
     hintChmodChown: "避免直接修改系统目录所有权或文件权限",
     hintReviewerReadOnly: "审查者代理仅可读取项目文件，禁止执行命令或修改文件",
+    hintRetryExhaustion: "检测到重复拒绝；需要操作员手动介入",
   },
 });
 
@@ -202,6 +206,7 @@ const RULE_KEYS = Object.freeze({
   "silent-error-masked": "ruleSilentErrorMasked",
   "chmod-chown": "ruleChmodChown",
   "reviewer-read-only": "ruleReviewerReadOnly",
+  "retry-exhaustion": "ruleRetryExhaustion",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -217,6 +222,7 @@ const HINT_KEYS = Object.freeze({
   "silent-error-masked": "hintSilentErrorMasked",
   "chmod-chown": "hintChmodChown",
   "reviewer-read-only": "hintReviewerReadOnly",
+  "retry-exhaustion": "hintRetryExhaustion",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -273,4 +279,4 @@ export function askMessage(hit, who, translate, logger) {
   if (snippet) parts.push(translated(translate, "commandLabel", logger) + ": " + snippet);
   if (who) parts.push(who.trim());
   return parts.join(" — ") + ".";
-}
+}

package/lib/retry-exhaustion.js

@@ -0,0 +1,171 @@
+// lib/retry-exhaustion.js
+// Anti-replay and Retry Exhaustion guard for dsh-approval-gate (#96).
+// Blocks looping/thrashing agents attempting repeated bypasses after consecutive denials.
+
+export const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+
+/**
+ * Extracts base command root from execution for grouping repeated bypass attempts.
+ *
+ * @param {any} execution
+ * @returns {string}
+ */
+export function extractCommandRoot(execution) {
+  if (!execution) return "";
+  const tool = String(execution.name || execution.tool || "").trim().toLowerCase();
+  const args = execution.arguments || {};
+  if (tool === "bash" || tool === "sh" || tool === "shell") {
+    const cmd = typeof args.command === "string" ? args.command.trim() : "";
+    if (!cmd) return "bash";
+    const parts = cmd.split(/[\s;&|]+/);
+    for (const p of parts) {
+      const clean = p.replace(/^['"]+|['"]+$/g, "").trim();
+      if (!clean) continue;
+      if (clean === "sudo" || clean === "env" || clean === "nohup") continue;
+      return clean;
+    }
+    return "bash";
+  }
+  const path = args.path || args.file || args.target;
+  if (typeof path === "string") return `${tool}:${path}`;
+  return tool;
+}
+
+/**
+ * @typedef {Object} RetrySessionState
+ * @property {string} lastRoot
+ * @property {number} rootRetries
+ * @property {number} totalDenies
+ * @property {boolean} exhausted
+ * @property {number} trippedAt
+ * @property {string[]} recentRoots
+ */
+
+export class RetryExhaustionGuard {
+  /**
+   * @param {{ maxAttempts?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxAttempts = options.maxAttempts || DEFAULT_MAX_RETRY_ATTEMPTS;
+    /** @type {Map<string, RetrySessionState>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let state = this.sessions.get(key);
+    if (!state) {
+      state = {
+        lastRoot: "",
+        rootRetries: 0,
+        totalDenies: 0,
+        exhausted: false,
+        trippedAt: 0,
+        recentRoots: [],
+      };
+      this.sessions.set(key, state);
+    }
+    return state;
+  }
+
+  /**
+   * Check if session has exhausted retries.
+   *
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  isExhausted(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return Boolean(state && state.exhausted);
+  }
+
+  /**
+   * Get consecutive denials count for session.
+   *
+   * @param {string} [sessionId]
+   * @returns {number}
+   */
+  getConsecutiveDenials(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return state ? state.rootRetries : 0;
+  }
+
+  /**
+   * Record a verdict for session and evaluate exhaustion threshold.
+   *
+   * @param {string} sessionId
+   * @param {any} execution
+   * @param {"allow" | "deny" | "ask"} verdict
+   * @returns {boolean} True if this verdict caused exhaustion to trip
+   */
+  recordVerdict(sessionId, execution, verdict) {
+    const state = this._getOrCreate(sessionId);
+    const root = extractCommandRoot(execution);
+
+    if (verdict === "deny") {
+      state.totalDenies += 1;
+      if (state.lastRoot === root) {
+        state.rootRetries += 1;
+      } else {
+        state.lastRoot = root;
+        state.rootRetries = 1;
+      }
+
+      state.recentRoots.push(root);
+      if (state.recentRoots.length > 10) {
+        state.recentRoots.shift();
+      }
+
+      if (state.rootRetries >= this.maxAttempts && !state.exhausted) {
+        state.exhausted = true;
+        state.trippedAt = Date.now();
+        return true;
+      }
+    } else if (verdict === "allow") {
+      state.rootRetries = 0;
+      state.lastRoot = "";
+    }
+
+    return false;
+  }
+
+  /**
+   * Reset consecutive denies without clearing total denies or exhaustion.
+   *
+   * @param {string} [sessionId]
+   */
+  resetConsecutive(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state && state.rootRetries > 0) {
+      state.rootRetries = 0;
+      state.lastRoot = "";
+    }
+  }
+
+  /**
+   * Resume / reset a session to active state.
+   *
+   * @param {string} [sessionId]
+   */
+  reset(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state) {
+      state.lastRoot = "";
+      state.rootRetries = 0;
+      state.exhausted = false;
+      state.trippedAt = 0;
+      state.recentRoots = [];
+    }
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}