@goodandready/dsh-approval-gate 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.14
+
+- Feature: Режим теневого аудита (`dryRun: true` / `shadowMode: true`) в `Config` и `SecurityEngine` для безопасного тестирования правил на проде без блокировки выполнения процессов агента (Refs: #128).
+- Security: Генерация канонического отпечатка операции (`lib/fingerprint.js`) в формате `tool:normalize(cmd):target_path` со строгой дифференциацией флагов, аргументов и путей (Refs: #80).
+- Performance: Семантический LRU/TTL кэш вердиктов безопасности (`lib/cache.js`) по хэшу нормализованных аргументов и сессионный кэш с детерминированным O(1) временем ответа (Refs: #63, #119).
+- Security: Предохранитель повторных попыток обхода (`lib/retry-exhaustion.js` `RetryExhaustionGuard`) с блокировкой и требованием вмешательства человека при 3 последовательных попытках вызова запрещенных команд (Refs: #96).
+- Resilience: Исключение сетевых сбоев, таймаутов LLM и ошибок парсинга классификатора из срабатывания предохранителя `CircuitBreaker` (`countDeny` с опцией исключения сбоев) (Refs: #111).
+- Quality: Журнал аномалий и качества сессии (`lib/ledger.js` `QualityLedger`) с фиксацией повторных отказов, расчетом qualityScore и предупреждениями о деградации (Refs: #88).
+- Security: Изоляция журнала аудита от контекста сессии (`lib/audit-log.js` `AuditLogger`) с записью в append-only файл `~/.dsh/approval-gate-audit.jsonl` для предотвращения indirect prompt injection (Refs: #56).
+
+## 0.1.13
+
+- Architecture: выделение `CommandDispatcher` (`lib/dispatcher.js`) для полной изоляции синтаксического разбора аргументов и классификации типов инструментов от движка принятия решений `SecurityEngine` (Refs: #133).
+- Git: специализированный парсер семантики команд Git (`lib/parsers/git.js`) с разграничением безопасных операций чтения (`status`, `log`, `diff`, `rev-parse`), локальных мутаций (`commit`, `checkout -b`, `add`, `branch`) и деструктивных действий (`reset --hard`, `clean -f`, `branch -D`) (Refs: #125).
+- Git: разделение локальных операций и сетевой публикации — автоматическое разрешение локальных коммитов и веток при обязательном запросе подтверждения (`git-remote-push`) для `git push` в удаленный репозиторий (Refs: #103).
+- Shell: специализированный парсер конструкций оболочки (`lib/parsers/shell-cmds.js`) для детекции опасных перенаправлений в системные блочные устройства (`/dev/sd*`), защищенные файлы секретов и предотвращения обхода через traversal (Refs: #126).
+- Security: `SilentErrorGuard` — детекция маскировки критических ошибок компиляции и сбоев команд через подавление потока stderr (`2>/dev/null`, `&>/dev/null`), принудительный нулевой код возврата (`|| true`, `|| :`, `|| exit 0`) и отключение проверки ошибок (`set +e`) (Refs: #90).
+- Security: строгая изоляция агента-ревьюера (`Reviewer`) в режиме read-only без возможности запуска shell-процессов или записи/модификации файлов (Refs: #65).
+- Security: предотвращение рекурсивной или системной модификации прав и владельцев (`chmod -R`, `chown -R`, манипуляции над `/`, `/etc`, `/var`, `/usr`, `/root`) (Refs: #65).
+- Network: безопасный loopback bypass (`lib/loopback.js`) с нулевой задержкой и автоматическим разрешением запросов к `localhost`, `127.0.0.1`, `::1`, `0.0.0.0` для локальных dev-серверов и тестов (Refs: #40).
+
 ## 0.1.12
 
 - Fix: корректная регистрация сервиса `approvalGate` в Cordis через `ctx.provide('approvalGate', ...)` и экспорт `export const provide = ['approvalGate']`, устраняющая ошибку `cannot set property "approvalGate" without provide` при старте хоста DSH.
@@ -22,19 +43,14 @@
 - Policy: оптимизация сканирования истории событий сессии в `readKnobs` — однопроходный поиск, ограничение глубины до 100 событий и кэширование политики сессии на `_gateCachedPolicy` (Refs: #148).
 - Schema: поддержка `.volatile()` на полях конфигурации, явные поля `workspaceDir` и `engine`, полифилл для DSH UI формы настроек и функция разворачивания реактивных боксов `plainConfig` (Refs: #142, #150, #151).
 - Engine: методы `addGrant`, `getGrants` и `resume` на `SecurityEngine` и экспорт `ctx.approvalGate` для управления грантами и сбросом предохранителя (Refs: #152).
-- Tokenizer: исправление передачи маркера heredoc (`marker: heredoc.delimiter`) в токенизаторе и корректная реконструкция в `splitSubcommands` (Refs: #146).
-- Tests: матрица проверок на обходные векторы через операторы конвейеров и allow-префиксы (Refs: #164).
 
 ## 0.1.10
 
-- Policy: точное определение сессионной политики апрува в `readKnobs` через `approval.effectivePolicy(session)`, историю событий `session.eventAt` и пресет `danger-full-access` (Refs: #140).
-- Execution: корректный пропуск некритичных команд в режиме «Полный доступ» (`never`) без ложного поднятия `ask` и автоматического отказа DSH `Error: the user rejected tool` (Refs: #140).
-- Observability: форматирование `sessionTag` с получением строкового идентификатора сессии `session.id` / `session.name` вместо `[object Object]` (Refs: #140).
+- Performance: lazy compilation of regular expressions in `inspectArgv` (Refs: #140).
+- Test: fix path traversal tests on Windows by dynamically reading root drive (Refs: #141).
 
 ## 0.1.9
 
-- Inspect: декомпозиция `lib/inspect.js` с выносом `checkEnvExfiltration` в `lib/inspect-env.js`, строгое соблюдение порога 600 строк (Refs: #35).
-- Security: автоматическое маскирование и redaction чувствительных данных, токенов и паролей в сетевых URL и аудиторских логах `redactUrl` и `redactCredentials` (Refs: #42).
 - Paths: интеграция `resolveSafePath` как основного примитива безопасности файловых путей и защита от symlink и path traversal обходов (Refs: #94, #137).
 - Engine: интеграция 5-уровневого каскада принятия решений `SecurityEngine` (P0 Hard-Deny -> P1 Grants -> P2 Static -> P3 LLM -> P4 Ask) в хук `tools/pre-execute` и рантайм-гард `tools.guard` (Refs: #122).
 - Messages: расширенная мультиязычная локализация причин блокировки (ru, en, zh) с контекстными подсказками безопасных альтернатив `hintPrefix` и `ruleHints` (Refs: #131).

package/lib/audit-log.js

@@ -0,0 +1,76 @@
+// lib/audit-log.js
+// Isolated append-only audit logger for dsh-approval-gate (#56).
+// Logs gate decisions to ~/.dsh/approval-gate-audit.jsonl out-of-band to prevent prompt injection.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { computeFingerprint } from "./fingerprint.js";
+import { redactCredentials } from "./redact.js";
+
+export const DEFAULT_AUDIT_LOG_RELATIVE = path.join(".dsh", "approval-gate-audit.jsonl");
+
+export class AuditLogger {
+  /**
+   * @param {{ logPath?: string, disabled?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.disabled = options.disabled === true;
+    if (options.logPath) {
+      this.logPath = options.logPath;
+    } else {
+      const home = os.homedir ? os.homedir() : (process.env.HOME || process.env.USERPROFILE || "");
+      this.logPath = home ? path.join(home, DEFAULT_AUDIT_LOG_RELATIVE) : "";
+    }
+  }
+
+  /**
+   * Write an audit record to the isolated log file.
+   *
+   * @param {{
+   *   sessionId?: string,
+   *   execution?: any,
+   *   decision: { verdict: string, stage?: string, reason?: string, detail?: string, dryRun?: boolean },
+   *   dryRun?: boolean
+   * }} record
+   */
+  log(record) {
+    if (this.disabled || !this.logPath) return;
+
+    try {
+      const now = Date.now();
+      const execution = record.execution || {};
+      const decision = record.decision || {};
+      const tool = String(execution.name || execution.tool || "").trim();
+      const rawCmd = execution.arguments && typeof execution.arguments.command === "string"
+        ? execution.arguments.command
+        : "";
+      const redactedCmd = rawCmd ? redactCredentials(rawCmd) : undefined;
+      const fp = computeFingerprint(execution);
+
+      const entry = {
+        timestamp: now,
+        iso: new Date(now).toISOString(),
+        sessionId: record.sessionId || "default",
+        tool,
+        command: redactedCmd,
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        fingerprint: fp,
+        dryRun: Boolean(record.dryRun || decision.dryRun),
+      };
+
+      const line = JSON.stringify(entry) + "\n";
+      const dir = path.dirname(this.logPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.appendFileSync(this.logPath, line, "utf8");
+    } catch {
+      // Security audit failures fail open to prevent DoS,
+      // but never leak errors into agent prompt.
+    }
+  }
+}

package/lib/breaker.js

@@ -166,10 +166,16 @@ export class CircuitBreaker {
 
   /**
    * Record a security denial. Returns true if this call tripped the breaker.
+   * Excludes network faults and classifier errors from tripping the breaker (#111).
+   *
    * @param {string} [sessionId]
+   * @param {{ isNetworkFault?: boolean, isClassifierError?: boolean }} [options]
    * @returns {boolean}
    */
-  countDeny(sessionId) {
+  countDeny(sessionId, options = {}) {
+    if (options && (options.isNetworkFault || options.isClassifierError)) {
+      return false;
+    }
     const key = sessionId || "default";
     const state = this._getOrCreate(key);
     state.consecutive += 1;
@@ -191,6 +197,25 @@ export class CircuitBreaker {
     return false;
   }
 
+  /**
+   * Identifies whether an error represents a network fault or classifier timeout (#111).
+   * @param {any} err
+   * @returns {boolean}
+   */
+  static isFaultOrTimeout(err) {
+    if (!err) return false;
+    const msg = String(err.message || err).toLowerCase();
+    return (
+      msg.includes("timeout") ||
+      msg.includes("econnrefused") ||
+      msg.includes("enotfound") ||
+      msg.includes("etimedout") ||
+      msg.includes("network") ||
+      msg.includes("fetch failed") ||
+      msg.includes("socket hang up")
+    );
+  }
+
   /**
    * Reset the consecutive counter on an allowed operation.
    * @param {string} [sessionId]
@@ -231,4 +256,3 @@ export class CircuitBreaker {
     this.sessions.clear();
   }
 }
-

package/lib/cache.js

@@ -0,0 +1,146 @@
+// lib/cache.js
+// Semantic LRU/TTL verdict cache for dsh-approval-gate (#63, #119).
+// Caches deterministic security decisions by canonical operation fingerprint.
+
+import { computeFingerprintHash } from "./fingerprint.js";
+
+export const DEFAULT_CACHE_MAX_SIZE = 1000;
+export const DEFAULT_CACHE_TTL_MS = 300_000; // 5 minutes
+
+export class VerdictCache {
+  /**
+   * @param {{ maxSize?: number, defaultTtlMs?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || DEFAULT_CACHE_MAX_SIZE;
+    this.defaultTtlMs = options.defaultTtlMs !== undefined ? options.defaultTtlMs : DEFAULT_CACHE_TTL_MS;
+    /** @type {Map<string, { decision: any, expiresAt: number, sessionId?: string, timestamp: number }>} */
+    this.entries = new Map();
+  }
+
+  /**
+   * Generates a stable cache key for execution in a session context.
+   *
+   * @param {any} execution
+   * @param {{ sessionId?: string, cwd?: string, sessionScoped?: boolean }} [context]
+   * @returns {string}
+   */
+  makeKey(execution, context = {}) {
+    const hash = computeFingerprintHash(execution, { cwd: context.cwd });
+    if (context.sessionScoped && context.sessionId) {
+      return `${context.sessionId}:${hash}`;
+    }
+    return hash;
+  }
+
+  /**
+   * Retrieves a cached verdict if present and not expired.
+   * Promotes the entry to most recently used.
+   *
+   * @param {string} key
+   * @returns {any | undefined} Cached decision object or undefined
+   */
+  get(key) {
+    if (!this.entries.has(key)) return undefined;
+    const entry = this.entries.get(key);
+    const now = Date.now();
+
+    if (entry.expiresAt > 0 && now > entry.expiresAt) {
+      this.entries.delete(key);
+      return undefined;
+    }
+
+    // Refresh LRU order: delete and re-insert
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+
+    return { ...entry.decision, cached: true, cacheHitAt: now };
+  }
+
+  /**
+   * Stores a decision in the cache.
+   * Only caches deterministic verdicts ("allow" or "deny").
+   *
+   * @param {string} key
+   * @param {any} decision
+   * @param {{ ttlMs?: number, sessionId?: string }} [options]
+   */
+  set(key, decision, options = {}) {
+    if (!key || !decision) return;
+    // Do not cache transient or uncertain verdicts unless explicit
+    if (decision.verdict !== "allow" && decision.verdict !== "deny") {
+      return;
+    }
+
+    const ttl = options.ttlMs !== undefined ? options.ttlMs : this.defaultTtlMs;
+    const now = Date.now();
+    const expiresAt = ttl > 0 ? now + ttl : 0;
+
+    // If key already exists, delete it first to ensure correct insertion order
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.maxSize) {
+      // Evict oldest (first key in iteration)
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.entries.delete(oldestKey);
+      }
+    }
+
+    this.entries.set(key, {
+      decision: {
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        hit: decision.hit,
+      },
+      expiresAt,
+      sessionId: options.sessionId,
+      timestamp: now,
+    });
+  }
+
+  has(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+      this.entries.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  delete(key) {
+    return this.entries.delete(key);
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+
+  clearSession(sessionId) {
+    if (!sessionId) return;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.sessionId === sessionId || key.startsWith(`${sessionId}:`)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+
+  prune() {
+    const now = Date.now();
+    let count = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.expiresAt > 0 && now > entry.expiresAt) {
+        this.entries.delete(key);
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}

package/lib/dispatcher.js

@@ -0,0 +1,208 @@
+// lib/dispatcher.js
+// Command Dispatcher: architectural isolation of command parsing and syntactic dispatch
+// from the safety evaluation engine.
+// Resolves: #133, #65
+
+import { tokenize, splitSubcommands } from "./tokenizer.js";
+import { parseGitArgv, classifyGitOperation } from "./parsers/git.js";
+import { extractRedirects, inspectRedirectSecurity, inspectSilentErrors, inspectPipelines } from "./parsers/shell-cmds.js";
+import { isLoopbackCommand, isLoopbackUrl } from "./loopback.js";
+import { resolveSafePath, isPathTraversal, isProtectedConfigPath } from "./paths.js";
+
+export const TOOL_KIND_SHELL = "shell";
+export const TOOL_KIND_FILE_WRITE = "file_write";
+export const TOOL_KIND_FILE_READ = "file_read";
+export const TOOL_KIND_NETWORK = "network";
+export const TOOL_KIND_GENERIC = "generic";
+
+export const DEFAULT_BASH_TOOL = "bash";
+export const DEFAULT_FILE_WRITE_TOOLS = Object.freeze([
+  "write",
+  "edit",
+  "Write",
+  "Edit",
+  "str_replace_editor",
+  "str_replace",
+  "apply_patch",
+]);
+
+export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
+  "read_file",
+  "view_file",
+  "read_url_content",
+  "search_web",
+  "list_dir",
+  "glob",
+  "grep",
+]);
+
+export const DEFAULT_NETWORK_TOOLS = Object.freeze([
+  "fetch",
+  "web_fetch",
+  "http_request",
+  "read_url_content",
+]);
+
+/**
+ * Extracts target file path from various tool argument schemas.
+ *
+ * @param {any} args
+ * @returns {string | null}
+ */
+export function extractFilePath(args) {
+  if (typeof args === "string") return args;
+  if (!args || typeof args !== "object") return null;
+  const keys = [
+    "path",
+    "file_path",
+    "filePath",
+    "file",
+    "filename",
+    "target",
+    "to",
+    "TargetFile",
+    "AbsolutePath",
+  ];
+  for (const k of keys) {
+    if (typeof args[k] === "string" && args[k].trim()) {
+      return args[k].trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Checks whether an execution originates from a designated read-only reviewer agent.
+ * Resolves: #65 (strict read-only reviewer subagent isolation).
+ *
+ * @param {any} execution
+ * @param {any} [options]
+ * @returns {boolean}
+ */
+export function isReviewerAgent(execution, options = {}) {
+  if (options && options.reviewerMode === true) return true;
+  const agent = execution && execution.agent;
+  if (!agent) return false;
+
+  const role = typeof agent.role === "string" ? agent.role.toLowerCase() : "";
+  const name = typeof agent.name === "string" ? agent.name.toLowerCase() : "";
+  const type = typeof agent.type === "string" ? agent.type.toLowerCase() : "";
+
+  return role.includes("review") || name.includes("review") || type.includes("review");
+}
+
+export class CommandDispatcher {
+  /**
+   * @param {{
+   *   toolName?: string,
+   *   fileWriteTools?: string[] | Set<string>,
+   *   readOnlyTools?: string[] | Set<string>,
+   *   networkTools?: string[] | Set<string>,
+   *   workspaceDir?: string
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.toolName = options.toolName || DEFAULT_BASH_TOOL;
+    this.fileWriteTools = new Set(options.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS);
+    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+    this.networkTools = new Set(options.networkTools || DEFAULT_NETWORK_TOOLS);
+    this.workspaceDir = options.workspaceDir || process.cwd();
+  }
+
+  /**
+   * Categorizes the tool name into functional kind.
+   *
+   * @param {string} name
+   * @returns {"shell" | "file_write" | "file_read" | "network" | "generic"}
+   */
+  classifyTool(name) {
+    if (!name) return TOOL_KIND_GENERIC;
+    if (name === this.toolName) return TOOL_KIND_SHELL;
+    if (this.fileWriteTools.has(name)) return TOOL_KIND_FILE_WRITE;
+    if (this.readOnlyTools.has(name)) return TOOL_KIND_FILE_READ;
+    if (this.networkTools.has(name)) return TOOL_KIND_NETWORK;
+    return TOOL_KIND_GENERIC;
+  }
+
+  /**
+   * Dispatches and normalizes a tool execution request into a structured descriptor.
+   *
+   * @param {any} execution - The tool execution event carrying name, arguments, agent, session
+   * @param {any} [options] - Dynamic context overrides
+   * @returns {{
+   *   tool: string,
+   *   kind: "shell" | "file_write" | "file_read" | "network" | "generic",
+   *   isMutating: boolean,
+   *   reviewerViolation: boolean,
+   *   command?: string,
+   *   tokens?: any[],
+   *   subcommands?: string[],
+   *   git?: any,
+   *   silentError?: any,
+   *   loopback?: any,
+   *   filePath?: string,
+   *   pathSafety?: any
+   * }}
+   */
+  dispatch(execution, options = {}) {
+    const name = execution && execution.name ? String(execution.name).trim() : "";
+    const args = execution ? execution.arguments : undefined;
+    const kind = this.classifyTool(name);
+    const isReviewer = isReviewerAgent(execution, options);
+
+    const isMutating = kind === TOOL_KIND_SHELL || kind === TOOL_KIND_FILE_WRITE;
+    const reviewerViolation = isReviewer && isMutating;
+
+    const descriptor = {
+      tool: name,
+      kind,
+      isMutating,
+      reviewerViolation,
+    };
+
+    if (kind === TOOL_KIND_SHELL) {
+      const rawCommand = args && typeof args === "object" ? args.command : (typeof args === "string" ? args : "");
+      descriptor.command = typeof rawCommand === "string" ? rawCommand : "";
+
+      if (descriptor.command) {
+        const tokenized = tokenize(descriptor.command);
+        descriptor.tokens = tokenized.tokens || [];
+        descriptor.tokenizerOk = tokenized.ok;
+        descriptor.tokenizerReason = tokenized.reason;
+
+        // Subcommands breakdown
+        descriptor.subcommands = splitSubcommands(descriptor.command);
+
+        // Silent errors inspection (#90)
+        descriptor.silentError = inspectSilentErrors(descriptor.command);
+
+        // Git inspection (#125, #103)
+        if (/\bgit\b/.test(descriptor.command)) {
+          const firstWords = descriptor.command.trim().split(/\s+/);
+          descriptor.git = parseGitArgv(firstWords);
+          descriptor.gitClassification = classifyGitOperation(descriptor.git.verb, descriptor.git.args);
+        }
+
+        // Loopback detection (#40)
+        descriptor.loopback = isLoopbackCommand(descriptor.command.trim().split(/\s+/));
+      }
+    } else if (kind === TOOL_KIND_FILE_WRITE) {
+      const filePath = extractFilePath(args);
+      descriptor.filePath = filePath;
+      if (filePath) {
+        const ws = options.workspaceDir || this.workspaceDir;
+        descriptor.pathSafety = resolveSafePath(filePath, ws);
+        descriptor.isProtected = isProtectedConfigPath(descriptor.pathSafety.canonical || filePath);
+        descriptor.isTraversal = !descriptor.pathSafety.safe;
+      }
+    } else if (kind === TOOL_KIND_NETWORK) {
+      const url = args && typeof args === "object" ? (args.url || args.Url || args.uri || args.Uri) : "";
+      descriptor.url = typeof url === "string" ? url : "";
+      if (descriptor.url) {
+        descriptor.isLoopback = isLoopbackUrl(descriptor.url);
+      }
+    }
+
+    return descriptor;
+  }
+}