@drakon-systems/shieldcortex-realtime 3.4.4 → 4.8.0

package/README.md

@@ -32,7 +32,7 @@ openclaw plugins install @drakon-systems/shieldcortex-realtime
 If you also want the companion session hook, install it from the main package:
 
 ```bash
-openclaw hooks install shieldcortex
+openclaw skills install shieldcortex
 ```
 
 Restart OpenClaw after installing:

package/index.ts

@@ -1,11 +1,11 @@
 /**
- * ShieldCortex Real-time Scanning Plugin for OpenClaw v2026.2.15+
+ * ShieldCortex Real-time Scanning Plugin for OpenClaw v2026.3.22+
  *
- * Hooks into llm_input/llm_output for real-time defence scanning
- * and optional memory extraction. All operations are fire-and-forget.
+ * Uses explicit capability registration (registerHook + registerCommand)
+ * for llm_input/llm_output scanning and optional memory extraction.
+ * All scanning operations are fire-and-forget.
  */
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -13,6 +13,10 @@ import path from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
+import type { InterceptorConfig, ToolCallContext } from './interceptor.js';
+import { syncInterceptEvent } from './intercept-ingest.js';
+
 // ==================== RESILIENT RUNTIME LOADER ====================
 // Resolves runtime.mjs from multiple locations so the plugin works both
 // inside the npm package tree AND when copied to ~/.openclaw/extensions/
