@drakon-systems/shieldcortex-realtime 4.47.4 → 4.47.6

package/README.md

@@ -4,9 +4,9 @@ OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory
 
 ## Compatibility
 
-- **Node.js** — ≥ 18 required
+- **Node.js** — ≥ 20 required (the `shieldcortex` peer ships `better-sqlite3` ^12, which needs Node 20+)
 - **OpenClaw** — ≥ 2026.3.22 required, **≥ 2026.4.23 recommended** — 2026.4.23 added host-package linking for plugins that declare `openclaw` as a peer dependency ([#70462](https://github.com/openclaw/openclaw/pull/70462)), which lets any future `openclaw/plugin-sdk/*` imports resolve without a duplicate runtime bundle
-- **ShieldCortex** — ≥ 4.11.1 required
+- **ShieldCortex** — ≥ 4.18.3 required (matches the declared peer dependency; ship both packages at the same version)
 
 OpenClaw is declared as an **optional** peer dependency, so installs on older OpenClaw keep working but miss the linking benefit.
 
@@ -29,9 +29,11 @@ The defensive root `openclaw.plugin.json` is kept for one release on the main pa
 |------|--------|
 | `llm_input` | Scans prompts and history through the ShieldCortex defence pipeline. Threats are logged to audit and can forward to ShieldCortex Cloud. |
 | `llm_output` | Extracts high-signal memories from assistant replies and writes them into ShieldCortex with novelty filtering and dedupe. |
-| `before_tool_call` | Runs the Action Guard before tools execute. Catastrophic shell/file/network/git actions are blocked; dangerous actions warn by default or request approval when enforcement is enabled. |
+| `before_tool_call` | Runs the Action Guard before tools execute. Catastrophic shell/file/network/git actions are always blocked. Recognised-dangerous actions are **enforced by default**: attended sessions get an approval prompt, unattended sessions fail closed per `failurePolicy`. Set `actionGuard.enforce: false` to opt down to warn-and-allow, or pre-approve specific operations with `actionGuard.autoApprove`. |
+| `session_end` | Resets the interceptor's per-session caches. |
+| `/shieldcortex-status` | Slash command reporting the plugin's runtime state. |
 
-The plugin is intentionally fire-and-forget: it should not stall the OpenClaw turn loop if ShieldCortex is unavailable.
+The scanning and memory paths are fire-and-forget: they do not stall the OpenClaw turn loop if ShieldCortex is unavailable. The Action Guard is the deliberate exception — it gates tool calls inline, and since 4.47.5 a guard that fails to load falls back to a dependency-free scanner that still denies unambiguous catastrophic operations (fail-closed) rather than allowing everything.
 
 ## Installation
 
@@ -108,6 +110,10 @@ Supported plugin config keys:
 - `openclawAutoMemoryDedupe`: enable or disable duplicate suppression
 - `openclawAutoMemoryNoveltyThreshold`: dedupe similarity threshold, `0.6` to `0.99`
 - `openclawAutoMemoryMaxRecent`: dedupe cache size, `50` to `1000`
+- `actionGuard.enabled`: turn the before-tool-call Action Guard on or off (default `true`)
+- `actionGuard.enforce`: enforce dangerous-operation gating (default `true`); `false` opts down to warn-and-allow. Catastrophic operations are blocked regardless.
+- `actionGuard.autoApprove`: array of operation allowlist entries for unattended agents that legitimately need specific dangerous operations
+- `failurePolicy`: per-severity verdict when a decision can't be obtained unattended (defaults: `low`/`medium` allow, `high`/`critical` deny)
 
 ## Auto-memory
 

package/dist/index.js

@@ -798,9 +798,22 @@ export default {
                     const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
                     const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
                     const cloud = cfg.cloudApiKey ? "configured" : "not configured";
+                    // Resolve the Action Guard state the same way initInterceptor() does,
+                    // so the status line reflects what before_tool_call will actually do.
+                    const rawInterceptor = cfg.interceptor;
+                    const guardCfg = {
+                        ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
+                        ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
+                    };
+                    const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
+                    const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
+                    const guardState = !interceptorOn || !guardCfg.enabled
+                        ? "off"
+                        : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
                     return {
                         text: `ShieldCortex v${_version}\n` +
-                            `  Hooks: llm_input (scan), llm_output (memory)\n` +
+                            `  Hooks: llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)\n` +
+                            `  Action guard: ${guardState}\n` +
                             `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
                             `  Cloud sync: ${cloud}`,
                     };

package/dist/interceptor.js

@@ -143,6 +143,51 @@ export function formatApprovalPrompt(input) {
         '[Approve]  [Deny]',
     ].join('\n');
 }
+// --- WS2 fail-closed fallback (guard load/eval failure) ---
+// Deliberately DUPLICATED from tool-action-guard.ts's CATASTROPHIC list, not
+// imported — this file already avoids a compile-time dependency on the main
+// package across the plugin build boundary (see ToolGuardVerdictLike above),
+// and the fallback specifically must keep working when THAT dependency is
+// what's broken. Narrow by design: only the unambiguous, essentially-never-
+// benign catastrophic shapes, so a broken/unwired guard still fails closed on
+// "rm -rf /"-class commands without turning every tool call into a denial
+// whenever the guard is merely unavailable (e.g. mid-upgrade) — that would
+// itself break unattended agents/cron, the outcome ShieldCortex exists to
+// prevent. Mirrored in scripts/pre-tool-hook.mjs for the Claude Code surface.
+const FALLBACK_CATASTROPHIC_PATTERNS = [
+    /\brm\b[^|;&\n]*?(?:-\w*r\w*f\w*|-\w*f\w*r\w*|(?=[^|;&\n]*--recursive)(?=[^|;&\n]*--force))/i,
+    /\brm\b[^|;&\n]*\s(?:-\w+\s+)*(?:\/|~|\$HOME|\/\*|\*|\.\/\*)(?:\s|$)/i,
+    /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:?\s*&?\s*\}\s*;\s*:/,
+    /\bmkfs(\.\w+)?\b/i,
+    /\bdd\b[^|;&\n]*\bof=\/dev\/(sd|nvme|hd|disk|mmcblk|vd)/i,
+    /\b(fdisk|parted|sgdisk|wipefs|blkdiscard)\b/i,
+    // Leading `[^\n|]*` (not `[^\n]*`, issue #92 must-fix 1: ReDoS) + `env <assign>
+    // <interp>` admitted (issue #92 must-fix 3) — mirrors tool-action-guard.ts's
+    // pipe-download-to-shell pattern exactly; kept in sync there.
+    /\b(?:curl|wget|fetch)\b[^\n|]*\|(?:[^\n|]*\|)*\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:env\s+)?(?:\w+=\S*\s+)*(?:bash|sh|zsh|ksh|python\d?|perl|ruby|node)\b(?!(?:\s+-[a-z]+)*\s+-[cem]\b)/i,
+    /\bch(?:mod|own)\b[^|;&\n]*(?:-\w*R\w*|--recursive)\b[^|;&\n]*\s\/(?:\s|$)/i,
+];
+const FALLBACK_SURFACE_KEYS = [
+    'command', 'cmd', 'script', 'code', 'input', 'shell', 'run',
+    'path', 'file_path', 'filePath', 'file', 'target', 'destination', 'dir', 'directory',
+    'url', 'uri', 'endpoint', 'href', 'host', 'to',
+];
+/** Same command/path/url field set tool-action-guard.ts extracts — narrow, not the whole args object. */
+function fallbackExecSurface(args) {
+    const parts = [];
+    for (const k of FALLBACK_SURFACE_KEYS) {
+        const v = args?.[k];
+        if (typeof v === 'string' && v.length > 0)
+            parts.push(v);
+    }
+    return parts.join('   ');
+}
+function fallbackCatastrophicMatch(args) {
+    const text = fallbackExecSurface(args);
+    if (!text)
+        return false;
+    return FALLBACK_CATASTROPHIC_PATTERNS.some(re => re.test(text));
+}
 /** One-line summary of tool args for audit previews (bounded, no secrets dumped). */
 export function summariseToolArgs(args) {
     if (!args)
@@ -247,19 +292,43 @@ export function createInterceptor(config, pipeline, options) {
             preview: preview.slice(0, 200), ts: new Date().toISOString(),
         };
     }
+    // WS2 fail-closed path: when the real guard was never wired in or throws,
+    // run the narrow fallback scan and DENY (throw) a catastrophic-looking
+    // command instead of silently allowing it. The fallback recognising nothing
+    // is not evidence the command is safe, only that it isn't one of the
+    // handful of unambiguous shapes — everything else still falls through to
+    // the pre-existing fail-OPEN log-and-allow.
+    function handleGuardUnavailable(context, reason) {
+        if (!fallbackCatastrophicMatch(context.arguments)) {
+            log.warn(`[shieldcortex] ⚠️ action-guard unavailable (${reason}) — allowing ${context.toolName}`);
+            return;
+        }
+        const preview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
+        emitAudit({
+            type: 'intercept', tool: context.toolName, severity: 'critical',
+            firewallResult: 'ACTION_GUARD_FALLBACK', threats: ['fallback-scan'],
+            anomalyScore: 1, trustScore: 0, sensitivityLevel: 'INTERNAL', fragmentationScore: null,
+            pipelineDurationMs: 0, preview: preview.slice(0, 200), ts: new Date().toISOString(),
+            action: 'auto_deny', outcome: 'auto_denied',
+        });
+        log.warn(`[shieldcortex] action-guard UNAVAILABLE (${reason}) and fallback scan matched a catastrophic pattern — DENYING ${context.toolName} (fail-closed, WS2)`);
+        throw new Error(`ShieldCortex: tool call blocked — action guard unavailable (${reason}), fallback catastrophic scan matched`);
+    }
     // Action Guard: gates non-memory tool calls (shell / file / network / git).
     // This is what makes "Iron Dome protects what the agent DOES" true at runtime.
     async function runActionGuard(context) {
-        if (!actionGuardCfg.enabled || typeof evaluateToolCall !== 'function')
+        if (!actionGuardCfg.enabled)
+            return;
+        if (typeof evaluateToolCall !== 'function') {
+            handleGuardUnavailable(context, 'evaluateToolCall not wired');
             return;
+        }
         let v;
         try {
             v = evaluateToolCall(context.toolName, context.arguments || {});
         }
         catch (err) {
-            // A guard error must never break the agent — log and allow. (The memory
-            // pipeline is the hard-fail path; the action guard is best-effort.)
-            log.warn(`[shieldcortex] ⚠️ action-guard error (allowing ${context.toolName}): ${err instanceof Error ? err.message : err}`);
+            handleGuardUnavailable(context, `action-guard error: ${err instanceof Error ? err.message : err}`);
             return;
         }
         if (v.decision === 'allow')

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.47.4",
+  "version": "4.47.6",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,
@@ -77,6 +77,22 @@
       "label": "Critical Severity Action",
       "description": "Action for critical-severity threats (log, warn, require_approval)",
       "type": "string"
+    },
+    "interceptor.actionGuard.enabled": {
+      "label": "Action Guard",
+      "description": "Gate dangerous shell/file/network/git tool calls before they execute. Catastrophic operations are always blocked while enabled.",
+      "type": "boolean"
+    },
+    "interceptor.actionGuard.enforce": {
+      "label": "Enforce Action Guard",
+      "description": "Enforce dangerous-operation gating (attended: approval prompt; unattended: failurePolicy). Off = warn-and-allow (advisory). Catastrophic operations block regardless.",
+      "type": "boolean"
+    },
+    "interceptor.actionGuard.autoApprove": {
+      "label": "Action Guard Auto-approve List",
+      "description": "Family/action/signal names pre-approved for unattended agents that legitimately need specific dangerous operations (case-insensitive substring match). Never applies to catastrophic operations.",
+      "type": "array",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -197,6 +213,27 @@
                 "default": "deny"
               }
             }
+          },
+          "actionGuard": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true
+              },
+              "enforce": {
+                "type": "boolean",
+                "default": true
+              },
+              "autoApprove": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": []
+              }
+            }
           }
         }
       }

