@upx-us/shield 0.2.16-beta → 0.3.5

package/dist/src/transformer.js

@@ -1,12 +1,4 @@
 "use strict";
-/**
- * transformer.ts — Thin orchestration layer
- *
- * Iterates raw JSONL entries, routes each tool call to the matching schema,
- * and wraps the resulting ShieldEvent in an EnvelopeEvent for transmission.
- *
- * All enrichment logic lives in src/events/{type}/enrich.ts.
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -43,17 +35,17 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOpenClawVersion = resolveOpenClawVersion;
 exports.resolveAgentLabel = resolveAgentLabel;
+exports.resolveOutboundIp = resolveOutboundIp;
 exports.transformEntries = transformEntries;
 exports.generateHostTelemetry = generateHostTelemetry;
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const https = __importStar(require("https"));
+const dgram_1 = require("dgram");
 const events_1 = require("./events");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
-// ─── OpenClaw info resolution ─────────────────────────────────────────────────
-/** Resolve the installed OpenClaw version from known package.json paths. */
+const counters_1 = require("./counters");
 function resolveOpenClawVersion() {
     if (process.env.OPENCLAW_VERSION)
         return process.env.OPENCLAW_VERSION;
@@ -70,9 +62,8 @@ function resolveOpenClawVersion() {
                     return pkg.version;
             }
         }
-        catch { /* skip */ }
+        catch { }
     }
-    // Fallback: read lastTouchedVersion from openclaw.json
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.openclaw/openclaw.json'), 'utf8'));
         return cfg?.meta?.lastTouchedVersion || 'unknown';
@@ -81,7 +72,6 @@ function resolveOpenClawVersion() {
         return 'unknown';
     }
 }
-/** Resolve agent_label from IDENTITY.md in the configured workspace. */
 function resolveAgentLabel(agentId) {
     if (process.env.OPENCLAW_AGENT_LABEL)
         return process.env.OPENCLAW_AGENT_LABEL;
@@ -97,44 +87,86 @@ function resolveAgentLabel(agentId) {
                 return match[1].trim();
         }
     }
-    catch { /* skip */ }
+    catch { }
     return agentId;
 }