@@ -48,49 +52,43 @@ function collectRuntimeCandidates(): string[] {
   // 1. Relative path (works when running from within npm package tree)
   candidates.add(new URL("../../hooks/openclaw/cortex-memory/runtime.mjs", import.meta.url).href);
 
-  // 2. Environment variable override
-  if (process.env.SHIELDCORTEX_ROOT) {
-    addRuntimeCandidate(candidates, process.env.SHIELDCORTEX_ROOT);
-  }
+  // 2. Config file override (reads path from ~/.shieldcortex/config.json instead of env var)
+  try {
+    const cfgPath = path.join(homedir(), ".shieldcortex", "config.json");
+    if (existsSync(cfgPath)) {
+      const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+      if (cfg.installRoot) addRuntimeCandidate(candidates, cfg.installRoot);
+    }
+  } catch { /* no config */ }
 
   // 3. Walk up from current file location
   addAncestorCandidates(candidates, path.dirname(fileURLToPath(import.meta.url)));
 
-  // 4. Find via shieldcortex binary
-  try {
-    const bin = execFileSync("which", ["shieldcortex"], {
-      encoding: "utf-8",
-      timeout: 3000,
-    }).trim();
-    if (bin) addAncestorCandidates(candidates, realpathSync(bin));
-  } catch {}
-
-  // 5. npm global root
-  try {
-    const npmRoot = execFileSync("npm", ["root", "-g"], {
-      encoding: "utf-8",
-      timeout: 3000,
-    }).trim();
-    if (npmRoot) addRuntimeCandidate(candidates, path.join(npmRoot, "shieldcortex"));
-  } catch {}
-
-  // 6. npm prefix
-  try {
-    const prefix = execFileSync("npm", ["config", "get", "prefix"], {
-      encoding: "utf-8",
-      timeout: 3000,
-    }).trim();
-    if (prefix) addRuntimeCandidate(candidates, path.join(prefix, "lib", "node_modules", "shieldcortex"));
-  } catch {}
+  // 4. Resolve via common bin symlink paths (no child_process needed)
+  for (const binDir of ["/usr/local/bin", "/opt/homebrew/bin", path.join(homedir(), ".npm-global", "bin")]) {
+    const binPath = path.join(binDir, "shieldcortex");
+    try {
+      if (existsSync(binPath)) addAncestorCandidates(candidates, realpathSync(binPath));
+    } catch { /* broken symlink */ }
+  }
 
-  // 7. Common global install paths
+  // 5. Common global install paths (covers npm root -g results without spawning npm)
   for (const root of [
     "/usr/lib/node_modules/shieldcortex",
     "/usr/local/lib/node_modules/shieldcortex",
     "/opt/homebrew/lib/node_modules/shieldcortex",
     path.join(homedir(), ".npm-global", "lib", "node_modules", "shieldcortex"),
+    path.join(homedir(), ".nvm", "versions", "node"),  // nvm users
   ]) {
-    addRuntimeCandidate(candidates, root);
+    if (root.includes(".nvm")) {
+      // For nvm, check the current symlink
+      try {
+        const currentNode = path.join(homedir(), ".nvm", "current", "lib", "node_modules", "shieldcortex");
+        addRuntimeCandidate(candidates, currentNode);
+      } catch { /* no nvm */ }
+    } else {
+      addRuntimeCandidate(candidates, root);
+    }
   }
 
   return [...candidates];
@@ -214,14 +212,16 @@ let _config: SCConfig | null = null;
 let _configOverride: SCConfig | null = null;
 let _version = "0.0.0";
 try {
-  for (const packageUrl of [
+  // Try package.json first, then openclaw.plugin.json (the manifest IS copied to extensions/)
+  for (const candidateUrl of [
     new URL("./package.json", import.meta.url),
     new URL("../../package.json", import.meta.url),
+    new URL("./openclaw.plugin.json", import.meta.url),
   ]) {
     try {
-      const pkg = JSON.parse(readFileSync(packageUrl, "utf-8"));
-      if (typeof pkg.version === "string" && pkg.version.trim()) {
-        _version = pkg.version;
+      const data = JSON.parse(readFileSync(candidateUrl, "utf-8"));
+      if (typeof data.version === "string" && data.version.trim()) {
+        _version = data.version;
         break;
       }
     } catch {
@@ -230,6 +230,8 @@ try {
   }
 } catch { /* fallback */ }
 
+let _registered = false;
+
 function normaliseConfig(raw: unknown): SCConfig {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 
@@ -674,9 +676,125 @@ export default {
   },
 
   register(api: PluginApi) {
+    if (_registered) return;
+    _registered = true;
+    try {
     applyPluginConfigOverride(api);
-    api.on("llm_input", handleLlmInput);
-    api.on("llm_output", handleLlmOutput);
-    api.logger.info("[shieldcortex] Real-time scanning plugin registered (llm_input + llm_output)");
+
+    // --- Interceptor (lazy init) ---
+    let interceptorReady: ReturnType<typeof createInterceptor> | null = null;
+    let interceptorInitAttempted = false;
+
+    async function initInterceptor(): Promise<ReturnType<typeof createInterceptor> | null> {
+      if (interceptorInitAttempted) return interceptorReady;
+      interceptorInitAttempted = true;
+
+      try {
+        const scConfig = await loadConfig();
+        const rawInterceptorConfig = (scConfig as any).interceptor;
+        const interceptorConfig: InterceptorConfig = {
+          ...DEFAULT_INTERCEPTOR_CONFIG,
+          ...(rawInterceptorConfig && typeof rawInterceptorConfig === 'object' ? {
+            enabled: rawInterceptorConfig.enabled ?? DEFAULT_INTERCEPTOR_CONFIG.enabled,
+            severityActions: { ...DEFAULT_INTERCEPTOR_CONFIG.severityActions, ...rawInterceptorConfig.severityActions },
+            failurePolicy: { ...DEFAULT_INTERCEPTOR_CONFIG.failurePolicy, ...rawInterceptorConfig.failurePolicy },
+          } : {}),
+          logger: { info: api.logger?.info ?? console.log, warn: (api.logger as any)?.warn ?? console.warn },
+        };
+
+        if (!interceptorConfig.enabled) return null;
+
+        // Dynamic import with string variable to prevent TypeScript from resolving
+        // at compile time — 'shieldcortex/defence' only exists at runtime when the
+        // package is installed globally, not during CI builds of the plugin itself.
+        let defenceMod: any;
+        try {
+          const defenceModPath = 'shieldcortex' + '/defence';
+          defenceMod = await import(/* webpackIgnore: true */ defenceModPath);
+        } catch (importErr) {
+          // Stack overflow or missing module — interceptor can't load
+          (api.logger as any)?.warn?.(`[shieldcortex] Cannot load defence module: ${importErr instanceof Error ? importErr.message : importErr}`);
+          return null;
+        }
+        if (typeof defenceMod.runDefencePipeline !== 'function') return null;
+
+        interceptorReady = createInterceptor(interceptorConfig, defenceMod.runDefencePipeline as Parameters<typeof createInterceptor>[1], {
+          onAuditEntry: (entry) => syncInterceptEvent(entry, {
+            cloudApiKey: (scConfig as any).cloudApiKey ?? '',
+            cloudBaseUrl: (scConfig as any).cloudBaseUrl ?? 'https://api.shieldcortex.ai',
+            cloudEnabled: (scConfig as any).cloudEnabled ?? false,
+          }),
+        });
+        api.logger?.info?.('[shieldcortex] Interceptor active — watching: remember, mcp__memory__remember');
+        return interceptorReady;
+      } catch (err) {
+        (api.logger as any)?.warn?.(`[shieldcortex] Interceptor init failed: ${err instanceof Error ? err.message : err}`);
+        return null;
+      }
+    }
+
+    // Register before_tool_call with lazy-init wrapper
+    api.registerHook('before_tool_call', async (context: ToolCallContext) => {
+      const interceptor = await initInterceptor();
+      if (!interceptor) return;
+      try {
+        await interceptor.handleToolCall(context);
+      } catch (err) {
+        // Intentional blocks from the interceptor (ShieldCortex: ...) should propagate
+        if (err instanceof Error && err.message.startsWith('ShieldCortex:')) throw err;
+        // Unexpected errors (DB crash, etc.) — log and allow the tool call through
+        (api.logger as any)?.warn?.(`[shieldcortex] Interceptor error (allowing tool call): ${err instanceof Error ? err.message : err}`);
+      }
+    }, {
+      name: 'shieldcortex-intercept-tool',
+      description: 'Active threat gating on tool calls',
+    });
+
+    // Try to register session_end for cache cleanup
+    try {
+      api.registerHook('session_end', () => { interceptorReady?.resetSession(); }, {
+        name: 'shieldcortex-session-cleanup',
+        description: 'Clear interceptor deny cache on session end',
+      });
+    } catch {
+      // session_end may not be a supported hook — TTL safety net handles this
+    }
+
+    // Explicit capability registration (replaces legacy api.on)
+    api.registerHook("llm_input", handleLlmInput, {
+      name: "shieldcortex-scan-input",
+      description: "Real-time threat scanning on LLM input",
+    });
+    api.registerHook("llm_output", handleLlmOutput, {
+      name: "shieldcortex-scan-output",
+      description: "Memory extraction from LLM output",
+    });
+
+    // Register a lightweight status command so the plugin is not hook-only
+    api.registerCommand({
+      name: "shieldcortex-status",
+      description: "Show ShieldCortex real-time scanner status",
+      async handler() {
+        const cfg = await loadConfig();
+        const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
+        const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
+        const cloud = cfg.cloudApiKey ? "configured" : "not configured";
+        return {
+          text:
+            `ShieldCortex v${_version}\n` +
+            `  Hooks: llm_input (scan), llm_output (memory)\n` +
+            `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
+            `  Cloud sync: ${cloud}`,
+        };
+      },
+    });
+
+    api.logger.info(`[shieldcortex] v${_version} registered (llm_input + llm_output + before_tool_call + /shieldcortex-status)`);
+    } catch (err) {
+      // Plugin must never block channel startup — warn and bail gracefully
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[shieldcortex] WARNING: Plugin failed to initialize: ${msg}`);
+      console.warn('[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+    }
   },
 };

package/intercept-ingest.ts

@@ -0,0 +1,28 @@
+// plugins/openclaw/intercept-ingest.ts
+import type { InterceptAuditEntry } from './interceptor.js';
+
+interface CloudConfig {
+  cloudApiKey: string;
+  cloudBaseUrl: string;
+  cloudEnabled: boolean;
+}
+
+export function syncInterceptEvent(event: InterceptAuditEntry, config: CloudConfig): void {
+  if (!config.cloudEnabled || !config.cloudApiKey) return;
+
+  const url = `${config.cloudBaseUrl}/v1/audit/ingest`;
+
+  fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${config.cloudApiKey}`,
+    },
+    body: JSON.stringify({
+      events: [{ ...event, source: 'openclaw-interceptor' }],
+    }),
+    signal: AbortSignal.timeout(5_000),
+  }).catch(() => {
+    // Fire-and-forget — never block on cloud sync failure
+  });
+}

package/interceptor.ts

@@ -0,0 +1,461 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
+export type InterceptAction = 'log' | 'warn' | 'require_approval';
+export type FailureAction = 'allow' | 'deny';
+
+export interface InterceptorConfig {
+  enabled: boolean;
+  severityActions: Record<Severity, InterceptAction>;
+  failurePolicy: Record<Severity, FailureAction>;
+  logger?: { info: (msg: string) => void; warn: (msg: string) => void };
+}
+
+export interface ToolCallContext {
+  toolName: string;
+  arguments: Record<string, unknown>;
+  requireApproval?: (message: string) => Promise<boolean>;
+}
+
+export interface InterceptAuditEntry {
+  type: 'intercept';
+  tool: string;
+  severity: Severity;
+  firewallResult: string;
+  threats: string[];
+  anomalyScore: number;
+  action: InterceptAction | 'auto_deny' | 'rate_limit';
+  outcome: 'approved' | 'denied' | 'auto_denied' | 'logged' | 'warned' | 'failure_allowed' | 'failure_denied';
+  preview: string;
+  ts: string;
+}
+
+const WATCHED_TOOLS = ['remember', 'mcp__memory__remember'] as const;
+
+const CONTENT_FIELDS: Record<string, string[]> = {
+  remember: ['content', 'title'],
+  mcp__memory__remember: ['content', 'title'],
+};
+
+const DEFAULT_CONFIG: InterceptorConfig = {
+  enabled: true,
+  severityActions: {
+    low: 'log',
+    medium: 'warn',
+    high: 'require_approval',
+    critical: 'require_approval',
+  },
+  failurePolicy: {
+    low: 'allow',
+    medium: 'allow',
+    high: 'deny',
+    critical: 'deny',
+  },
+};
+
+export { WATCHED_TOOLS, CONTENT_FIELDS, DEFAULT_CONFIG };
+
+export function extractContent(toolName: string, args: Record<string, unknown>): { title: string; content: string } {
+  const fields = CONTENT_FIELDS[toolName];
+  if (!fields) return { title: '', content: '' };
+  const title = typeof args.title === 'string' ? args.title : '';
+  const content = typeof args.content === 'string' ? args.content : '';
+  return { title, content };
+}
+
+interface FirewallResult {
+  result: 'ALLOW' | 'BLOCK' | 'QUARANTINE';
+  anomalyScore: number;
+}
+
+export function mapSeverity(firewall: FirewallResult): Severity {
+  if (firewall.result === 'BLOCK') return 'critical';
+  if (firewall.result === 'QUARANTINE') return 'high';
+  if (firewall.result === 'ALLOW' && firewall.anomalyScore >= 0.3) return 'medium';
+  return 'low';
+}
+
+// --- Deny Cache ---
+
+// Exact replica of normalizeMemoryText() from index.ts (lines 426-434).
+// Must produce identical output for SHA-256 hash consistency.
+function normaliseContent(text: string): string {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[`"'\\]/g, ' ')
+    .replace(/https?:\/\/\S+/g, ' ')
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function hashContent(text: string): string {
+  return createHash('sha256').update(normaliseContent(text)).digest('hex');
+}
+
+interface DenyCacheEntry {
+  hash: string;
+  ts: number;
+}
+
+const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+
+export class DenyCache {
+  private cache = new Map<string, DenyCacheEntry[]>();
+  private maxPerTool: number;
+  private ttlMs: number;
+
+  constructor(maxPerTool = 200, ttlMs = TWO_HOURS_MS) {
+    this.maxPerTool = maxPerTool;
+    this.ttlMs = ttlMs;
+  }
+
+  isDenied(tool: string, content: string): boolean {
+    const entries = this.cache.get(tool);
+    if (!entries) return false;
+    const hash = hashContent(content);
+    const now = Date.now();
+    return entries.some(e => e.hash === hash && (now - e.ts) < this.ttlMs);
+  }
+
+  addDenial(tool: string, content: string): void {
+    const hash = hashContent(content);
+    const now = Date.now();
+    if (!this.cache.has(tool)) {
+      this.cache.set(tool, []);
+    }
+    const entries = this.cache.get(tool)!;
+    const live = entries.filter(e => (now - e.ts) < this.ttlMs);
+    if (live.some(e => e.hash === hash)) return;
+    live.push({ hash, ts: now });
+    while (live.length > this.maxPerTool) {
+      live.shift();
+    }
+    this.cache.set(tool, live);
+  }
+
+  reset(): void {
+    this.cache.clear();
+  }
+}
+
+// --- Rate Limiter ---
+
+export class RateLimiter {
+  private timestamps: number[] = [];
+  private maxPerWindow: number;
+  private windowMs: number;
+
+  constructor(maxPerWindow = 5, windowMs = 60_000) {
+    this.maxPerWindow = maxPerWindow;
+    this.windowMs = windowMs;
+  }
+
+  shouldAllow(): boolean {
+    const now = Date.now();
+    this.timestamps = this.timestamps.filter(t => now - t < this.windowMs);
+    if (this.timestamps.length >= this.maxPerWindow) return false;
+    this.timestamps.push(now);
+    return true;
+  }
+}
+
+// --- Approval Prompt ---
+
+interface ApprovalPromptInput {
+  tool: string;
+  severity: Severity;
+  firewallResult: string;
+  threats: string[];
+  content: string;
+}
+
+export function formatApprovalPrompt(input: ApprovalPromptInput): string {
+  const preview = input.content.length > 200
+    ? input.content.slice(0, 200) + '...'
+    : input.content;
+  const threatList = input.threats.length > 0
+    ? input.threats.join(', ')
+    : 'none identified';
+
+  return [
+    '🛡️ ShieldCortex — Tool Call Intercepted',
+    '',
+    `Tool:       ${input.tool}`,
+    `Risk:       ${input.severity} (${input.firewallResult})`,
+    `Threats:    ${threatList}`,
+    `Content:    "${preview}"`,
+    '',
+    '[Approve]  [Deny]',
+  ].join('\n');
+}
+
+// --- Audit Logging (local JSONL) ---
+
+const AUDIT_DIR = join(homedir(), '.shieldcortex', 'audit');
+
+function writeAuditEntry(entry: InterceptAuditEntry): void {
+  try {
+    mkdirSync(AUDIT_DIR, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const file = join(AUDIT_DIR, `realtime-${date}.jsonl`);
+    appendFileSync(file, JSON.stringify(entry) + '\n');
+  } catch {
+    // Best-effort — never block on audit failure
+  }
+}
+
+// --- X-Ray Inline Guard ---
+// Lightweight inline version of xrayMemoryContent for the plugin build boundary.
+// Detects AI directive injection patterns in memory content.
+
+const XRAY_AI_DIRECTIVE_PATTERNS: RegExp[] = [
+  /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?|context)/i,
+  /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?)/i,
+  /override\s+(previous|prior|all)\s+(instructions?|rules?|constraints?)/i,
+  /you\s+are\s+now\s+(?:in\s+)?(?:developer|god|admin|root|unrestricted)\s+mode/i,
+  /enter\s+(?:developer|god|admin|DAN|jailbreak)\s+mode/i,
+  /(?:system|hidden|secret)\s*(?:prompt|instruction|directive)\s*:/i,
+  /\[SYSTEM\]\s*:/i,
+  /\[INST\]/i,
+  /<\|(?:system|user|assistant|im_start|im_end)\|>/i,
+  /(?:decode|execute|follow)\s+(?:the\s+)?hidden\s+(?:instructions?|payload|message)/i,
+  /(?:hidden|embedded|encoded)\s+(?:instructions?|directive|command)\s+(?:in|within|inside)/i,
+];
+
+const XRAY_FILENAME_PATTERNS: RegExp[] = [
+  /ignore_previous/i, /decode_hidden/i, /execute_instructions/i,
+  /override_previous/i, /developer_mode/i, /system_prompt/i,
+  /jailbreak/i, /\[SYSTEM\]/i, /\[INST\]/i,
+];
+
+interface XRayGuardResult {
+  allowed: boolean;
+  findings: Array<{ category: string; title: string; severity: string }>;
+  riskLevel: string;
+}
+
+function xrayMemoryGuard(content: string, title?: string): XRayGuardResult {
+  const findings: Array<{ category: string; title: string; severity: string }> = [];
+  const text = content.length > 50000 ? content.slice(0, 50000) : content;
+
+  for (const pattern of XRAY_AI_DIRECTIVE_PATTERNS) {
+    if (pattern.test(text)) {
+      findings.push({ category: 'ai-directive', title: 'AI directive injection detected', severity: 'critical' });
+      break;
+    }
+  }
+
+  if (title) {
+    for (const pattern of XRAY_FILENAME_PATTERNS) {
+      if (pattern.test(title)) {
+        findings.push({ category: 'ai-directive', title: 'AI directive in title', severity: 'critical' });
+        break;
+      }
+    }
+  }
+
+  // Score: 100 - 60 per critical finding (single critical = blocked)
+  const score = Math.max(0, 100 - findings.length * 60);
+  const riskLevel = score >= 80 ? 'SAFE' : score >= 60 ? 'LOW' : score >= 40 ? 'MEDIUM' : score >= 20 ? 'HIGH' : 'CRITICAL';
+  return { allowed: score >= 60, findings, riskLevel };
+}
+
+// --- Interceptor Factory ---
+
+type PipelineRunner = (content: string, title: string, source: { type: string; identifier: string }) => {
+  allowed: boolean;
+  firewall: {
+    result: 'ALLOW' | 'BLOCK' | 'QUARANTINE';
+    reason: string;
+    threatIndicators: string[];
+    anomalyScore: number;
+    blockedPatterns: string[];
+  };
+  auditId: number;
+};
+
+interface InterceptorOptions {
+  maxPromptsPerMinute?: number;
+  onAuditEntry?: (entry: InterceptAuditEntry) => void;
+}
+
+export function createInterceptor(
+  config: InterceptorConfig,
+  pipeline: PipelineRunner,
+  options?: InterceptorOptions,
+): {
+  handleToolCall: (context: ToolCallContext) => Promise<void>;
+  resetSession: () => void;
+} {
+  const denyCache = new DenyCache();
+  const rateLimiter = new RateLimiter(options?.maxPromptsPerMinute ?? 5);
+  const log = config.logger ?? { info: console.log, warn: console.warn };
+  const onAuditEntry = options?.onAuditEntry;
+
+  function emitAudit(entry: InterceptAuditEntry): void {
+    writeAuditEntry(entry);
+    onAuditEntry?.(entry);
+  }
+
+  async function handleToolCall(context: ToolCallContext): Promise<void> {
+    if (!(WATCHED_TOOLS as readonly string[]).includes(context.toolName)) return;
+
+    const { title, content } = extractContent(context.toolName, context.arguments);
+    const fullContent = [title, content].filter(Boolean).join(' ');
+    if (!fullContent.trim()) return;
+
+    // X-Ray content scan — fast, synchronous, no I/O
+    const xrayResult = xrayMemoryGuard(content, title || undefined);
+    if (!xrayResult.allowed) {
+      const xrayEntry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity: 'critical',
+        firewallResult: 'BLOCK', threats: xrayResult.findings.map(f => f.category),
+        anomalyScore: 1, action: 'auto_deny', outcome: 'auto_denied',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(xrayEntry);
+      throw new Error(`ShieldCortex: tool call blocked by X-Ray memory guard (risk: ${xrayResult.riskLevel}, findings: ${xrayResult.findings.length})`);
+    }
+
+    let severity: Severity;
+    let firewallResult: string;
+    let threats: string[];
+    let anomalyScore: number;
+
+    try {
+      const result = pipeline(content, title, { type: 'agent', identifier: 'openclaw' });
+      severity = mapSeverity(result.firewall);
+      firewallResult = result.firewall.result;
+      threats = result.firewall.threatIndicators;
+      anomalyScore = result.firewall.anomalyScore;
+    } catch (err) {
+      log.warn(`[shieldcortex] ⚠️ Defence pipeline error: ${err instanceof Error ? err.message : err}`);
+      const failAction = config.failurePolicy.high;
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity: 'high',
+        firewallResult: 'ERROR', threats: ['pipeline_error'], anomalyScore: 0,
+        action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      if (failAction === 'deny') {
+        throw new Error('ShieldCortex: tool call blocked — pipeline error, failure policy: deny');
+      }
+      return;
+    }
+
+    if (denyCache.isDenied(context.toolName, fullContent)) {
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'auto_deny', outcome: 'auto_denied',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      throw new Error('ShieldCortex: tool call auto-denied (previously denied content)');
+    }
+
+    const action = config.severityActions[severity];
+
+    if (action === 'log') {
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'log', outcome: 'logged',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      return;
+    }
+
+    if (action === 'warn') {
+      log.warn(`[shieldcortex] ⚠️ ${severity} risk in ${context.toolName}: ${threats.join(', ') || 'anomaly detected'}`);
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'warn', outcome: 'warned',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      return;
+    }
+
+    // action === 'require_approval'
+    if (typeof context.requireApproval !== 'function') {
+      // requireApproval unavailable (pre-v2026.3.28) — apply failurePolicy, not blanket allow
+      const failAction = config.failurePolicy[severity];
+      log.warn(`[shieldcortex] ⚠️ requireApproval not available for ${severity} risk in ${context.toolName} — failure policy: ${failAction}`);
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'require_approval',
+        outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      if (failAction === 'deny') {
+        throw new Error(`ShieldCortex: tool call blocked — requireApproval unavailable, failure policy: deny`);
+      }
+      return;
+    }
+
+    if (!rateLimiter.shouldAllow()) {
+      log.warn('[shieldcortex] ⚠️ Too many approval prompts — auto-denying');
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'rate_limit', outcome: 'auto_denied',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      denyCache.addDenial(context.toolName, fullContent);
+      throw new Error('ShieldCortex: tool call auto-denied (rate limit exceeded)');
+    }
+
+    const message = formatApprovalPrompt({ tool: context.toolName, severity, firewallResult, threats, content: fullContent });
+
+    let approved: boolean;
+    try {
+      approved = await context.requireApproval(message);
+    } catch (err) {
+      const failAction = config.failurePolicy[severity];
+      log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'require_approval',
+        outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      if (failAction === 'deny') {
+        throw new Error(`ShieldCortex: tool call blocked — requireApproval error, failure policy: deny`);
+      }
+      return;
+    }
+
+    if (approved) {
+      const entry: InterceptAuditEntry = {
+        type: 'intercept', tool: context.toolName, severity, firewallResult,
+        threats, anomalyScore, action: 'require_approval', outcome: 'approved',
+        preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+      };
+      emitAudit(entry);
+      return;
+    }
+
+    // Denied
+    denyCache.addDenial(context.toolName, fullContent);
+    const entry: InterceptAuditEntry = {
+      type: 'intercept', tool: context.toolName, severity, firewallResult,
+      threats, anomalyScore, action: 'require_approval', outcome: 'denied',
+      preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+    };
+    emitAudit(entry);
+    throw new Error('ShieldCortex: tool call denied by user');
+  }
+
+  function resetSession(): void {
+    denyCache.reset();
+  }
+
+  return { handleToolCall, resetSession };
+}

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "3.4.4",
+  "version": "4.8.0",
   "name": "ShieldCortex Real-time Scanner",
-  "description": "Real-time defence scanning on LLM input and memory extraction on LLM output.",
+  "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "uiHints": {
     "binaryPath": {
       "label": "ShieldCortex Binary Path",
@@ -40,6 +40,21 @@
       "label": "Recent Memory Cache Size",
       "help": "How many recent extracted memories to keep in the dedupe cache.",
       "advanced": true
+    },
+    "interceptor.enabled": {
+      "label": "Enable Tool Call Interceptor",
+      "description": "Scan memory-write tool calls and gate suspicious content behind user approval",
+      "type": "boolean"
+    },
+    "interceptor.severityActions.high": {
+      "label": "High Severity Action",
+      "description": "Action for high-severity threats (log, warn, require_approval)",
+      "type": "string"
+    },
+    "interceptor.severityActions.critical": {
+      "label": "Critical Severity Action",
+      "description": "Action for critical-severity threats (log, warn, require_approval)",
+      "type": "string"
     }
   },
   "configSchema": {
@@ -73,6 +88,32 @@
         "type": "integer",
         "minimum": 50,
         "maximum": 1000
+      },
+      "interceptor": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "severityActions": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "low": { "type": "string", "enum": ["log", "warn", "require_approval"], "default": "log" },
+              "medium": { "type": "string", "enum": ["log", "warn", "require_approval"], "default": "warn" },
+              "high": { "type": "string", "enum": ["log", "warn", "require_approval"], "default": "require_approval" },
+              "critical": { "type": "string", "enum": ["log", "warn", "require_approval"], "default": "require_approval" }
+            }
+          },
+          "failurePolicy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "low": { "type": "string", "enum": ["allow", "deny"], "default": "allow" },
+              "medium": { "type": "string", "enum": ["allow", "deny"], "default": "allow" },
+              "high": { "type": "string", "enum": ["allow", "deny"], "default": "deny" },
+              "critical": { "type": "string", "enum": ["allow", "deny"], "default": "deny" }
+            }
+          }
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "3.4.4",
+  "version": "4.8.0",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "index.ts",
@@ -15,6 +15,8 @@
   ],
   "files": [
     "index.ts",
+    "interceptor.ts",
+    "intercept-ingest.ts",
     "openclaw.plugin.json",
     "README.md"
   ],
@@ -22,7 +24,10 @@
     "pack:verify": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "shieldcortex": ">=3.4.4"
+    "shieldcortex": "^4.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "publishConfig": {
     "access": "public"