package/index.ts

@@ -946,10 +946,23 @@ export default {
         const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
         const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
         const cloud = cfg.cloudApiKey ? "configured" : "not configured";
+        // Resolve the Action Guard state the same way initInterceptor() does,
+        // so the status line reflects what before_tool_call will actually do.
+        const rawInterceptor = (cfg as any).interceptor;
+        const guardCfg = {
+          ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
+          ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
+        };
+        const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
+        const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
+        const guardState = !interceptorOn || !guardCfg.enabled
+          ? "off"
+          : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
         return {
           text:
             `ShieldCortex v${_version}\n` +
-            `  Hooks: llm_input (scan), llm_output (memory)\n` +
+            `  Hooks: llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)\n` +
+            `  Action guard: ${guardState}\n` +
             `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
             `  Cloud sync: ${cloud}`,
         };

package/interceptor.ts

@@ -247,6 +247,53 @@ export function formatApprovalPrompt(input: ApprovalPromptInput): string {
   ].join('\n');
 }
 
+// --- WS2 fail-closed fallback (guard load/eval failure) ---
+// Deliberately DUPLICATED from tool-action-guard.ts's CATASTROPHIC list, not
+// imported — this file already avoids a compile-time dependency on the main
+// package across the plugin build boundary (see ToolGuardVerdictLike above),
+// and the fallback specifically must keep working when THAT dependency is
+// what's broken. Narrow by design: only the unambiguous, essentially-never-
+// benign catastrophic shapes, so a broken/unwired guard still fails closed on
+// "rm -rf /"-class commands without turning every tool call into a denial
+// whenever the guard is merely unavailable (e.g. mid-upgrade) — that would
+// itself break unattended agents/cron, the outcome ShieldCortex exists to
+// prevent. Mirrored in scripts/pre-tool-hook.mjs for the Claude Code surface.
+const FALLBACK_CATASTROPHIC_PATTERNS: RegExp[] = [
+  /\brm\b[^|;&\n]*?(?:-\w*r\w*f\w*|-\w*f\w*r\w*|(?=[^|;&\n]*--recursive)(?=[^|;&\n]*--force))/i,
+  /\brm\b[^|;&\n]*\s(?:-\w+\s+)*(?:\/|~|\$HOME|\/\*|\*|\.\/\*)(?:\s|$)/i,
+  /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:?\s*&?\s*\}\s*;\s*:/,
+  /\bmkfs(\.\w+)?\b/i,
+  /\bdd\b[^|;&\n]*\bof=\/dev\/(sd|nvme|hd|disk|mmcblk|vd)/i,
+  /\b(fdisk|parted|sgdisk|wipefs|blkdiscard)\b/i,
+  // Leading `[^\n|]*` (not `[^\n]*`, issue #92 must-fix 1: ReDoS) + `env <assign>
+  // <interp>` admitted (issue #92 must-fix 3) — mirrors tool-action-guard.ts's
+  // pipe-download-to-shell pattern exactly; kept in sync there.
+  /\b(?:curl|wget|fetch)\b[^\n|]*\|(?:[^\n|]*\|)*\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:env\s+)?(?:\w+=\S*\s+)*(?:bash|sh|zsh|ksh|python\d?|perl|ruby|node)\b(?!(?:\s+-[a-z]+)*\s+-[cem]\b)/i,
+  /\bch(?:mod|own)\b[^|;&\n]*(?:-\w*R\w*|--recursive)\b[^|;&\n]*\s\/(?:\s|$)/i,
+];
+
+const FALLBACK_SURFACE_KEYS = [
+  'command', 'cmd', 'script', 'code', 'input', 'shell', 'run',
+  'path', 'file_path', 'filePath', 'file', 'target', 'destination', 'dir', 'directory',
+  'url', 'uri', 'endpoint', 'href', 'host', 'to',
+];
+
+/** Same command/path/url field set tool-action-guard.ts extracts — narrow, not the whole args object. */
+function fallbackExecSurface(args: Record<string, unknown> | undefined): string {
+  const parts: string[] = [];
+  for (const k of FALLBACK_SURFACE_KEYS) {
+    const v = args?.[k];
+    if (typeof v === 'string' && v.length > 0) parts.push(v);
+  }
+  return parts.join('   ');
+}
+
+function fallbackCatastrophicMatch(args: Record<string, unknown> | undefined): boolean {
+  const text = fallbackExecSurface(args);
+  if (!text) return false;
+  return FALLBACK_CATASTROPHIC_PATTERNS.some(re => re.test(text));
+}
+
 /** One-line summary of tool args for audit previews (bounded, no secrets dumped). */
 export function summariseToolArgs(args: Record<string, unknown> | undefined): string {
   if (!args) return '';
@@ -403,18 +450,44 @@ export function createInterceptor(
     };
   }
 
