shieldcortex 4.0.0 → 4.0.1

package/dist/audit/memory-scanner.js

@@ -12,6 +12,21 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { runDefencePipeline } from '../defence/pipeline.js';
 const LEARN_MORE = 'https://shieldcortex.ai/docs/threats/memory-poisoning';
+// ── ShieldCortex Own-Hook Whitelist ──
+/**
+ * Paths belonging to ShieldCortex itself (hooks, plugin manifests, etc.).
+ * These should never produce false audit findings (#14).
+ */
+const SHIELDCORTEX_OWN_PATHS = [
+    'cortex-memory/HOOK.md',
+    'cortex-memory/handler.ts',
+    'cortex-memory/handler.js',
+    'shieldcortex-realtime',
+];
+function isShieldCortexOwnPath(filePath) {
+    const normalised = filePath.replace(/\\/g, '/');
+    return SHIELDCORTEX_OWN_PATHS.some(p => normalised.includes(p));
+}
 /** Maximum file size to scan (1 MB) */
 const MAX_FILE_SIZE = 1024 * 1024;
 /** Maximum number of memory files to scan */
@@ -193,6 +208,9 @@ export function scanMemories() {
     }
     const allFindings = [];
     for (const file of files) {
+        // Skip ShieldCortex's own hook/plugin files to avoid false positives (#14)
+        if (isShieldCortexOwnPath(file))
+            continue;
         allFindings.push(...scanMemoryFile(file));
     }
     return {

package/dist/audit/rules-file-scanner.js

@@ -13,6 +13,26 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import { join, basename } from 'path';
 import { scanSkill, discoverSkillFiles } from '../defence/skill-scanner/index.js';
 const LEARN_MORE = 'https://shieldcortex.ai/docs/threats/rules-file-backdoor';
+// ── ShieldCortex Own-Hook Whitelist ──
+/**
+ * Paths belonging to ShieldCortex itself.
+ * These are legitimate hooks/plugins that should never be flagged by the
+ * audit scanner — doing so produces false HIGH/MEDIUM findings (#14).
+ */
+const SHIELDCORTEX_OWN_PATHS = [
+    'cortex-memory/HOOK.md',
+    'cortex-memory/handler.ts',
+    'cortex-memory/handler.js',
+    'shieldcortex-realtime',
+];
+/**
+ * Return true if this file belongs to ShieldCortex's own hook/plugin set
+ * and should be excluded from audit findings.
+ */
+function isShieldCortexOwnPath(filePath) {
+    const normalised = filePath.replace(/\\/g, '/');
+    return SHIELDCORTEX_OWN_PATHS.some(p => normalised.includes(p));
+}
 // ── Unicode Backdoor Detection ──
 /** Invisible Unicode characters used in the "Rules File Backdoor" attack. */
 const INVISIBLE_UNICODE = [
@@ -164,6 +184,9 @@ export function scanRulesFiles() {
     }
     const allFindings = [];
     for (const file of allFiles) {
+        // Skip ShieldCortex's own hook/plugin files to avoid false positives (#14)
+        if (isShieldCortexOwnPath(file))
+            continue;
         allFindings.push(...scanRulesFile(file));
     }
     return {

package/dist/index.js

@@ -538,7 +538,7 @@ ${bold}DOCS${reset}
     }
     // Handle "openclaw" subcommand (backward compat: "clawdbot" also accepted)
     if (process.argv[2] === 'openclaw' || process.argv[2] === 'clawdbot') {
-        await handleOpenClawCommand(process.argv[3] || '');
+        await handleOpenClawCommand(process.argv[3] || '', process.argv.slice(4));
         return;
     }
     // Handle "copilot" subcommand (VS Code + Cursor MCP setup)

package/dist/setup/openclaw.d.ts

@@ -5,6 +5,14 @@
  * the real-time plugin into the OpenClaw extensions directory.
  * Supports both Claude Code (native binary) and legacy OpenClaw (Node.js).
  */
+/**
+ * Detect whether ShieldCortex is running inside a Docker container
+ * or similar isolated environment (Umbrel, Unraid, NixOS sandbox, etc.).
+ *
+ * In these environments, OpenClaw hook/plugin installation may crash or
+ * produce broken state. We warn and skip by default.
+ */
+export declare function isDockerEnvironment(): boolean;
 /**
  * Find ALL valid hook directories for install/uninstall/status.
  *
@@ -12,7 +20,16 @@
  * Creates the hooks/ subdirectory if the parent config dir exists.
  */
 export declare function findAllHooksDirs(): string[];
-export declare function installOpenClawHook(): Promise<void>;
+/**
+ * Install options for `shieldcortex openclaw install`.
+ */
+export interface OpenClawInstallOptions {
+    /** Skip hook installation (--no-hooks flag) */
+    noHooks?: boolean;
+    /** Skip plugin installation (--no-plugins flag) */
+    noPlugins?: boolean;
+}
+export declare function installOpenClawHook(options?: OpenClawInstallOptions): Promise<void>;
 export declare function uninstallOpenClawHook(): Promise<void>;
 export declare function openClawHookStatus(): Promise<void>;
-export declare function handleOpenClawCommand(subcommand: string): Promise<void>;
+export declare function handleOpenClawCommand(subcommand: string, extraArgs?: string[]): Promise<void>;

package/dist/setup/openclaw.js

@@ -22,6 +22,35 @@ const PLUGIN_PACKAGE_SOURCE = path.resolve(__dirname, '..', '..', 'plugins', 'op
 const PLUGIN_DIR_NAME = 'shieldcortex-realtime';
 const HOOK_FILES = ['HOOK.md', 'handler.ts'];
 const OPENCLAW_SKIP_NATIVE_INSTALL_ENV = 'SHIELDCORTEX_SKIP_NATIVE_OPENCLAW_INSTALL';
+// ==================== Docker/Container Detection ====================
+/**
+ * Detect whether ShieldCortex is running inside a Docker container
+ * or similar isolated environment (Umbrel, Unraid, NixOS sandbox, etc.).
+ *
+ * In these environments, OpenClaw hook/plugin installation may crash or
+ * produce broken state. We warn and skip by default.
+ */
+export function isDockerEnvironment() {
+    // Standard Docker marker file
+    try {
+        if (fs.existsSync('/.dockerenv'))
+            return true;
+    }
+    catch { /* ignore */ }
+    // Explicit env overrides
+    if (process.env.DOCKER === 'true' || process.env.DOCKER === '1')
+        return true;
+    if (process.env.container === 'docker')
+        return true;
+    // /proc/1/cgroup contains "docker" or "kubepods" on containerised systems
+    try {
+        const cgroup = fs.readFileSync('/proc/1/cgroup', 'utf-8');
+        if (/docker|kubepods|containerd/i.test(cgroup))
+            return true;
+    }
+    catch { /* not Linux or not accessible */ }
+    return false;
+}
 /**
  * Resolve the real user's home directory.
  *
@@ -373,7 +402,27 @@ function isPluginInLoadPaths() {
         return false;
     }
 }
-function installPlugin() {
+/**
+ * Install the real-time plugin.
+ * In Docker environments, skip with a warning — plugin install can crash
+ * the gateway in containers where filesystem permissions differ.
+ *
+ * @param options.noPlugins  Skip plugin installation entirely (--no-plugins flag)
+ */
+function installPlugin(options = {}) {
+    if (options.noPlugins) {
+        console.log('  Skipping plugin install (--no-plugins flag).');
+        return 'skipped';
+    }
+    // Docker / container environments: warn and skip
+    if (isDockerEnvironment()) {
+        console.warn('  ⚠  Docker/container environment detected.');
+        console.warn('  Skipping real-time plugin install to avoid gateway crash.');
+        console.warn('  To install manually after confirming OpenClaw support:');
+        console.warn('    DOCKER=false shieldcortex openclaw install');
+        console.warn('  Or suppress this warning: shieldcortex openclaw install --no-plugins');
+        return 'skipped';
+    }
     const nativeInstall = tryNativeOpenClawPluginInstall();
     if (nativeInstall) {
         return nativeInstall;
@@ -481,7 +530,6 @@ function uninstallPlugin() {
     if (!extensionsDir)
         return false;
     const destDir = path.join(extensionsDir, PLUGIN_DIR_NAME);
-    const indexPath = path.join(destDir, 'index.js');
     if (!fs.existsSync(destDir))
         return false;
     try {
@@ -543,8 +591,7 @@ function localPluginTrustStatus(pluginPath) {
         return 'unknown';
     }
 }
-// ==================== Commands ====================
-export async function installOpenClawHook() {
+export async function installOpenClawHook(options = {}) {
     const hooksDirs = findAllHooksDirs();
     if (hooksDirs.length === 0) {
         const home = resolveUserHome();
@@ -570,52 +617,76 @@ export async function installOpenClawHook() {
     }
     // Clean up legacy plugin entry that caused config validation errors
     cleanupLegacyPlugin();
-    // Install to ALL detected hook directories
+    // Docker / container: warn about environment
+    if (isDockerEnvironment()) {
+        console.warn('⚠  Docker/container environment detected.');
+        console.warn('   Hook and plugin installation may behave differently in containers.');
+        console.warn('   Use --no-plugins to skip plugin install, or --no-hooks to skip hooks.');
+        console.warn('');
+    }
     let installed = 0;
     let migratedLegacy = 0;
-    for (const hooksDir of hooksDirs) {
-        const destDir = preferredHookDir(hooksDir);
-        try {
-            const legacyDirsBeforeInstall = detectLegacyHookVariants(hooksDir);
-            copyHookFiles(HOOK_SOURCE, destDir);
-            console.log(`Installed cortex-memory hook to ${destDir}`);
-            if (legacyDirsBeforeInstall.length > 0) {
-                console.log(`Detected legacy OpenClaw hook layout in ${hooksDir} — migrating to ${destDir}`);
+    if (!options.noHooks) {
+        // Install to ALL detected hook directories
+        for (const hooksDir of hooksDirs) {
+            const destDir = preferredHookDir(hooksDir);
+            try {
+                const legacyDirsBeforeInstall = detectLegacyHookVariants(hooksDir);
+                copyHookFiles(HOOK_SOURCE, destDir);
+                console.log(`Installed cortex-memory hook to ${destDir}`);
+                if (legacyDirsBeforeInstall.length > 0) {
+                    console.log(`Detected legacy OpenClaw hook layout in ${hooksDir} — migrating to ${destDir}`);
+                }
+                for (const removedDir of removeLegacyHookVariants(hooksDir)) {
+                    console.log(`Removed legacy cortex-memory hook from ${removedDir}`);
+                    migratedLegacy++;
+                }
+                installed++;
             }
-            for (const removedDir of removeLegacyHookVariants(hooksDir)) {
-                console.log(`Removed legacy cortex-memory hook from ${removedDir}`);
-                migratedLegacy++;
+            catch (err) {
+                const code = err.code;
+                if (code === 'EACCES' || code === 'EPERM') {
+                    console.warn(`  Skipped ${destDir} (permission denied)`);
+                }
+                else {
+                    // Never throw — warn gracefully
+                    console.warn(`  Warning: Could not install hook to ${destDir}: ${err.message}`);
+                }
             }
-            installed++;
         }
-        catch (err) {
-            const code = err.code;
-            if (code === 'EACCES' || code === 'EPERM') {
-                console.warn(`  Skipped ${destDir} (permission denied)`);
-            }
-            else {
-                throw err;
-            }
+        if (installed === 0) {
+            console.warn('Could not install hooks to any directory (permission denied or error).');
+            console.log('Try one of these:');
+            console.log('  sudo "$(command -v shieldcortex)" openclaw install');
+            console.log('  sudo chown -R "$USER":"$USER" ~/.openclaw ~/.claude');
+            console.log('  shieldcortex openclaw install --no-hooks  # skip hook install');
+            // Do not exit(1) — allow plugin install to continue
         }
     }
-    if (installed === 0) {
-        console.error('Could not install to any hook directory (permission denied).');
-        console.log('Try one of these:');
-        console.log('  sudo "$(command -v shieldcortex)" openclaw install');
-        console.log('  sudo chown -R "$USER":"$USER" ~/.openclaw ~/.claude');
-        console.log('  shieldcortex openclaw install');
-        process.exit(1);
+    else {
+        console.log('Skipping hook installation (--no-hooks flag).');
+        installed = hooksDirs.length; // pretend success so plugin install proceeds
     }
     // Install the real-time plugin to the extensions directory
-    const pluginInstallMode = installPlugin();
+    const pluginInstallMode = installPlugin({ noPlugins: options.noPlugins });
     console.log('');
     if (migratedLegacy > 0) {
         console.log(`Legacy OpenClaw hook cleanup completed (${migratedLegacy} old path${migratedLegacy === 1 ? '' : 's'} removed).`);
         console.log('');
     }
     console.log('What was installed:');
-    console.log('  • cortex-memory hook (memory injection + "remember this:" trigger)');
-    console.log('    Auto-save is optional: shieldcortex config --openclaw-auto-memory true');
+    if (!options.noHooks) {
+        if (installed > 0) {
+            console.log('  • cortex-memory hook (memory injection + "remember this:" trigger)');
+            console.log('    Auto-save is optional: shieldcortex config --openclaw-auto-memory true');
+        }
+        else {
+            console.log('  • cortex-memory hook: skipped (see warnings above)');
+        }
+    }
+    else {
+        console.log('  • cortex-memory hook: skipped (--no-hooks)');
+    }
     if (pluginInstallMode !== 'skipped') {
         console.log('  • shieldcortex-realtime plugin (real-time LLM input scanning + optional output extraction)');
         if (pluginInstallMode === 'native-package') {
@@ -631,6 +702,9 @@ export async function installOpenClawHook() {
             console.log('    Installed as a local fallback, but trust pinning failed.');
         }
     }
+    else {
+        console.log('  • shieldcortex-realtime plugin: skipped');
+    }
     console.log('');
     console.log('Native OpenClaw install is also supported:');
     console.log('  openclaw hooks install shieldcortex');
@@ -701,10 +775,12 @@ export async function openClawHookStatus() {
             : 'native or unknown trust source';
     console.log(`  Real-time plugin: installed (${plugin.path}) — ${trustSuffix}`);
 }
-export async function handleOpenClawCommand(subcommand) {
+export async function handleOpenClawCommand(subcommand, extraArgs = []) {
+    const noHooks = extraArgs.includes('--no-hooks');
+    const noPlugins = extraArgs.includes('--no-plugins');
     switch (subcommand) {
         case 'install':
-            await installOpenClawHook();
+            await installOpenClawHook({ noHooks, noPlugins });
             break;
         case 'uninstall':
             await uninstallOpenClawHook();
@@ -714,6 +790,10 @@ export async function handleOpenClawCommand(subcommand) {
             break;
         default:
             console.log('Usage: shieldcortex openclaw <install|uninstall|status>');
+            console.log('');
+            console.log('Install options:');
+            console.log('  --no-hooks     Skip hook installation (useful in Docker/CI)');
+            console.log('  --no-plugins   Skip plugin installation (useful in Docker/CI)');
             process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, Codex, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/postinstall.mjs

@@ -1,46 +1,144 @@
 #!/usr/bin/env node
 /**
  * Postinstall script - prints setup instructions after global install.
- * Does NOT auto-run setup (can fail in CI, user might not have Claude Code).
+ * Also detects existing OpenClaw installations and either auto-refreshes
+ * them or prints a clear upgrade warning (Bug #15 fix).
+ *
+ * Does NOT auto-run setup when:
+ *   - Running in CI
+ *   - SHIELDCORTEX_SKIP_AUTO_OPENCLAW=1 is set
+ *   - Running as a local/dev install (npm_config_global !== 'true')
  */
-import { existsSync } from 'fs';
+import { existsSync, copyFileSync, mkdirSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
-// Only show message for global installs (not local dev or CI)
 const isGlobal = process.env.npm_config_global === 'true';
 const isCI = process.env.CI === 'true' || process.env.CONTINUOUS_INTEGRATION === 'true';
 const skipAutoOpenClaw = process.env.SHIELDCORTEX_SKIP_AUTO_OPENCLAW === '1';
 
-function shouldRefreshOpenClaw() {
+/**
+ * Detect Docker/container environment — mirrors the logic in src/setup/openclaw.ts.
+ * Postinstall must not crash the gateway in Umbrel/Docker installs (#16).
+ */
+function isDockerEnvironment() {
+  try { if (existsSync('/.dockerenv')) return true; } catch { /* ignore */ }
+  if (process.env.DOCKER === 'true' || process.env.DOCKER === '1') return true;
+  if (process.env.container === 'docker') return true;
+  try {
+    const { readFileSync } = await import('fs').catch(() => ({ readFileSync: null }));
+    // Sync fallback — import() can't be used synchronously here
+  } catch { /* ignore */ }
+  return false;
+}
+
+/**
+ * Check whether OpenClaw is installed and whether ShieldCortex hooks/plugin exist.
+ */
+function getOpenClawState() {
   const home = homedir();
   const openclawDir = join(home, '.openclaw');
   const knownHook = join(openclawDir, 'hooks', 'cortex-memory');
   const knownPlugin = join(openclawDir, 'extensions', 'shieldcortex-realtime');
-  return existsSync(openclawDir) || existsSync(knownHook) || existsSync(knownPlugin);
+
+  return {
+    openclawInstalled: existsSync(openclawDir),
+    hookInstalled: existsSync(knownHook),
+    pluginInstalled: existsSync(knownPlugin),
+    pluginDir: knownPlugin,
+  };
 }
 
-function refreshOpenClawInstall() {
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = dirname(__filename);
-  const cliPath = join(__dirname, '..', 'dist', 'index.js');
+/**
+ * Auto-copy updated plugin files into the existing extensions directory.
+ * This ensures interceptor.js and other new files appear after upgrade (#15).
+ */
+function autoCopyPlugin(pluginDestDir, cliDistDir) {
+  if (!existsSync(pluginDestDir)) return false;
+
+  try {
+    // Source: plugins/openclaw/dist/ inside this package
+    const pluginSourceDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'plugins', 'openclaw', 'dist');
+    if (!existsSync(pluginSourceDir)) return false;
 
-  if (!existsSync(cliPath)) return;
+    let copied = 0;
+    const files = readdirSync(pluginSourceDir);
+    for (const file of files) {
+      const src = join(pluginSourceDir, file);
+      const dest = join(pluginDestDir, file);
+      try {
+        copyFileSync(src, dest);
+        copied++;
+      } catch {
+        // Non-fatal — individual file copy failure
+      }
+    }
+    return copied > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run `shieldcortex openclaw install` to refresh the full hook+plugin.
+ */
+function refreshOpenClawInstall(cliPath) {
+  if (!existsSync(cliPath)) return false;
   const result = spawnSync(process.execPath, [cliPath, 'openclaw', 'install'], {
     stdio: 'inherit',
     env: process.env,
   });
-  if (result.status !== 0) {
-    console.warn('[shieldcortex] OpenClaw auto-refresh skipped (non-fatal).');
-  }
+  return result.status === 0;
 }
 
+// ── Main postinstall logic ──
+
 if (isGlobal && !isCI) {
-  if (!skipAutoOpenClaw && shouldRefreshOpenClaw()) {
-    console.log('\n[shieldcortex] OpenClaw detected. Refreshing hook/plugin to latest version...');
-    refreshOpenClawInstall();
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const cliPath = join(__dirname, '..', 'dist', 'index.js');
+
+  const state = getOpenClawState();
+  const inDocker = isDockerEnvironment();
+
+  if (!skipAutoOpenClaw && state.openclawInstalled) {
+    if (inDocker) {
+      // Bug #16: Docker install — never auto-run, just warn
+      console.log('');
+      console.warn('[shieldcortex] ⚠  Docker/container environment detected.');
+      console.warn('[shieldcortex] Skipping automatic OpenClaw hook/plugin refresh.');
+      console.warn('[shieldcortex] To manually install after confirming OpenClaw support:');
+      console.warn('[shieldcortex]   shieldcortex openclaw install --no-plugins');
+    } else if (state.pluginInstalled) {
+      // Bug #15: Plugin exists from a previous install — auto-copy new files
+      console.log('');
+      console.log('[shieldcortex] Existing plugin detected. Copying updated plugin files...');
+      const copied = autoCopyPlugin(state.pluginDir, cliPath);
+      if (copied) {
+        console.log('[shieldcortex] Plugin files updated. Run full refresh for hook updates:');
+        console.log('[shieldcortex]   shieldcortex openclaw install');
+      } else {
+        // Fall back to full refresh
+        console.log('[shieldcortex] Auto-copy failed. Running full OpenClaw refresh...');
+        const ok = refreshOpenClawInstall(cliPath);
+        if (!ok) {
+          console.warn('[shieldcortex] ⚠  OpenClaw auto-refresh failed (non-fatal).');
+          console.warn('[shieldcortex] Run manually: shieldcortex openclaw install');
+        }
+      }
+    } else if (state.hookInstalled) {
+      // Hook exists but no plugin — run full refresh
+      console.log('');
+      console.log('[shieldcortex] OpenClaw hook detected. Refreshing to latest version...');
+      const ok = refreshOpenClawInstall(cliPath);
+      if (!ok) {
+        console.warn('[shieldcortex] ⚠  OpenClaw auto-refresh skipped (non-fatal).');
+        console.warn('[shieldcortex] Run manually: shieldcortex openclaw install');
+      }
+    }
+    // else: openclaw installed but no previous shieldcortex — don't auto-install; let user run setup
   }
 
   console.log('');