@goodandready/dsh-approval-gate 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# 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).
+- Security: inspect `chmod` and `chown` in `inspectArgv`, blocking modifications to protected secret files and recursive changes to root/system paths (Refs: #29).
+- Security: inspect `source` and `.` shell built-in commands as script executions, requiring approval for external script files and process substitutions (Refs: #30).
+- Security: detect destructive SQL (`DROP`, `TRUNCATE`, `ALTER`) delivered via `heredoc` (`<< EOF`) and pipelines to database clients (Refs: #31).
+- Security: block `curl` and `wget` streaming pipelines into interpreter processes like `python`, `node`, `perl`, and `ruby` (Refs: #32).
+- Security: expand `isProtectedPath` to protect `/etc/shadow`, `/etc/sudoers`, `/etc/sudoers.d/`, and SSH `authorized_keys` from writes and redirects (Refs: #33).
+- Bugfix: support GNU sed `--in-place=<suffix>` prefix syntax when checking modifications to protected files (Refs: #34).
+- Refactor: decompose `lib/inspect.js` below the 600-line guideline by extracting bash tokenization into `lib/tokenizer.js` and message formatters into `lib/messages.js` (Refs: #35).
+- Localization: add complete built-in Russian (`ru`) dictionary covering all rules, syntax reasons, and approval prompts in `lib/messages.js` (Refs: #36).
+
 ## 0.1.4
 
 - The gate no longer raises an ask it knows cannot be answered. It reads the effective
@@ -12,7 +34,6 @@
   the policy is not visible. An unknown policy keeps the safe direction and still asks.
 - 8 tests for the new behaviour (23 in total).
 
-# Changelog
 
 ## 0.1.3
 

package/README.md

@@ -58,8 +58,9 @@ graph LR
 | Module | Responsibility |
 |---|---|
 | lib/index.js | Registers the monotonic tools.guard and pre-execution approval hook; wires the shell and file-write inspectors into DSH. |
-| lib/inspect.js | Tokenizes bounded Bash syntax, inspects command argv and expansions, applies destructive-command and protected-write rules, and returns pass, deny, or ask decisions. |
-| lib/messages.js | Provides English and Simplified Chinese rule names, explanations, and redacted-result labels. |
+| lib/tokenizer.js | Tokenizes bounded Bash syntax, tracks operators/heredocs, and extracts parameter/command substitutions. |
+| lib/inspect.js | Evaluates safety rules, inspects command argv and expansions, and returns pass, deny, or ask decisions. |
+| lib/messages.js | Provides English, Simplified Chinese, and Russian rule names, explanations, and formatted messages. |
 | cordis.patch.yml | Declares the host-side plugin bundle and optional tool configuration. |
 
 The guard runs before the tool body. A recognized dangerous action is denied even if a prompt could otherwise be shown. Uncertain syntax or targets are sent to DSH approval; DSH policy still decides whether a prompt is available.
@@ -68,7 +69,12 @@ The guard runs before the tool body. A recognized dangerous action is denied eve
 
 | Call | Result |
 |---|---|
-| `rm -rf /tmp/x`, `sudo rm -r ...` | block |
+| `rm -rf /tmp/x`, `rm -Rf /tmp/x`, `sudo rm -r ...` | block |
+| `chmod`/`chown` on `.env` / `id_rsa`, `chmod -R 777 /` | block |
+| `source script.sh`, `. script.sh`, `source <(...)` | request DSH approval |
+| `mysql << EOF DROP TABLE...`, `echo DROP \| mysql` | block |
+| `curl ... \| python3`, `wget ... \| node` | block |
+| writing to `/etc/shadow`, `/etc/sudoers`, `authorized_keys` | block |
 | `kill` / `pkill` / `killall` as the command | block |
 | `k''ill -9 1` (quoted fragments) | block |
 | `systemctl restart\|stop\|disable ...` | block |

package/README.ru.md

@@ -38,7 +38,7 @@
 Установка (публичный пакет npm):
 
 ```sh
-dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.3
+dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.5
 ```
 
 ## Изменения в v0.1.3
@@ -62,8 +62,9 @@ dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.3
 | Модуль | Назначение |
 |---|---|
 | lib/index.js | Регистрирует монотонный tools.guard и штатный pre-execution approval hook DSH, подключает проверки shell и файловых записей. |
-| lib/inspect.js | Разбирает ограниченный shell-синтаксис, проверяет argv и подстановки, применяет правила опасных команд и защищённых записей, возвращает pass, deny или ask. |
-| lib/messages.js | Содержит английские и китайские названия правил, пояснения и подписи для обезличенного фрагмента. |
+| lib/tokenizer.js | Разбирает ограниченный shell-синтаксис, выделяет операторы, heredoc и подстановки команд/параметров. |
+| lib/inspect.js | Применяет правила опасных команд и защищённых записей, проверяет argv и подстановки, возвращает pass, deny или ask. |
+| lib/messages.js | Содержит английские, китайские и русские словари правил, пояснений и форматирования сообщений. |
 | cordis.patch.yml | Объявляет host-пакет плагина и необязательную конфигурацию инструментов. |
 
 ```mermaid
@@ -80,7 +81,12 @@ graph LR
 
 | Пример вызова | Результат |
 |---|---|
-| rm -rf /tmp/x, sudo rm -r ... | Запрет |
+| rm -rf /tmp/x, rm -Rf /tmp/x, sudo rm -r ... | Запрет |
+| chmod/chown на секретах (.env, id_rsa) или chmod -R на корне | Запрет |
+| source script.sh, . script.sh, source <(...) | Запрос подтверждения DSH |
+| mysql << EOF DROP TABLE..., echo DROP \| mysql | Запрет |
+| curl ... \| python3, wget ... \| node | Запрет |
+| Запись в /etc/shadow, /etc/sudoers, authorized_keys | Запрет |
 | kill, pkill, killall | Запрет |
 | systemctl stop/restart/disable | Запрет; systemctl is-active проходит |
 | service name stop/restart | Запрет |
@@ -116,7 +122,7 @@ graph LR
 
 ### Установка и ограничения
 
-<pre><code>dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.3</code></pre>
+<pre><code>dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.5</code></pre>
 
 Плагин не добавляет HTTP-маршруты или отдельную CLI-команду и не читает содержимое файлов скриптов. Это не системная песочница: команды cron и systemd, запущенные отдельно от инструментов DSH, он не перехватывает.
 

package/README.zh.md

@@ -38,7 +38,7 @@
 从公开 npm registry 安装：
 
 ```sh
-dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.3
+dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.5
 ```
 
 ## v0.1.3 变更
@@ -62,8 +62,9 @@ shell 分析器现在支持命令替换、反引号、进程替换、常见重
 | 模块 | 职责 |
 |---|---|
 | lib/index.js | 注册单调的 tools.guard 和 DSH 原生预执行审批钩子，并连接 shell 与文件写入检查器。 |
-| lib/inspect.js | 对有界 shell 语法进行分词，检查 argv 和展开内容，应用危险命令与受保护写入规则，并返回通过、拒绝或请求审批的结果。 |
-| lib/messages.js | 提供英文和简体中文规则名称、说明及脱敏提示。 |
+| lib/tokenizer.js | 对有界 shell 语法进行分词，提取操作符、here-document 和命令/参数替换。 |
+| lib/inspect.js | 检查 argv 和展开内容，应用危险命令与受保护写入规则，并返回通过、拒绝或请求审批的结果。 |
+| lib/messages.js | 提供英文、简体中文及俄文规则名称、说明及格式化提示。 |
 | cordis.patch.yml | 声明 host 端插件包和可选工具配置。 |
 
 ```mermaid
@@ -116,7 +117,7 @@ graph LR
 
 ### 安装与限制
 
-<pre><code>dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.3</code></pre>
+<pre><code>dsh plugin --profile web add @goodandready/dsh-approval-gate@0.1.5</code></pre>
 
 本插件不添加 HTTP 路由或独立 CLI，也不读取脚本文件内容。它不是操作系统沙箱，不会检查 cron 或 systemd 自行执行的命令。
 

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";