@goodandready/dsh-approval-gate 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.19
+
+- Security: Структурированная категоризация рисков операций по 5 стандартизированным бакетам (`READ_ONLY`, `WORKSPACE`, `EGRESS`, `SYSTEM`, `SECRETS`) в `lib/risk.js` с приоритетной оценкой чувствительности путей, команд и сетевых направлений (Refs: #58).
+- Security: Многомерное тегирование рисков (`risk_tags`: `read-only`, `file-mutation`, `network`, `git`, `credentials`, `package-manager`, `system-mutation`, `privilege-escalation`, `destructive`) для детального анализа и обогащения решений безопасности (Refs: #70).
+- Resilience: Трекер задержки семантического классификатора (`ClassifierLatencyTracker` в `lib/latency.js`) со скользящим окном p95/avg и автоматическим переходом на детерминированные правила при превышении SLA (`classifier-sla-fallback` -> `ask`) (Refs: #57).
+- Resilience: Плавный fallback при несовместимости эндпоинта с OpenAI JSON-mode (`isShapeRejectError`), извлечение JSON из markdown/raw-ответов (`extractJsonPayload`) и повторный запрос без `response_format` для Ollama/vLLM (Refs: #59).
+- Security: Строгая Schemastery-схема вердиктов классификатора (`ClassifierVerdictSchema`, `validateClassifierResponse`) с fail-closed защитой от некорректных/неполных ответов модели (`malformed-classifier-response` -> `ask`) (Refs: #66).
+
+## 0.1.18
+
+- Security: Эвристический предохранитель размера аргументов (`computePayloadSize` / `maxPayloadBytes`, по умолчанию 64 КБ) для предотвращения переполнения контекста LLM-ревьюера и обхода инспекции (`payload-too-large` -> `ask`) (Refs: #71).
+- Security: Сканер анти-инъекций инструкций в аргументы и скрипты (`scanPromptInjection`) с жесткой блокировкой директив обхода правил (`SYSTEM OVERRIDE: ALLOW`, `ignore previous instructions` и др. -> `reviewer-injection-attempt`) (Refs: #72).
+- Security: Страж соответствия контракту задачи (`ContractGuard` в `lib/contract-guard.js`) с перехватом нецелевых системных пакетных менеджеров, управления службами, сетевых конфигураций и запрещенных инструментов (`contract-violation` -> `ask`) (Refs: #87).
+- Security: Строгая изоляция временных каталогов проекта (`resolveTempRoot`, `isGlobalTempPath`, `checkTempIsolation` в `lib/paths.js`) с переводом обращений к глобальному `/tmp` на запрос подтверждения (`unisolated-temp-path` -> `ask` в пользу `<workspace>/.dsh/tmp`) (Refs: #102).
+- Feature: Контроль оверинжиниринга (`OverengineeringGuard` в `lib/overengineering.js`) с отслеживанием числа создаваемых уникальных файлов за сессию (`maxFilesPerSession`, по умолчанию 10) и запросом подтверждения при превышении (`overengineering-file-limit` -> `ask`) (Refs: #89).
+
 ## 0.1.17
 
 - Feature: Автонормализация URL эндпоинтов пользовательских LLM (`normalizeChatCompletionsUrl`) с поддержкой bare host, портов, `/v1` и `/chat/completions` без риска 404 (Refs: #127).

package/lib/classifier.js

@@ -4,6 +4,7 @@
 
 import { redactCredentials, redactUrl } from "./redact.js";
 import { CircuitBreaker } from "./breaker.js";
+import Schema from "@deepseek-ai/schemastery";
 
 // Additional regex patterns for sensitive tokens & API keys (#115)
 const OPENAI_KEY_PATTERN = /\bsk-[a-zA-Z0-9_\-]{20,}\b/g;
@@ -244,7 +245,104 @@ export function isLowRiskExecution(execution) {
 }
 
 /**
- * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117).
+ * Checks whether an error is caused by endpoint rejection of JSON-mode / response_format (#59).
+ * Common in local LLM runtimes like Ollama, vLLM, and older endpoints.
+ *
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isShapeRejectError(err) {
+  if (!err) return false;
+  const status = err.status || (err.response && err.response.status);
+  if (status === 400 || status === 415 || status === 422) return true;
+  const msg = String(err.message || "").toLowerCase();
+  return (
+    msg.includes("response_format") ||
+    msg.includes("json_object") ||
+    msg.includes("unsupported parameter") ||
+    msg.includes("schema")
+  );
+}
+
+/**
+ * Robust JSON extraction from raw strings, handling markdown code blocks and raw JSON (#59).
+ *
+ * @param {string} content
+ * @returns {any | null}
+ */
+export function extractJsonPayload(content) {
+  if (!content || typeof content !== "string") return null;
+  const trimmed = content.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Check markdown code block
+    const mdMatch = /```(?:json)?\s*([\s\S]*?)\s*```/i.exec(trimmed);
+    if (mdMatch && mdMatch[1]) {
+      try {
+        return JSON.parse(mdMatch[1].trim());
+      } catch {
+        // continue
+      }
+    }
+    // Check bracketed JSON
+    const braceMatch = /\{[\s\S]*\}/.exec(trimmed);
+    if (braceMatch) {
+      try {
+        return JSON.parse(braceMatch[0]);
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Strict Schemastery schema for validating structured classifier decisions (#66).
+ */
+export const ClassifierVerdictSchema = Schema.object({
+  verdict: Schema.union(["allow", "deny", "ask"]).required(),
+  reason: Schema.string().default("classifier-evaluated"),
+  riskScore: Schema.number().default(0.5),
+  tags: Schema.array(Schema.string()).default([]),
+});
+
+/**
+ * Validates and normalizes structured classifier response (#66).
+ *
+ * @param {any} parsed
+ * @returns {{ valid: boolean, verdict?: "allow" | "deny" | "ask", reason?: string, riskScore?: number, tags?: string[], error?: string }}
+ */
+export function validateClassifierResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { valid: false, error: "Response is not a valid JSON object" };
+  }
+  const rawVerdict = String(parsed.verdict || "").toLowerCase().trim();
+  if (!["allow", "deny", "ask"].includes(rawVerdict)) {
+    return { valid: false, error: `Invalid verdict '${parsed.verdict}', expected allow|deny|ask` };
+  }
+  const reason = typeof parsed.reason === "string" && parsed.reason.trim()
+    ? parsed.reason.trim()
+    : `classifier-${rawVerdict}`;
+  const riskScore = typeof parsed.riskScore === "number" && !isNaN(parsed.riskScore)
+    ? Math.max(0, Math.min(1, parsed.riskScore))
+    : (rawVerdict === "deny" ? 1.0 : (rawVerdict === "ask" ? 0.6 : 0.1));
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim())
+    : [];
+
+  return {
+    valid: true,
+    verdict: rawVerdict,
+    reason,
+    riskScore,
+    tags,
+  };
+}
+
+/**
+ * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117, #59, #66).
  */
 export class LlmClassifier {
   /**
@@ -256,6 +354,7 @@ export class LlmClassifier {
    *   timeoutPolicy?: "strict" | "permissive",
    *   maxRetries?: number,
    *   maxContextChars?: number,
+   *   supportsJsonMode?: boolean,
    *   fetch?: typeof globalThis.fetch
    * }} [options]
    */
@@ -267,11 +366,12 @@ export class LlmClassifier {
     this.timeoutPolicy = options.timeoutPolicy === "permissive" ? "permissive" : "strict";
     this.maxRetries = typeof options.maxRetries === "number" ? options.maxRetries : 2;
     this.maxContextChars = typeof options.maxContextChars === "number" ? options.maxContextChars : 1000;
+    this.supportsJsonMode = options.supportsJsonMode !== false;
     this.fetch = options.fetch || globalThis.fetch;
   }
 
   /**
-   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117).
+   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117, #66).
    *
    * @param {any} execution
    * @param {any} [context]
@@ -286,7 +386,7 @@ export class LlmClassifier {
         role: "system",
         content:
           "You are a security approval gate classifier. Analyze the provided tool execution request. " +
-          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\"}.",
+          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\", \"riskScore\": <0.0-1.0>, \"tags\": [\"<tag>\"]}.",
       },
       {
         role: "user",
@@ -296,11 +396,11 @@ export class LlmClassifier {
   }
 
   /**
-   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117).
+   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117, #59, #66).
    *
    * @param {any} execution
    * @param {any} [context]
-   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, timeout?: boolean, error?: any }>}
+   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, riskScore?: number, tags?: string[], timeout?: boolean, error?: any }>}
    */
   async classify(execution, context = {}) {
     if (!this.endpoint || typeof this.fetch !== "function") {
@@ -308,15 +408,19 @@ export class LlmClassifier {
     }
 
     const messages = this.formatMessages(execution, context);
-    const body = JSON.stringify({
-      model: this.model,
-      messages,
-      temperature: 0.1,
-      response_format: { type: "json_object" },
-    });
 
-    try {
-      const response = await withLlmRetry(
+    const callApi = async (useJsonMode) => {
+      const payload = {
+        model: this.model,
+        messages,
+        temperature: 0.1,
+      };
+      if (useJsonMode) {
+        payload.response_format = { type: "json_object" };
+      }
+      const body = JSON.stringify(payload);
+
+      return withLlmRetry(
         async () => {
           const controller = new AbortController();
           const timer = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -354,23 +458,49 @@ export class LlmClassifier {
           retryOn: shouldRetryLlmError,
         }
       );
+    };
+
+    try {
+      let response;
+      if (this.supportsJsonMode) {
+        try {
+          response = await callApi(true);
+        } catch (err) {
+          if (isShapeRejectError(err)) {
+            this.supportsJsonMode = false;
+            response = await callApi(false);
+          } else {
+            throw err;
+          }
+        }
+      } else {
+        response = await callApi(false);
+      }
 
       const content = response?.choices?.[0]?.message?.content;
       if (!content) {
         return { verdict: "ask", reason: "classifier-empty-response" };
       }
 
-      let parsed;
-      try {
-        parsed = JSON.parse(content);
-      } catch {
+      const parsed = extractJsonPayload(content);
+      if (!parsed) {
         return { verdict: "ask", reason: "classifier-invalid-json" };
       }
 
-      const verdict = ["allow", "deny", "ask"].includes(parsed.verdict) ? parsed.verdict : "ask";
+      const validated = validateClassifierResponse(parsed);
+      if (!validated.valid) {
+        return {
+          verdict: "ask",
+          reason: "malformed-classifier-response",
+          detail: validated.error,
+        };
+      }
+
       return {
-        verdict,
-        reason: parsed.reason || `classifier-${verdict}`,
+        verdict: validated.verdict,
+        reason: validated.reason,
+        riskScore: validated.riskScore,
+        tags: validated.tags,
       };
     } catch (err) {
       const isTimeout = CircuitBreaker.isFaultOrTimeout(err) || Boolean(err?.isTimeout);

package/lib/contract-guard.js

@@ -0,0 +1,147 @@
+// lib/contract-guard.js
+// Enforces task contract boundaries and blocks out-of-scope system mutations (#87).
+
+const SYSTEM_PACKAGE_MANAGERS = new Set([
+  "apt",
+  "apt-get",
+  "dpkg",
+  "yum",
+  "dnf",
+  "pacman",
+  "zypper",
+  "brew",
+  "snap",
+  "flatpak",
+  "apk",
+]);
+
+const SYSTEM_SERVICE_COMMANDS = new Set([
+  "systemctl",
+  "service",
+  "init",
+  "reboot",
+  "shutdown",
+  "poweroff",
+]);
+
+const SYSTEM_NETWORKING_COMMANDS = new Set([
+  "iptables",
+  "ufw",
+  "firewalld",
+  "ifconfig",
+  "netplan",
+]);
+
+const SYSTEM_CONFIG_TARGETS = [
+  "/etc/passwd",
+  "/etc/shadow",
+  "/etc/sudoers",
+  "/etc/fstab",
+  "/etc/hosts",
+  "/etc/pam.d",
+  "/etc/profile",
+  "/etc/bash.bashrc",
+];
+
+/**
+ * Validates whether a command or tool execution stays within task contract boundaries (#87).
+ */
+export class ContractGuard {
+  /**
+   * @param {{
+   *   allowSystemMutations?: boolean,
+   *   allowedTools?: string[],
+   *   allowedCommands?: string[],
+   *   forbiddenCommands?: string[]
+   * }} [contract]
+   */
+  constructor(contract = {}) {
+    this.allowSystemMutations = contract.allowSystemMutations === true;
+    this.allowedTools = Array.isArray(contract.allowedTools) ? new Set(contract.allowedTools) : null;
+    this.allowedCommands = Array.isArray(contract.allowedCommands) ? new Set(contract.allowedCommands) : null;
+    this.forbiddenCommands = Array.isArray(contract.forbiddenCommands) ? new Set(contract.forbiddenCommands) : null;
+  }
+
+  /**
+   * Checks if an execution violates the task contract boundaries.
+   *
+   * @param {string} toolName
+   * @param {string} [command]
+   * @param {any} [execution]
+   * @returns {{ allowed: boolean, reason?: string, detail?: string, snippet?: string }}
+   */
+  check(toolName, command, execution) {
+    // 1. Tool-level restriction
+    if (this.allowedTools && toolName && !this.allowedTools.has(toolName)) {
+      return {
+        allowed: false,
+        reason: "contract-violation",
+        detail: `Tool '${toolName}' is not permitted by task contract`,
+        snippet: toolName,
+      };
+    }
+
+    if (!command || typeof command !== "string") {
+      return { allowed: true };
+    }
+
+    const trimmed = command.trim();
+    if (!trimmed) return { allowed: true };
+
+    const firstWord = trimmed.split(/\s+/)[0].replace(/^sudo\s+/, "");
+
+    // 2. Explicit forbidden command list
+    if (this.forbiddenCommands && this.forbiddenCommands.has(firstWord)) {
+      return {
+        allowed: false,
+        reason: "contract-violation",
+        detail: `Command '${firstWord}' is explicitly forbidden by task contract`,
+        snippet: firstWord,
+      };
+    }
+
+    // 3. System mutations guard when allowSystemMutations is false
+    if (!this.allowSystemMutations) {
+      if (SYSTEM_PACKAGE_MANAGERS.has(firstWord)) {
+        return {
+          allowed: false,
+          reason: "contract-violation",
+          detail: `Out-of-scope system package manager invocation: ${firstWord}`,
+          snippet: trimmed,
+        };
+      }
+
+      if (SYSTEM_SERVICE_COMMANDS.has(firstWord)) {
+        return {
+          allowed: false,
+          reason: "contract-violation",
+          detail: `Out-of-scope system service or reboot control: ${firstWord}`,
+          snippet: trimmed,
+        };
+      }
+
+      if (SYSTEM_NETWORKING_COMMANDS.has(firstWord)) {
+        return {
+          allowed: false,
+          reason: "contract-violation",
+          detail: `Out-of-scope network configuration command: ${firstWord}`,
+          snippet: trimmed,
+        };
+      }
+
+      // Check system configuration mutation redirects
+      for (const target of SYSTEM_CONFIG_TARGETS) {
+        if (trimmed.includes(target) && /[><]/.test(trimmed)) {
+          return {
+            allowed: false,
+            reason: "contract-violation",
+            detail: `Out-of-scope system configuration file write: ${target}`,
+            snippet: trimmed,
+          };
+        }
+      }
+    }
+
+    return { allowed: true };
+  }
+}