@drakon-systems/shieldcortex-realtime 5.0.4 → 5.0.6

package/interceptor.ts

@@ -541,7 +541,7 @@ const FALLBACK_CATASTROPHIC_PATTERNS: RegExp[] = [
 // `isGatedNpxBunx` (shape-based, #96), not by a DANGEROUS pattern, and a blunt
 // fallback matching them would over-gate `npx tsc`; `uvx`/`dlx` (unconditional)
 // ARE covered. Mirrored in scripts/pre-tool-hook.mjs + hermes/sc_client.py.
-const FALLBACK_DANGEROUS_PATTERNS: Array<{ re: RegExp; signal: string }> = [
+const FALLBACK_DANGEROUS_PATTERNS: Array<{ re: RegExp; signal: string; lockPath?: true }> = [
   { re: /\brm\b|\bunlink\b|\brmdir\b|(?:(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?|\bxargs\s+(?:-{1,2}\S+\s+)*|-exec\s+)shred\b/i, signal: 'file-delete' },
   { re: /\bsudo\b|\bdoas\b|\bsu\s/i, signal: 'privilege-escalation' },
   { re: /\bgit\b[^|\n]*\bpush\b[^|\n]*(--force\b|-f\b|\+)/i, signal: 'git-force-push' },
@@ -560,6 +560,20 @@ const FALLBACK_DANGEROUS_PATTERNS: Array<{ re: RegExp; signal: string }> = [
   { re: /\.shieldcortex[\\/]+approvals\b/i, signal: 'touch-approval-store' },
   // Session-lease ledger + store (#227): a freeze an agent can edit is not a freeze.
   { re: /\.shieldcortex[\\/]+(?:DECISIONS\.md|leases)\b/i, signal: 'touch-decisions-ledger' },
+  // #500: outage fallback must gate self-disable / global uninstall / config.json writes.
+  { re: /--action-guard-(?:disable|advisory)\b|\biron-dome\s+deactivate\b/i, signal: 'disable-action-guard' },
+  { re: /\b(?:npm|yarn|pnpm|bun)\b[^|;&\n]*\b(?:uninstall|remove)\b[^|;&\n]*\b(?:shieldcortex|@drakon-systems\/shieldcortex-realtime)\b/i, signal: 'disable-action-guard' },
+  { re: /\.shieldcortex[\\/]+config\.json\b/i, signal: 'touch-guard-config' },
+  // #501: the policy lock's own attack surface. The two environment seams that
+  // decide WHICH policy-lock reader runs and which root it reads; the protected
+  // root and its pointer; and `~/.claude/settings.json`, whose `env` stanza is
+  // the same-UID file that delivers those variables into the enforcing
+  // process. All at the `disable-action-guard` tier, because that is what they
+  // are. Kept byte-identical with the sibling table by the #501 drift test in
+  // enforcement-surface-parity.
+  { re: /\bSHIELDCORTEX_(?:DIST_ROOT|PROTECTED_ROOT)\s*=/i, signal: 'disable-action-guard' },
+  { re: /\/etc\/shieldcortex(?:\.conf\b|[\\/]|(?![\w.-]))/i, signal: 'disable-action-guard', lockPath: true },
+  { re: /(?:^|[\s'"=:(\\/])\.claude[\\/]+settings(?:\.local)?\.json\b/i, signal: 'disable-action-guard', lockPath: true },
   { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?uvx\b/i, signal: 'registry-code-exec' },
   { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:pnpm|yarn)\b[^|;&\n]*\bdlx\b/i, signal: 'registry-code-exec' },
   { re: /\b(?:base64|openssl|xxd|cat|http)\b[^\n|]*\|(?:[^\n|]*\|)*\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:bash|sh|zsh|ksh|python\d?|perl|ruby|node)\b(?:\s+-)?\s*(?:[;&|\n]|$)/i, signal: 'decode-pipe-to-shell' },
@@ -584,6 +598,17 @@ function fallbackExecSurface(args: Record<string, unknown> | undefined): string
   for (const k of FALLBACK_SURFACE_KEYS) {
     const v = args?.[k];
     if (typeof v === 'string' && v.length > 0) parts.push(v);
+    // #522 r7 FIND-4: an ARGV ARRAY under one of these keys is a real host
+    // shape, and the guard this fallback stands in for already reads it —
+    // `rawStringArgs` in tool-action-guard.ts joins string arrays, and the
+    // catastrophic tier blocks the array form of a recursive root delete.
+    // Skipping arrays here made the degraded scan strictly weaker than the
+    // evaluator it replaces, on exactly the tier documented as an
+    // unconditional deny.
+    else if (Array.isArray(v)) {
+      const joined = v.filter((e) => typeof e === 'string').join(' ');
+      if (joined.length > 0) parts.push(joined);
+    }
   }
   return parts.join('   ').slice(0, FALLBACK_SCAN_CAP);
 }
@@ -594,11 +619,95 @@ function fallbackCatastrophicMatch(args: Record<string, unknown> | undefined): b
   return FALLBACK_CATASTROPHIC_PATTERNS.some(re => re.test(text));
 }
 
+
+// ── #522 G4: the lock-path READ carve-out, ported to the blunt fallback ──────
+//
+// `ee5c6ac1` gave the real guard a carve-out: pure inspection of the protected
+// root or `.claude/settings(.local).json` is not an attempt on the floor, so
+// `Read {file_path:<lock>}` and `cat|grep|jq|ls <lock>` allow while every write
+// shape still gates. That carve-out lives in tool-action-guard.ts — the module
+// that is MISSING in exactly this degraded mode. So a broken install on a
+// locked host carded every settings/policy read, which is the UX the carve-out
+// was written to stop. These mirror it, fail-closed, with no dependency on the
+// dist.
+//
+// Scope: this drops ONLY the two lock-PATH rows below (tagged `lockPath`).
+// The env-seam row, the #500 command shapes and every other signal are
+// untouched, so `rm`, `tee`, `cp`, `sed -i`, a redirect and `chmod` onto those
+// paths still gate here exactly as they did.
+
+/** Read-family tools cannot write; mirrors `classifyFamily`'s READ_TOOLS. */
+const FALLBACK_READ_TOOLS = /^(read|read_file|cat|less|more|head|tail|view|open|get|glob|grep|search|find|ls|list|list_files|stat|pwd|which|web_search|websearch)$/;
+/** Shell verbs that only OBSERVE — the guard's LOCK_READONLY_VERB_RE set. */
+const FALLBACK_LOCK_READ_VERB_RE = /^(?:ls|dir|cat|head|tail|less|more|stat|file|wc|grep|egrep|fgrep|rg|ag|ack|realpath|readlink|basename|dirname|test|\[|echo|printf|jq)$/i;
+/** `git <sub>` stages that only read history / the working tree. */
+const FALLBACK_GIT_READ_SUB_RE = /^(?:log|show|diff|status|blame|ls-files)$/i;
+/**
+ * True when a `git` stage writes a file or runs a configured driver. Judged per
+ * TOKEN with quotes stripped, not against the raw spelling: a pattern that
+ * required whitespace immediately before `--` was defeated by an ordinary
+ * quoted argument (#522 r2). The short form is matched GLUED as well as bare
+ * (`-o<file>` is what parse-options accepts). Mirrors `gitStageWritesOrExecs`
+ * in src/defence/iron-dome/tool-action-guard.ts — keep the three in lockstep.
+ */
+function fallbackGitStageWrites(stage: string): boolean {
+  for (const raw of stage.split(/\s+/)) {
+    if (!raw) continue;
+    const token = raw.replace(/['"]/g, '');
+    if (/^-o(?:$|[^-])/.test(token)) return true;
+    if (/^--(?:output|ext-diff)\b/i.test(token)) return true;
+  }
+  return false;
+}
+/** Any non-fd-dup redirect, glued or spaced — `echo x > <lock>` is a WRITE. */
+const FALLBACK_REDIRECT_RE = />{1,2}\|?(?!&\d)/;
+/** Nested execution keeps the gate; the verb whitelist cannot see inside it. */
+const FALLBACK_NESTED_EXEC_RE = /\$\(|`|<\(|>\(|\beval\b|\bsource\b|\b\.\s+\/|\bfunction\b|[\w.-]+\s*\(\s*\)\s*\{/i;
+/** Assigning an env seam decides WHICH reader runs — never a read. */
+const FALLBACK_LOCK_ENV_SEAM_RE = /\bSHIELDCORTEX_(?:DIST_ROOT|PROTECTED_ROOT)\s*=/i;
+
+/**
+ * True when the whole surface is pure inspection of a lock path. Fail-closed on
+ * an env-seam assignment, a redirect, nested execution, and any unknown verb in
+ * any stage of any statement — the same rule the real guard applies, with the
+ * statement split done conservatively (`&` and `|` both separate, so a
+ * pipeline stage or a backgrounded sibling must ALSO be a read).
+ */
+function fallbackLockPathAccessIsReadOnly(text: string, toolName: string | undefined): boolean {
+  if (!text) return false;
+  if (FALLBACK_LOCK_ENV_SEAM_RE.test(text)) return false;
+  const seg = String(toolName || '').toLowerCase().split(/__|\.|:|\//).filter(Boolean).pop() || '';
+  if (seg && FALLBACK_READ_TOOLS.test(seg)) return true;
+  if (FALLBACK_REDIRECT_RE.test(text) || FALLBACK_NESTED_EXEC_RE.test(text)) return false;
+  let sawStage = false;
+  for (const raw of text.split(/[\n;&|]+/)) {
+    const stage = raw.trim();
+    if (!stage) continue;
+    sawStage = true;
+    const toks = stage
+      .replace(/^(?:[A-Za-z_]\w*=\S*\s+)+/, '')
+      .replace(/^sudo\s+(?:-E\s+)?/, '')
+      .split(/\s+/);
+    const word = toks[0] || '';
+    const base = word.split('/').pop() || word;
+    if (/^git$/i.test(base)) {
+      const sub = toks.slice(1).find((t) => !t.startsWith('-')) || '';
+      if (!FALLBACK_GIT_READ_SUB_RE.test(sub)) return false;
+      if (fallbackGitStageWrites(stage)) return false;
+      continue;
+    }
+    if (!FALLBACK_LOCK_READ_VERB_RE.test(base)) return false;
+  }
+  return sawStage;
+}
+
 /** First matching dangerous signal for the WS2 fallback, or null (issue #59). */
-function fallbackDangerousMatch(args: Record<string, unknown> | undefined): string | null {
+function fallbackDangerousMatch(args: Record<string, unknown> | undefined, toolName?: string): string | null {
   const text = fallbackExecSurface(args);
   if (!text) return null;
-  for (const { re, signal } of FALLBACK_DANGEROUS_PATTERNS) {
+  const lockReadOnly = fallbackLockPathAccessIsReadOnly(text, toolName);
+  for (const { re, signal, lockPath } of FALLBACK_DANGEROUS_PATTERNS) {
+    if (lockReadOnly && lockPath === true) continue;
     if (re.test(text)) return signal;
   }
   return null;
@@ -615,10 +724,80 @@ export function summariseToolArgs(args: Record<string, unknown> | undefined): st
   return parts.join(' ').slice(0, 160);
 }
 
+/**
+ * #524 — the operator-facing half of the native `process` contract.
+ *
+ * DUPLICATED from `tool-action-guard.ts`'s `OPENCLAW_PROCESS_INSPECT` /
+ * `OPENCLAW_PROCESS_MUTATE` on purpose, the same discipline as
+ * `FALLBACK_CATASTROPHIC_PATTERNS` above: this file carries no compile-time
+ * dependency on the main package, and the card must still read in English when
+ * the guard is loaded through the injected-evaluator seam. Kept in sync there;
+ * a verb that drifts out of sync falls back to the generic lead below rather
+ * than inventing a sentence.
+ */
+const NATIVE_PROCESS_PHRASE: Record<string, string> = {
+  list: 'see what commands are running',
+  poll: 'check a running command',
+  log: "read a running command's output",
+  kill: 'stop a running command',
+  write: 'type into a running command',
+  'send-keys': 'press keys in a running command',
+  submit: 'submit input to a running command',
+  paste: 'paste text into a running command',
+  clear: "clear a running command's input",
+  remove: "remove a running command's session",
+};
+
+/** EXACT native spelling only — `mcp__openclaw__process` is not this contract. */
+function isNativeProcessTool(toolName: string): boolean {
+  return String(toolName || '').trim().toLowerCase() === 'process';
+}
+
+/**
+ * The plain sentence the card LEADS with.
+ *
+ * The operator's complaint was not that the card was wrong, it was that
+ * `invalid_tool_input / unknown field action` is not a question a person can
+ * answer. So the headline is what the agent is trying to do, in words, and the
+ * `Tool:`/`Action:`/`Signals:` block below it keeps the machine-readable
+ * detail — including for the secret-egress filter in `index.ts`, which forwards
+ * those label lines and drops everything else.
+ *
+ * Every sentence says what allow-once buys, because that is the other half of
+ * what went wrong: a Telegram allow-once looked like it taught the tool, and it
+ * did not. It never will — no card mints a standing grant.
+ */
+function actionGuardLead(
+  toolName: string,
+  v: ToolGuardVerdictLike,
+  args?: Record<string, unknown>,
+): string {
+  const rawAction = args?.action;
+  const verb = typeof rawAction === 'string'
+    ? rawAction.trim().toLowerCase().replace(/_/g, '-')
+    : '';
+  const phrase = isNativeProcessTool(toolName) ? NATIVE_PROCESS_PHRASE[verb] : undefined;
+  if (phrase) {
+    return `Jarvis wants to ${phrase} (${verb}). Allow once is this call only.`;
+  }
+  if (isSchemaInvalid(v)) {
+    return `Jarvis used ${toolName}, which ShieldCortex does not fully recognise yet. `
+      + 'Allow once lets this one call through. It does not teach the tool.';
+  }
+  return `Jarvis wants to use ${toolName}, and ShieldCortex rated this call ${v.severity}. `
+    + 'Allow once is this call only.';
+}
+
 /** Operator-facing approval prompt for a gated action (not a memory write). */
-export function formatActionGuardPrompt(toolName: string, v: ToolGuardVerdictLike): string {
+export function formatActionGuardPrompt(
+  toolName: string,
+  v: ToolGuardVerdictLike,
+  args?: Record<string, unknown>,
+): string {
   return [
-    '🛡️ ShieldCortex — Action Intercepted',
+    '🛡️ ShieldCortex needs a yes',
+    '',
+    actionGuardLead(toolName, v, args),
     '',
     `Tool:       ${toolName}`,
     `Action:     ${v.action}`,
@@ -626,7 +805,7 @@ export function formatActionGuardPrompt(toolName: string, v: ToolGuardVerdictLik
     `Signals:    ${v.signals.join(', ') || 'none'}`,
     `Reason:     ${v.reason}`,
     '',
-    '[Approve]  [Deny]',
+    '[Allow once]  [Deny]',
   ].join('\n');
 }
 
@@ -1215,7 +1394,7 @@ export function createInterceptor(
 
     // 2. Dangerous — route through failurePolicy (the "can't obtain a verdict"
     //    policy; a degraded guard is precisely that). enforce:false → advisory.
-    const dangerousSignal = fallbackDangerousMatch(context.arguments);
+    const dangerousSignal = fallbackDangerousMatch(context.arguments, context.toolName);
     if (dangerousSignal) {
       const dBase = { ...degradedBase, severity: 'high' as Severity, threats: ['fallback-scan', dangerousSignal], anomalyScore: 0.6 };
       if (!actionGuardCfg.enforce) {
@@ -1223,7 +1402,15 @@ export function createInterceptor(
         log.warn(`[shieldcortex] ⚠️ action-guard unavailable (${reason}) — advisory (enforce:false), allowing dangerous ${context.toolName} [${dangerousSignal}]`);
         return;
       }
-      const failAction = config.failurePolicy.high;
+      // #522 G3: only an explicit, recognised `allow` permits a dangerous op
+      // through a degraded guard. `failurePolicy` arrives from config files
+      // including the unsigned same-UID `openclaw.json`, and the old
+      // `=== 'deny'` test made every OTHER value — a typo, a null, an object,
+      // anything a schema did not catch — fail OPEN on the one tier this
+      // branch exists to hold. On a locked host the value is pinned to `deny`
+      // upstream by the policy lock (`withGuardPosture`); this is the floor
+      // for the value that actually arrives.
+      const failAction: FailureAction = config.failurePolicy.high === 'allow' ? 'allow' : 'deny';
       emitAudit({ ...dBase, action: 'gate_degraded', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
       if (failAction === 'deny') {
         log.warn(`[shieldcortex] action-guard UNAVAILABLE (${reason}) and fallback matched a DANGEROUS op [${dangerousSignal}] — DENYING ${context.toolName} (fail-closed, failure policy: deny)`);
@@ -1503,7 +1690,7 @@ export function createInterceptor(
     let approved: boolean;
     try {
       approved = await withApprovalDeadline(
-        context.requireApproval(formatActionGuardPrompt(context.toolName, v)),
+        context.requireApproval(formatActionGuardPrompt(context.toolName, v, context.arguments)),
         brokered ? brokerApprovalTimeoutMs(v.severity) : 0,
       );
     } catch (err) {

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "5.0.4",
+  "version": "5.0.6",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",