-/** Fetch the public (egress) IP from ipify.org — resolves once at startup. */
-function fetchPublicIp() {
+const IP_CACHE_FILE = path.join(os.homedir(), '.openclaw', 'shield', 'data', 'public-ip.cache');
+const IP_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+function readIpCache() {
+    try {
+        if (!fs.existsSync(IP_CACHE_FILE))
+            return null;
+        const data = JSON.parse(fs.readFileSync(IP_CACHE_FILE, 'utf8'));
+        if (!data.ip || !data.resolvedAt)
+            return null;
+        if (Date.now() - data.resolvedAt > IP_CACHE_TTL_MS)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function writeIpCache(ip) {
+    try {
+        const dir = path.dirname(IP_CACHE_FILE);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(IP_CACHE_FILE, JSON.stringify({ ip, resolvedAt: Date.now() }));
+    }
+    catch { }
+}
+function resolveOutboundIp() {
     return new Promise((resolve) => {
-        const req = https.get('https://api.ipify.org?format=json', { timeout: 5000 }, (res) => {
-            let data = '';
-            res.on('data', (chunk) => { data += chunk; });
-            res.on('end', () => {
+        try {
+            const socket = (0, dgram_1.createSocket)('udp4');
+            socket.connect(53, '8.8.8.8', () => {
                 try {
-                    resolve(JSON.parse(data).ip || null);
+                    const addr = socket.address();
+                    const ip = typeof addr === 'object' ? addr.address : null;
+                    socket.close();
+                    resolve(ip || null);
                 }
                 catch {
+                    socket.close();
                     resolve(null);
                 }
             });
-        });
-        req.on('error', () => resolve(null));
-        req.on('timeout', () => { req.destroy(); resolve(null); });
+            socket.on('error', () => {
+                try {
+                    socket.close();
+                }
+                catch { }
+                resolve(null);
+            });
+        }
+        catch {
+            resolve(null);
+        }
     });
 }
-// ─── Source Info (cached, async-enriched) ────────────────────────────────────
 let _source = null;
-/** Kick off public IP resolution at module load (non-blocking). */
-function initPublicIp() {
-    fetchPublicIp().then((ip) => {
-        if (ip && _source) {
-            // Inject public IP as first entry so SIEM sees it
-            const alreadyHas = _source.ip_addresses.includes(ip);
-            if (!alreadyHas)
-                _source.ip_addresses = [ip, ..._source.ip_addresses];
-            log.info('transformer', `Public IP resolved: ${ip}`);
+function initOutboundIp() {
+    const cached = readIpCache();
+    if (cached) {
+        log.info('transformer', `Outbound IP loaded from cache: ${cached.ip}`);
+        injectIp(cached.ip);
+        return;
+    }
+    resolveOutboundIp().then((ip) => {
+        if (ip) {
+            writeIpCache(ip);
+            injectIp(ip);
+            log.info('transformer', `Outbound IP resolved: ${ip}`);
         }
-        return ip;
     });
 }
-initPublicIp();
+function injectIp(ip) {
+    if (_source && !_source.ip_addresses.includes(ip)) {
+        _source.ip_addresses = [ip, ..._source.ip_addresses];
+    }
+}
+initOutboundIp();
 function getSourceInfo() {
     if (_source)
         return _source;
@@ -160,8 +192,6 @@ function getSourceInfo() {
     };
     return _source;
 }
-// ─── Administrative Detection ─────────────────────────────────────────────────
-/** Detect if an event is administrative Shield activity (prevents meta-detection) */
 function isAdministrativeEvent(toolName, args, sessionId) {
     if (sessionId && /subagent/i.test(sessionId))
         return true;
@@ -191,7 +221,6 @@ function isAdministrativeEvent(toolName, args, sessionId) {
         return true;
     return false;
 }
-// ─── Main Transform ───────────────────────────────────────────────────────────
 function transformEntries(entries) {
     const baseSource = getSourceInfo();
     const envelopes = [];
@@ -202,7 +231,6 @@ function transformEntries(entries) {
             ...baseSource,
             openclaw: { ...baseSource.openclaw, agent_id: agentId },
         };
-        // ── TOOL_CALL ──
         if (msg.role === 'assistant' && Array.isArray(msg.content)) {
             const model = msg.model ? `${msg.provider || ''}/${msg.model}`.replace(/^\//, '') : '';
             for (const item of msg.content) {
@@ -210,22 +238,20 @@ function transformEntries(entries) {
                     continue;
                 const toolName = item.name || 'unknown';
                 const args = item.arguments || {};
-                // Route to matching schema (first match wins; GenericSchema is last fallback)
                 const schema = events_1.schemas.find(s => s.match({ name: toolName, id: item.id, arguments: args }));
                 if (!schema)
-                    continue; // should never happen since GenericSchema matches everything
+                    continue;
                 const event = schema.enrich({ name: toolName, id: item.id, arguments: args }, { sessionId: entry._sessionId, agentId, timestamp: entry.timestamp, model, source });
-                // Inject administrative flag post-enrichment (cross-cutting concern)
                 if (isAdministrativeEvent(toolName, args, entry._sessionId)) {
                     if (!event.tool_metadata)
                         event.tool_metadata = {};
                     event.tool_metadata['openclaw.is_administrative'] = 'true';
                 }
                 log.debug('transformer', `TOOL_CALL tool=${toolName} session=${entry._sessionId} agent=${agentId} schema=${schema.constructor?.name || 'unknown'} admin=${event.tool_metadata?.['openclaw.is_administrative'] === 'true'}`, log.isDebug ? event : undefined);
+                (0, counters_1.recordEventType)(event.event_type);
                 envelopes.push({ source, event });
             }
         }
-        // ── TOOL_RESULT ──
         else if (msg.role === 'toolResult') {
             const event = (0, events_1.buildToolResult)({ toolName: msg.toolName, content: msg.content, details: msg.details }, { sessionId: entry._sessionId, agentId, timestamp: entry.timestamp, source });
             if (isAdministrativeEvent(event.tool_name, {}, entry._sessionId)) {
@@ -234,14 +260,13 @@ function transformEntries(entries) {
                 event.tool_metadata['openclaw.is_administrative'] = 'true';
             }
             log.debug('transformer', `TOOL_RESULT tool=${event.tool_name} session=${entry._sessionId} agent=${agentId}`, log.isDebug ? event : undefined);
+            (0, counters_1.recordEventType)(event.event_type);
             envelopes.push({ source, event });
         }
     }
     log.info('transformer', `${envelopes.length} envelopes from ${entries.length} entries`);
     return envelopes;
 }
-// ─── Host Telemetry ───────────────────────────────────────────────────────────
-/** Generate a HOST_TELEMETRY envelope with version + config info for security rules */
 function generateHostTelemetry() {
     const source = getSourceInfo();
     const version = source.openclaw.version;
@@ -271,7 +296,7 @@ function generateHostTelemetry() {
             }
         }
     }
-    catch { /* default values */ }
+    catch { }
     const event = {
         timestamp: new Date().toISOString(),
         event_type: 'TOOL_CALL',

package/dist/src/validator.d.ts

@@ -1,16 +1,5 @@
-/**
- * validator.ts — Event validation with quarantine
- *
- * Validates events using the schema registry. Events that fail validation are
- * written to a local quarantine file and never enter the redaction/send path.
- * This is the tamper-prevention gate — malformed or unexpected events don't leave the machine.
- */
 import type { ShieldEvent } from './events';
 export declare const QUARANTINE_FILE: string;
-/**
- * Validate a batch of events.
- * Returns the valid events and the count of quarantined ones.
- */
 export declare function validate(events: ShieldEvent[]): {
     valid: ShieldEvent[];
     quarantined: number;

package/dist/src/validator.js

@@ -1,11 +1,4 @@
 "use strict";
-/**
- * validator.ts — Event validation with quarantine
- *
- * Validates events using the schema registry. Events that fail validation are
- * written to a local quarantine file and never enter the redaction/send path.
- * This is the tamper-prevention gate — malformed or unexpected events don't leave the machine.
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -53,41 +46,36 @@ exports.QUARANTINE_FILE = path.join(SHIELD_DATA_DIR, 'quarantine.jsonl');
 function ensureDataDir() {
     fs.mkdirSync(SHIELD_DATA_DIR, { recursive: true });
 }
-function appendQuarantine(event, error, field) {
+function flushQuarantineBuffer(buffer) {
+    if (buffer.length === 0)
+        return;
     try {
         ensureDataDir();
-        const record = JSON.stringify({
-            quarantined_at: new Date().toISOString(),
-            validation_error: error,
-            validation_field: field || null,
-            event,
-        });
-        fs.appendFileSync(exports.QUARANTINE_FILE, record + '\n');
+        fs.appendFileSync(exports.QUARANTINE_FILE, buffer.join(''));
     }
     catch (e) {
-        // Quarantine write failure is non-fatal
-        console.error('[validator] Failed to write quarantine record:', e);
+        console.error('[validator] Failed to write quarantine records:', e);
     }
 }
-/**
- * Validate a batch of events.
- * Returns the valid events and the count of quarantined ones.
- */
 function validate(events) {
     const valid = [];
+    const quarantineBuffer = [];
     let quarantined = 0;
     for (const event of events) {
-        // Find the matching schema by tool_category
         const schema = events_1.schemas.find(s => s.category === event.tool_category);
         if (!schema) {
-            // No schema found — run base validations only and pass through
             const baseResult = base_1.baseValidations.validate(event);
             if (baseResult.valid) {
                 valid.push(event);
             }
             else {
                 quarantined++;
-                appendQuarantine(event, baseResult.error || 'validation_failed', baseResult.field);
+                quarantineBuffer.push(JSON.stringify({
+                    quarantined_at: new Date().toISOString(),
+                    validation_error: baseResult.error || 'validation_failed',
+                    validation_field: baseResult.field || null,
+                    event,
+                }) + '\n');
             }
             continue;
         }
@@ -98,11 +86,17 @@ function validate(events) {
         }
         else {
             quarantined++;
-            appendQuarantine(event, result.error || 'validation_failed', result.field);
+            quarantineBuffer.push(JSON.stringify({
+                quarantined_at: new Date().toISOString(),
+                validation_error: result.error || 'validation_failed',
+                validation_field: result.field || null,
+                event,
+            }) + '\n');
             log.warn('validator', `QUARANTINE tool=${event.tool_name} field=${result.field} error=${result.error}`);
             log.debug('validator', 'quarantined event', event);
         }
     }
+    flushQuarantineBuffer(quarantineBuffer);
     if (quarantined > 0 || log.isDebug) {
         log.info('validator', `${valid.length} valid, ${quarantined} quarantined`);
     }

package/dist/src/version.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
-// Works from both src/ (dev) and dist/src/ (compiled)
 function loadVersion() {
     for (const rel of ['../package.json', '../../package.json']) {
         const p = (0, path_1.join)(__dirname, rel);
@@ -11,7 +10,7 @@ function loadVersion() {
             try {
                 return JSON.parse((0, fs_1.readFileSync)(p, 'utf-8')).version ?? '0.0.0';
             }
-            catch { /* next */ }
+            catch { }
         }
     }
     return '0.0.0';

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "shield",
   "name": "OpenClaw Shield",
-  "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.2.16-beta",
+  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.3.5",
   "skills": [
     "./skills"
   ],
@@ -10,6 +10,10 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
+      "installationKey": {
+        "type": "string",
+        "description": "One-time installation key from the Shield portal. The plugin uses this to register the instance and obtain credentials automatically. Can be removed from config after first activation."
+      },
       "enabled": {
         "type": "boolean",
         "default": true
@@ -33,6 +37,10 @@
     }
   },
   "uiHints": {
+    "installationKey": {
+      "label": "Installation Key",
+      "description": "One-time key from the Shield portal (https://uss.upx.com). Required for first-time activation only."
+    },
     "enabled": {
       "label": "Enable security monitoring"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.2.16-beta",
+  "version": "0.3.5",
   "description": "Security monitoring plugin for OpenClaw agents — streams enriched security events to the Shield detection platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
-    "dist/src/",
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
     "openclaw.plugin.json",
     "skills/",
     "README.md",
@@ -32,7 +33,7 @@
     "dev": "tsx scripts/dev-harness.ts",
     "dev:dry": "tsx scripts/dev-harness.ts --dry-run",
     "generate:schemas": "tsx scripts/generate-schemas.ts",
-    "prepublishOnly": "npm run prepublish:check && npm run build && npm run generate:schemas",
+    "prepublishOnly": "npm run build && npm run generate:schemas && npm run prepublish:check",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "prepublish:check": "node scripts/prepublish-check.js"
   },
@@ -47,6 +48,10 @@
   ],
   "author": "UPX Security Services",
   "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "tag": "latest",
+    "access": "public"
+  },
   "engines": {
     "node": ">=20.0.0"
   },

package/dist/src/host-collector.d.ts

@@ -1 +0,0 @@
-export declare function collectHostMetrics(): Promise<any[]>;

package/dist/src/host-collector.js

@@ -1,200 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectHostMetrics = collectHostMetrics;
-const child_process_1 = require("child_process");
-const os = __importStar(require("os"));
-function run(cmd) {
-    try {
-        return (0, child_process_1.execSync)(cmd, { timeout: 10000, encoding: 'utf-8' }).trim();
-    }
-    catch {
-        return '';
-    }
-}
-async function collectCpu() {
-    try {
-        const top = run('top -l 1 -n 0');
-        const m = top.match(/CPU usage:\s+([\d.]+)%\s+user,\s+([\d.]+)%\s+sys,\s+([\d.]+)%\s+idle/);
-        const idle = m ? parseFloat(m[3]) : null;
-        const usage = idle !== null ? Math.round((100 - idle) * 100) / 100 : null;
-        const loads = os.loadavg();
-        return {
-            usage,
-            load1: Math.round(loads[0] * 100) / 100,
-            load5: Math.round(loads[1] * 100) / 100,
-            load15: Math.round(loads[2] * 100) / 100,
-        };
-    }
-    catch {
-        return { usage: null, load1: null, load5: null, load15: null };
-    }
-}
-async function collectMemory() {
-    try {
-        const totalBytes = os.totalmem();
-        const freeBytes = os.freemem();
-        const totalMb = Math.round(totalBytes / 1024 / 1024);
-        const usedMb = Math.round((totalBytes - freeBytes) / 1024 / 1024);
-        const usagePercent = Math.round((usedMb / totalMb) * 10000) / 100;
-        return { totalMb, usedMb, usagePercent };
-    }
-    catch {
-        return { totalMb: null, usedMb: null, usagePercent: null };
-    }
-}
-async function collectDisk() {
-    try {
-        const df = run('df -g /');
-        const lines = df.split('\n');
-        if (lines.length < 2)
-            return { totalGb: null, usedGb: null, usagePercent: null };
-        const parts = lines[1].split(/\s+/);
-        const totalGb = parseInt(parts[1]);
-        const usedGb = parseInt(parts[2]);
-        const usagePercent = Math.round((usedGb / totalGb) * 10000) / 100;
-        return { totalGb, usedGb, usagePercent };
-    }
-    catch {
-        return { totalGb: null, usedGb: null, usagePercent: null };
-    }
-}
-async function collectUptime() {
-    try {
-        return Math.round(os.uptime());
-    }
-    catch {
-        return null;
-    }
-}
-async function collectNetwork() {
-    try {
-        const connCount = parseInt(run("netstat -an | grep ESTABLISHED | wc -l").trim()) || 0;
-        const lsof = run("lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null");
-        const ports = new Set();
-        for (const line of lsof.split('\n').slice(1)) {
-            const m = line.match(/:(\d+)\s/);
-            if (m)
-                ports.add(m[1]);
-        }
-        return {
-            connections: connCount,
-            listeningPorts: ports.size > 0 ? Array.from(ports).sort((a, b) => parseInt(a) - parseInt(b)).join(',') : null,
-        };
-    }
-    catch {
-        return { connections: null, listeningPorts: null };
-    }
-}
-async function collectTopProcesses() {
-    try {
-        const ps = run("ps aux -r | head -6");
-        const lines = ps.split('\n').slice(1); // skip header
-        const procs = lines.map(l => {
-            const parts = l.split(/\s+/);
-            return `${parts[10] || parts[parts.length - 1]}(${parts[2]}%)`;
-        });
-        return procs.join(', ') || null;
-    }
-    catch {
-        return null;
-    }
-}
-async function collectOpenClawStatus() {
-    try {
-        const out = run("pgrep -f 'openclaw' | wc -l");
-        const count = parseInt(out.trim()) || 0;
-        return {
-            status: count > 0 ? 'running' : 'stopped',
-            sessions: null, // would need API access
-        };
-    }
-    catch {
-        return { status: null, sessions: null };
-    }
-}
-async function collectHostMetrics() {
-    const cpu = await collectCpu();
-    const mem = await collectMemory();
-    const disk = await collectDisk();
-    const uptimeSec = await collectUptime();
-    const net = await collectNetwork();
-    const procs = await collectTopProcesses();
-    const oc = await collectOpenClawStatus();
-    const anomalies = [];
-    if (cpu.usage !== null && cpu.usage > 90)
-        anomalies.push(`CPU=${cpu.usage}%`);
-    if (mem.usagePercent !== null && mem.usagePercent > 90)
-        anomalies.push(`Memory=${mem.usagePercent}%`);
-    if (disk.usagePercent !== null && disk.usagePercent > 90)
-        anomalies.push(`Disk=${disk.usagePercent}%`);
-    const event = {
-        timestamp: new Date().toISOString(),
-        event_type: 'TOOL_CALL',
-        tool_name: 'host_telemetry',
-        session_id: 'host-monitor',
-        model: '',
-        hostname: os.hostname(),
-        product_name: 'OpenClaw',
-        vendor_name: 'UPX',
-        event_category: 'HOST_METRIC',
-        metric_type: 'system_snapshot',
-        cpu_usage_percent: cpu.usage,
-        cpu_load_1m: cpu.load1,
-        cpu_load_5m: cpu.load5,
-        cpu_load_15m: cpu.load15,
-        memory_total_mb: mem.totalMb,
-        memory_used_mb: mem.usedMb,
-        memory_usage_percent: mem.usagePercent,
-        disk_total_gb: disk.totalGb,
-        disk_used_gb: disk.usedGb,
-        disk_usage_percent: disk.usagePercent,
-        uptime_seconds: uptimeSec,
-        network_connections_count: net.connections,
-        network_listening_ports: net.listeningPorts,
-        top_processes: procs,
-        openclaw_gateway_status: oc.status,
-        openclaw_active_sessions: oc.sessions,
-        os_name: os.platform(),
-        os_version: os.release(),
-        arch: os.arch(),
-        tool_metadata: {
-            collection_method: 'shell_exec',
-            is_anomaly: anomalies.length > 0,
-            anomaly_details: anomalies.length > 0 ? anomalies.join('; ') : null,
-        },
-    };
-    return [event];
-}

package/skills/shield/SKILL.md

@@ -1,38 +0,0 @@
----
-name: shield
-description: OpenClaw Shield security monitoring plugin — check status, manage configuration, and review security event activity.
-metadata: {"openclaw": {"requires": {"env": []}, "emoji": "🛡️", "os": ["darwin", "linux", "windows"]}}
----
-
-OpenClaw Shield monitors this agent's activity and streams security events to the Shield detection platform for threat detection and compliance.
-
-## Check status
-
-```bash
-openclaw shield status
-```
-
-Shows: running state, last poll time, events processed, quarantine count, failure count, version.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `openclaw shield status` | Show monitoring status |
-| `openclaw shield flush` | Force an immediate sync |
-
-## First-time setup
-
-If Shield is not yet activated, run:
-
-```bash
-npx -p @upx-us/shield@beta shield-setup
-```
-
-The wizard will ask for an **installation key** (provided by your Shield administrator). It registers the instance and saves credentials locally. Restart the Gateway when done.
-
-## Troubleshooting
-
-- **Not running**: check `openclaw shield status` for failure count and last poll time
-- **High failure count**: Shield backs off automatically; run `openclaw shield flush` to retry immediately
-- **Setup required**: if credentials are missing, re-run `npx -p @upx-us/shield@beta shield-setup` with a valid installation key