+  // WS2 fail-closed path: when the real guard was never wired in or throws,
+  // run the narrow fallback scan and DENY (throw) a catastrophic-looking
+  // command instead of silently allowing it. The fallback recognising nothing
+  // is not evidence the command is safe, only that it isn't one of the
+  // handful of unambiguous shapes — everything else still falls through to
+  // the pre-existing fail-OPEN log-and-allow.
+  function handleGuardUnavailable(context: ToolCallContext, reason: string): void {
+    if (!fallbackCatastrophicMatch(context.arguments)) {
+      log.warn(`[shieldcortex] ⚠️ action-guard unavailable (${reason}) — allowing ${context.toolName}`);
+      return;
+    }
+    const preview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
+    emitAudit({
+      type: 'intercept', tool: context.toolName, severity: 'critical',
+      firewallResult: 'ACTION_GUARD_FALLBACK', threats: ['fallback-scan'],
+      anomalyScore: 1, trustScore: 0, sensitivityLevel: 'INTERNAL', fragmentationScore: null,
+      pipelineDurationMs: 0, preview: preview.slice(0, 200), ts: new Date().toISOString(),
+      action: 'auto_deny', outcome: 'auto_denied',
+    });
+    log.warn(`[shieldcortex] action-guard UNAVAILABLE (${reason}) and fallback scan matched a catastrophic pattern — DENYING ${context.toolName} (fail-closed, WS2)`);
+    throw new Error(`ShieldCortex: tool call blocked — action guard unavailable (${reason}), fallback catastrophic scan matched`);
+  }
+
   // Action Guard: gates non-memory tool calls (shell / file / network / git).
   // This is what makes "Iron Dome protects what the agent DOES" true at runtime.
   async function runActionGuard(context: ToolCallContext): Promise<void> {
-    if (!actionGuardCfg.enabled || typeof evaluateToolCall !== 'function') return;
+    if (!actionGuardCfg.enabled) return;
+
+    if (typeof evaluateToolCall !== 'function') {
+      handleGuardUnavailable(context, 'evaluateToolCall not wired');
+      return;
+    }
 
     let v: ToolGuardVerdictLike;
     try {
       v = evaluateToolCall(context.toolName, context.arguments || {});
     } catch (err) {
-      // A guard error must never break the agent — log and allow. (The memory
-      // pipeline is the hard-fail path; the action guard is best-effort.)
-      log.warn(`[shieldcortex] ⚠️ action-guard error (allowing ${context.toolName}): ${err instanceof Error ? err.message : err}`);
+      handleGuardUnavailable(context, `action-guard error: ${err instanceof Error ? err.message : err}`);
       return;
     }
     if (v.decision === 'allow') return;

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.47.4",
+  "version": "4.47.6",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,
@@ -77,6 +77,22 @@
       "label": "Critical Severity Action",
       "description": "Action for critical-severity threats (log, warn, require_approval)",
       "type": "string"
+    },
+    "interceptor.actionGuard.enabled": {
+      "label": "Action Guard",
+      "description": "Gate dangerous shell/file/network/git tool calls before they execute. Catastrophic operations are always blocked while enabled.",
+      "type": "boolean"
+    },
+    "interceptor.actionGuard.enforce": {
+      "label": "Enforce Action Guard",
+      "description": "Enforce dangerous-operation gating (attended: approval prompt; unattended: failurePolicy). Off = warn-and-allow (advisory). Catastrophic operations block regardless.",
+      "type": "boolean"
+    },
+    "interceptor.actionGuard.autoApprove": {
+      "label": "Action Guard Auto-approve List",
+      "description": "Family/action/signal names pre-approved for unattended agents that legitimately need specific dangerous operations (case-insensitive substring match). Never applies to catastrophic operations.",
+      "type": "array",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -197,6 +213,27 @@
                 "default": "deny"
               }
             }
+          },
+          "actionGuard": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true
+              },
+              "enforce": {
+                "type": "boolean",
+                "default": true
+              },
+              "autoApprove": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": []
+              }
+            }
           }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.47.4",
+  "version": "4.47.6",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0",
+    "node": ">=20.0.0",
     "openclaw": ">=2026.4.23"
   },
   "publishConfig": {