@drakon-systems/shieldcortex-realtime 4.54.4 → 4.54.7

package/dist/index.js

@@ -32,6 +32,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { readConversationAccess, describeRegisteredHooks } from './conversation-access.js';
 import { createSessionTaintStore } from './session-taint.js';
+import { isTaintingScanSummary, severityFromScanSummary } from './scan-taint-policy.js';
 import { classifyConversationOrigin } from './conversation-trust.js';
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
 import { syncInterceptEvent } from './intercept-ingest.js';
@@ -1529,12 +1530,29 @@ export async function scanRealtimeContent(text) {
     if (defenceMod && typeof defenceMod.scanToolResponse === "function") {
         try {
             const scan = defenceMod.scanToolResponse("openclaw-realtime", text, "advisory");
-            // Reproduce the historical summary contract exactly: risk level + detection
-            // count only when the injection scan flagged something.
-            const risk = scan.injection.clean ? "unknown" : scan.injection.riskLevel;
-            const summary = scan.injection.clean
-                ? risk
-                : `${risk} (${scan.injection.detections.length} detections)`;
+            // #361: never summarise a dirty overall scan as bare "unknown".
+            // Historical path used injection.riskLevel only when injection fired; when
+            // another layer dirtied the scan (encoding/instructions/credentials/etc.)
+            // while injection stayed clean, risk defaulted to "unknown" and the llm_input
+            // path treated that as a positive detection → session taint → AG escalate →
+            // broker unavailable deadlock on benign threads.
+            // Prefer the scanner's own multi-layer summary when dirty; only use the
+            // compact "RISK (N detections)" form for pure injection hits.
+            let summary;
+            if (scan.clean) {
+                summary = 'NONE';
+            }
+            else if (!scan.injection.clean) {
+                const risk = scan.injection.riskLevel || 'UNKNOWN';
+                summary = `${risk} (${scan.injection.detections.length} detections)`;
+            }
+            else if (typeof scan.summary === 'string' && scan.summary.trim()) {
+                // e.g. 'THREAT in "openclaw-realtime" response: encoding: base64 (12ms)'
+                summary = scan.summary;
+            }
+            else {
+                summary = 'THREAT (non-injection layer)';
+            }
             return { clean: scan.clean, summary, available: true };
         }
         catch (err) {
@@ -1853,7 +1871,10 @@ async function createNoveltyGate(config) {
     };
 }
 // ==================== HOOK HANDLERS ====================
-// Skip scanning internal OpenClaw content (boot checks, system prompts, heartbeats)
+// Skip scanning internal OpenClaw content (boot checks, system prompts, heartbeats).
+// #353: isolated cron prepends a host envelope (`[cron:<id> name]`) so the
+// heartbeat ritual is no longer at column 0. Recognition of THAT wrap uses
+// host session identity, never a spoofable prompt prefix.
 const SKIP_PATTERNS = [
     /^You are running a boot check/i,
     /^Read HEARTBEAT\.md/i,
@@ -1864,8 +1885,59 @@ const SKIP_PATTERNS = [
     /^A subagent task/i,
     /subagent.*completed/i,
 ];
-function isInternalContent(text) {
-    return SKIP_PATTERNS.some(p => p.test(text.trim()));
+/** Host-generated isolated heartbeat / cron session keys. Prompt text is never
+ *  a substitute. Tight prefixes only — `direct:heartbeat` is not trusted. */
+const HOST_HEARTBEAT_SESSION = /^(?:agent:[A-Za-z0-9._-]+:)+(?:main:)?heartbeat(?:$|:run:)/i;
+const HOST_CRON_SESSION = /^(?:agent:[A-Za-z0-9._-]+:)*cron:[A-Za-z0-9._-]+(?:$|:run:)/i;
+export function isTrustedAutomationSession(sessionId) {
+    if (typeof sessionId !== 'string')
+        return false;
+    const trimmed = sessionId.trim();
+    if (!trimmed || trimmed.length > 256 || /\s/.test(trimmed))
+        return false;
+    return HOST_HEARTBEAT_SESSION.test(trimmed) || HOST_CRON_SESSION.test(trimmed);
+}
+const HOST_CRON_ENVELOPE_LINE = /^\s*\[cron:[^\]]+\]\s*$/;
+const HOST_CRON_ENVELOPE_PREFIX = /^\s*\[cron:[^\]]+\][ \t]+/;
+/** Drop at most one leading host cron envelope (own line or same-line prefix).
+ *  Later `[cron:…]` tokens stay in the body so a user cannot bury an injection
+ *  after a fake wrap. */
+export function stripOneHostCronEnvelope(text) {
+    const raw = String(text ?? '');
+    const nl = raw.search(/\r?\n/);
+    const first = nl === -1 ? raw : raw.slice(0, nl);
+    if (HOST_CRON_ENVELOPE_LINE.test(first)) {
+        return nl === -1 ? '' : raw.slice(nl).replace(/^\r?\n/, '');
+    }
+    if (HOST_CRON_ENVELOPE_PREFIX.test(first)) {
+        const strippedFirst = first.replace(HOST_CRON_ENVELOPE_PREFIX, '');
+        return nl === -1 ? strippedFirst : strippedFirst + raw.slice(nl);
+    }
+    return raw;
+}
+function matchesSkipPatterns(text) {
+    return SKIP_PATTERNS.some((p) => p.test(text.trim()));
+}
+export function isInternalContent(text, sessionId) {
+    const body = String(text ?? '');
+    if (matchesSkipPatterns(body))
+        return true;
+    if (!isTrustedAutomationSession(sessionId))
+        return false;
+    const inner = stripOneHostCronEnvelope(body);
+    if (inner === body)
+        return false;
+    return matchesSkipPatterns(inner);
+}
+function resolveHookSessionId(event, ctx) {
+    const fromEvent = typeof event?.sessionId === 'string' ? event.sessionId.trim() : '';
+    if (fromEvent)
+        return fromEvent;
+    const fromCtx = typeof ctx?.sessionId === 'string' ? ctx.sessionId.trim() : '';
+    if (fromCtx)
+        return fromCtx;
+    const fromKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey.trim() : '';
+    return fromKey || undefined;
 }
 // Awaitable scan body — extracted so the jest suite can verify behaviour
 // deterministically. handleLlmInput wraps this fire-and-forget so the hook
@@ -1905,8 +1977,9 @@ export async function scanLlmInput(event, _ctx) {
             }
             return trustMemo;
         };
+        const sessionId = resolveHookSessionId(event, _ctx);
         const userTexts = extractUserContent(event.historyMessages).slice(-5);
-        const texts = [event.prompt, ...userTexts].filter(t => t && !isInternalContent(t));
+        const texts = [event.prompt, ...userTexts].filter(t => t && !isInternalContent(t, sessionId));
         for (const text of texts) {
             if (!text || text.length < 10)
                 continue;
@@ -1952,8 +2025,15 @@ export async function scanLlmInput(event, _ctx) {
                 // logs" is an instruction, and treating it as an attack is the false
                 // alarm that gets a control switched off. Everything the agent was
                 // handed — including another agent on a closed channel — is data.
-                if (trust.mayTaint) {
-                    sessionTaint.mark(event.sessionId, { reason: `conversation scan: ${result.summary}` });
+                // #361: taint only on a concrete detection summary. Bare "unknown" (and
+                // scanner-unavailable shapes) must not escalate Action Guard — they are
+                // degraded/uncertain states, not positive threats. Real injection keeps
+                // the HIGH/CRITICAL (N detections) form and still taints.
+                if (trust.mayTaint && isTaintingScanSummary(result.summary)) {
+                    sessionTaint.mark(event.sessionId, {
+                        severity: severityFromScanSummary(result.summary),
+                        reason: `conversation scan: ${result.summary}`,
+                    });
                 }
                 // #226: NO `preview`. This row carried the first 100 characters of the
                 // prompt — the exact text that tripped an injection detector, i.e.
@@ -1972,7 +2052,8 @@ export async function scanLlmInput(event, _ctx) {
                     // Whether this detection tainted the session (threat-graph Phase D:
                     // lets the threat graph attribute taint-raising events). Metadata
                     // only — no content, same as the fields above.
-                    tainted: trust.mayTaint,
+                    // #361: mirrors the mark gate — unknown/unavailable never count as taint.
+                    tainted: trust.mayTaint && isTaintingScanSummary(result.summary),
                     // Writer-side attestation (attestation Phase 4): the hook identity
                     // above is a hardcoded literal — no conversation content can reach
                     // it. RECORD-ONLY at the reader (attribution metadata); the JSONL
@@ -2383,11 +2464,12 @@ export async function handleBeforeAgentRun(event, ctx) {
         if (posture === 'off')
             return gatePass();
         const text = String(event?.prompt ?? '');
-        if (!text || text.length < 10 || isInternalContent(text))
-            return gatePass();
         // sessionId/model come off the hook CONTEXT (PluginHookAgentContext); the
         // event carries neither. Both are optional there too, so both may be absent.
-        const sessionId = ctx?.sessionId ?? ctx?.sessionKey;
+        // Resolve BEFORE the internal-content skip so #353 can see the host key.
+        const sessionId = resolveHookSessionId(undefined, ctx);
+        if (!text || text.length < 10 || isInternalContent(text, sessionId))
+            return gatePass();
         const model = ctx?.modelId;
         // scanRealtimeContent no longer throws on the paths that used to (it
         // reports `available:false` instead), but a defensive catch stays: this

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.4",
+  "version": "4.54.7",
   "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,

package/dist/scan-taint-policy.js

@@ -0,0 +1,37 @@
+/**
+ * #361 — which conversation-scan summaries may raise session taint.
+ *
+ * Session taint escalates Action Guard. Only concrete detections may do that.
+ * Uncertainty ("unknown"), unavailable scanners, and empty noise must not.
+ */
+export function isTaintingScanSummary(summary) {
+    if (!summary || typeof summary !== 'string')
+        return false;
+    const s = summary.trim();
+    if (!s)
+        return false;
+    const lower = s.toLowerCase();
+    if (lower === 'unknown' || lower === 'none' || lower === 'clean')
+        return false;
+    if (lower.includes('scan unavailable') || lower.includes('unscanned'))
+        return false;
+    if (/\b(critical|high|medium|low)\b/i.test(s))
+        return true;
+    if (/\bthreat\b/i.test(s))
+        return true;
+    if (/\bdetections?\b/i.test(s) && /\d+/.test(s))
+        return true;
+    return false;
+}
+export function severityFromScanSummary(summary) {
+    const s = summary.toLowerCase();
+    if (/\bcritical\b/.test(s))
+        return 'critical';
+    if (/\bhigh\b/.test(s))
+        return 'high';
+    if (/\bmedium\b/.test(s))
+        return 'medium';
+    if (/\blow\b/.test(s))
+        return 'low';
+    return 'medium';
+}

package/index.ts

@@ -34,6 +34,7 @@ import { createRequire } from "node:module";
 
 import { readConversationAccess, describeRegisteredHooks } from './conversation-access.js';
 import { createSessionTaintStore } from './session-taint.js';
+import { isTaintingScanSummary, severityFromScanSummary } from './scan-taint-policy.js';
 import { classifyConversationOrigin } from './conversation-trust.js';
 import type { ConversationTrustDecision } from './conversation-trust.js';
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
@@ -64,6 +65,8 @@ type DefenceModule = {
     mode?: 'advisory' | 'enforce',
   ) => {
     clean: boolean;
+    /** Multi-layer human summary — required for #361 non-injection dirty path. */
+    summary?: string;
     injection: { clean: boolean; riskLevel: string; detections: unknown[] };
   };
   /** #225 sink: the notify transport shared with the Action Guard (#143).
@@ -1895,12 +1898,26 @@ export async function scanRealtimeContent(text: string): Promise<ConversationSca
   if (defenceMod && typeof defenceMod.scanToolResponse === "function") {
     try {
       const scan = defenceMod.scanToolResponse("openclaw-realtime", text, "advisory");
-      // Reproduce the historical summary contract exactly: risk level + detection
-      // count only when the injection scan flagged something.
-      const risk = scan.injection.clean ? "unknown" : scan.injection.riskLevel;
-      const summary = scan.injection.clean
-        ? risk
-        : `${risk} (${scan.injection.detections.length} detections)`;
+      // #361: never summarise a dirty overall scan as bare "unknown".
+      // Historical path used injection.riskLevel only when injection fired; when
+      // another layer dirtied the scan (encoding/instructions/credentials/etc.)
+      // while injection stayed clean, risk defaulted to "unknown" and the llm_input
+      // path treated that as a positive detection → session taint → AG escalate →
+      // broker unavailable deadlock on benign threads.
+      // Prefer the scanner's own multi-layer summary when dirty; only use the
+      // compact "RISK (N detections)" form for pure injection hits.
+      let summary: string;
+      if (scan.clean) {
+        summary = 'NONE';
+      } else if (!scan.injection.clean) {
+        const risk = scan.injection.riskLevel || 'UNKNOWN';
+        summary = `${risk} (${scan.injection.detections.length} detections)`;
+      } else if (typeof scan.summary === 'string' && scan.summary.trim()) {
+        // e.g. 'THREAT in "openclaw-realtime" response: encoding: base64 (12ms)'
+        summary = scan.summary;
+      } else {
+        summary = 'THREAT (non-injection layer)';
+      }
       return { clean: scan.clean, summary, available: true };
     } catch (err) {
       // A scanner that THROWS is not a clean verdict either. Same treatment as
@@ -2251,7 +2268,10 @@ async function createNoveltyGate(config: SCConfig): Promise<{
 
 // ==================== HOOK HANDLERS ====================
 
-// Skip scanning internal OpenClaw content (boot checks, system prompts, heartbeats)
+// Skip scanning internal OpenClaw content (boot checks, system prompts, heartbeats).
+// #353: isolated cron prepends a host envelope (`[cron:<id> name]`) so the
+// heartbeat ritual is no longer at column 0. Recognition of THAT wrap uses
+// host session identity, never a spoofable prompt prefix.
 const SKIP_PATTERNS = [
   /^You are running a boot check/i,
   /^Read HEARTBEAT\.md/i,
@@ -2262,8 +2282,64 @@ const SKIP_PATTERNS = [
   /^A subagent task/i,
   /subagent.*completed/i,
 ];
-function isInternalContent(text: string): boolean {
-  return SKIP_PATTERNS.some(p => p.test(text.trim()));
+
+/** Host-generated isolated heartbeat / cron session keys. Prompt text is never
+ *  a substitute. Tight prefixes only — `direct:heartbeat` is not trusted. */
+const HOST_HEARTBEAT_SESSION =
+  /^(?:agent:[A-Za-z0-9._-]+:)+(?:main:)?heartbeat(?:$|:run:)/i;
+const HOST_CRON_SESSION =
+  /^(?:agent:[A-Za-z0-9._-]+:)*cron:[A-Za-z0-9._-]+(?:$|:run:)/i;
+
+export function isTrustedAutomationSession(sessionId?: string | null): boolean {
+  if (typeof sessionId !== 'string') return false;
+  const trimmed = sessionId.trim();
+  if (!trimmed || trimmed.length > 256 || /\s/.test(trimmed)) return false;
+  return HOST_HEARTBEAT_SESSION.test(trimmed) || HOST_CRON_SESSION.test(trimmed);
+}
+
+const HOST_CRON_ENVELOPE_LINE = /^\s*\[cron:[^\]]+\]\s*$/;
+const HOST_CRON_ENVELOPE_PREFIX = /^\s*\[cron:[^\]]+\][ \t]+/;
+
+/** Drop at most one leading host cron envelope (own line or same-line prefix).
+ *  Later `[cron:…]` tokens stay in the body so a user cannot bury an injection
+ *  after a fake wrap. */
+export function stripOneHostCronEnvelope(text: string): string {
+  const raw = String(text ?? '');
+  const nl = raw.search(/\r?\n/);
+  const first = nl === -1 ? raw : raw.slice(0, nl);
+  if (HOST_CRON_ENVELOPE_LINE.test(first)) {
+    return nl === -1 ? '' : raw.slice(nl).replace(/^\r?\n/, '');
+  }
+  if (HOST_CRON_ENVELOPE_PREFIX.test(first)) {
+    const strippedFirst = first.replace(HOST_CRON_ENVELOPE_PREFIX, '');
+    return nl === -1 ? strippedFirst : strippedFirst + raw.slice(nl);
+  }
+  return raw;
+}
+
+function matchesSkipPatterns(text: string): boolean {
+  return SKIP_PATTERNS.some((p) => p.test(text.trim()));
+}
+
+export function isInternalContent(text: string, sessionId?: string | null): boolean {
+  const body = String(text ?? '');
+  if (matchesSkipPatterns(body)) return true;
+  if (!isTrustedAutomationSession(sessionId)) return false;
+  const inner = stripOneHostCronEnvelope(body);
+  if (inner === body) return false;
+  return matchesSkipPatterns(inner);
+}
+
+function resolveHookSessionId(
+  event: { sessionId?: string } | undefined,
+  ctx?: AgentCtx,
+): string | undefined {
+  const fromEvent = typeof event?.sessionId === 'string' ? event.sessionId.trim() : '';
+  if (fromEvent) return fromEvent;
+  const fromCtx = typeof ctx?.sessionId === 'string' ? ctx.sessionId.trim() : '';
+  if (fromCtx) return fromCtx;
+  const fromKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey.trim() : '';
+  return fromKey || undefined;
 }
 
 // Awaitable scan body — extracted so the jest suite can verify behaviour
@@ -2304,8 +2380,9 @@ export async function scanLlmInput(event: LlmInputEvent, _ctx: AgentCtx): Promis
       }
       return trustMemo;
     };
+    const sessionId = resolveHookSessionId(event, _ctx);
     const userTexts = extractUserContent(event.historyMessages).slice(-5);
-    const texts = [event.prompt, ...userTexts].filter(t => t && !isInternalContent(t));
+    const texts = [event.prompt, ...userTexts].filter(t => t && !isInternalContent(t, sessionId));
     for (const text of texts) {
       if (!text || text.length < 10) continue;
       const result = await scanRealtimeContent(text);
@@ -2352,8 +2429,15 @@ export async function scanLlmInput(event: LlmInputEvent, _ctx: AgentCtx): Promis
         // logs" is an instruction, and treating it as an attack is the false
         // alarm that gets a control switched off. Everything the agent was
         // handed — including another agent on a closed channel — is data.
-        if (trust.mayTaint) {
-          sessionTaint.mark(event.sessionId, { reason: `conversation scan: ${result.summary}` });
+        // #361: taint only on a concrete detection summary. Bare "unknown" (and
+        // scanner-unavailable shapes) must not escalate Action Guard — they are
+        // degraded/uncertain states, not positive threats. Real injection keeps
+        // the HIGH/CRITICAL (N detections) form and still taints.
+        if (trust.mayTaint && isTaintingScanSummary(result.summary)) {
+          sessionTaint.mark(event.sessionId, {
+            severity: severityFromScanSummary(result.summary),
+            reason: `conversation scan: ${result.summary}`,
+          });
         }
         // #226: NO `preview`. This row carried the first 100 characters of the
         // prompt — the exact text that tripped an injection detector, i.e.
@@ -2372,7 +2456,8 @@ export async function scanLlmInput(event: LlmInputEvent, _ctx: AgentCtx): Promis
           // Whether this detection tainted the session (threat-graph Phase D:
           // lets the threat graph attribute taint-raising events). Metadata
           // only — no content, same as the fields above.
-          tainted: trust.mayTaint,
+          // #361: mirrors the mark gate — unknown/unavailable never count as taint.
+          tainted: trust.mayTaint && isTaintingScanSummary(result.summary),
           // Writer-side attestation (attestation Phase 4): the hook identity
           // above is a hardcoded literal — no conversation content can reach
           // it. RECORD-ONLY at the reader (attribution metadata); the JSONL
@@ -2896,11 +2981,11 @@ export async function handleBeforeAgentRun(
     if (posture === 'off') return gatePass();
 
     const text = String(event?.prompt ?? '');
-    if (!text || text.length < 10 || isInternalContent(text)) return gatePass();
-
     // sessionId/model come off the hook CONTEXT (PluginHookAgentContext); the
     // event carries neither. Both are optional there too, so both may be absent.
-    const sessionId = ctx?.sessionId ?? ctx?.sessionKey;
+    // Resolve BEFORE the internal-content skip so #353 can see the host key.
+    const sessionId = resolveHookSessionId(undefined, ctx);
+    if (!text || text.length < 10 || isInternalContent(text, sessionId)) return gatePass();
     const model = (ctx as { modelId?: string } | undefined)?.modelId;
 
     // scanRealtimeContent no longer throws on the paths that used to (it

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.4",
+  "version": "4.54.7",
   "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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.54.4",
+  "version": "4.54.7",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
     "prepublishOnly": "node -e \"if(!require('fs').existsSync('dist/index.js'))throw new Error('plugin dist/index.js missing — run `npm run build:ts` from the repo root before publishing')\""
   },
   "peerDependencies": {
-    "shieldcortex": ">=4.18.3 <5.0.0",
+    "shieldcortex": "^4.54.6",
     "openclaw": ">=2026.3.22"
   },
   "peerDependenciesMeta": {