@upx-us/shield 0.2.12-beta

package/LICENSE

@@ -0,0 +1,38 @@
+Copyright (c) 2026 UPX Technologies, Inc. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of UPX Technologies, Inc. ("UPX").
+
+GRANT OF USE
+Subject to the terms of a valid, active subscription agreement with UPX for
+the OpenClaw Shield service, UPX grants you a limited, non-exclusive,
+non-transferable, non-sublicensable license to install and use the Software
+solely for the purpose of connecting to the OpenClaw Shield platform as part
+of your subscription.
+
+RESTRICTIONS
+You may not, and you may not permit others to:
+  - Copy, modify, adapt, translate, or create derivative works of the Software
+  - Distribute, transfer, sublicense, lease, lend, or rent the Software
+  - Reverse engineer, disassemble, or decompile the Software
+  - Remove or alter any proprietary notices, labels, or marks on the Software
+  - Use the Software without an active OpenClaw Shield subscription
+
+TERMINATION
+This license is effective until terminated. It will terminate automatically
+if you breach any term of this agreement or your subscription expires. Upon
+termination, you must destroy all copies of the Software in your possession.
+
+DISCLAIMER
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. UPX DISCLAIMS
+ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+IN NO EVENT SHALL UPX BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
+THE SOFTWARE OR ITS USE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+For licensing inquiries: legal@upx.com
+For support: https://upx.com

package/README.md

@@ -0,0 +1,96 @@
+# OpenClaw Shield
+
+> **This plugin requires an active OpenClaw Shield subscription provided by UPX.**
+> For more information, visit [upx.com](https://upx.com).
+
+Real-time security monitoring for your OpenClaw agents — powered by the UPX Shield detection platform.
+
+Shield runs silently alongside your OpenClaw Gateway, captures agent activity, and streams it to the Shield platform where security rules, playbooks, and case management give your team full visibility.
+
+📖 **New?** See the [Getting Started guide](https://github.com/UPX-US/openclaw-shield-plugin/blob/main/docs/GETTING_STARTED.md) for a step-by-step walkthrough.
+
+## Install
+
+```bash
+openclaw plugins install @upx-us/shield@beta
+```
+
+Restart the Gateway after install. Shield starts automatically.
+
+## Activate
+
+You'll need an **installation key** from your Shield admin. Run the setup wizard:
+
+```bash
+npx -p @upx-us/shield@beta shield-setup
+```
+
+```
+🛡️  OpenClaw Shield Setup
+==========================
+
+Installation Key (from Shield portal): ████████████████
+Connecting... ok
+Registering instance... ok
+
+✅ Shield activated!
+   Restart your OpenClaw Gateway to start monitoring.
+```
+
+That's it. Your instance is now registered and events will start flowing to the Shield platform.
+
+## What data is collected
+
+Shield captures **agent activity events** — the things your OpenClaw agent does:
+
+| Event type | Examples |
+|---|---|
+| Shell commands | `git status`, `npm install`, `curl` calls |
+| File operations | Read, write, edit — path and action only |
+| Web requests | URLs fetched, search queries, browser actions |
+| Messages sent | Channel, direction — never message content |
+| Sessions spawned | Sub-agent launches |
+
+Shield does **not** collect:
+- Message content or conversation history
+- File contents
+- Credentials or secrets (see Redaction below)
+- Anything outside of OpenClaw agent activity
+
+## How your data is protected
+
+**Redaction** runs locally before any data leaves your machine. The redactor automatically strips:
+
+- API keys, tokens, and passwords
+- File paths that look like sensitive locations (`~/.ssh`, credential files)
+- Usernames and hostnames from command output
+- Any string matching known secret patterns
+
+You can verify what's being sent at any time by running:
+
+```bash
+openclaw shield status
+```
+
+**Transmission** uses HTTPS with TLS 1.2+. Each instance has a unique signing key — your data is tied to your instance only and cannot be replayed or forged.
+
+**Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600 — readable only by your user). They are never transmitted.
+
+## Check status
+
+```bash
+openclaw shield status
+```
+
+```
+Shield v0.2.1-beta  (12s ago)
+  Running:    true
+  Last poll:  2026-02-22T22:40:31Z
+  Events:     1,204
+  Quarantine: 0
+  Failures:   0
+```
+
+## Need help?
+
+Contact your Shield administrator or reach out to UPX support.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenClaw Shield — Plugin Entry Point
+ *
+ * This file is the OpenClaw plugin entry point, declared in package.json
+ * under `openclaw.extensions`. It registers the Shield plugin with the
+ * OpenClaw Gateway and starts the monitoring bridge as a managed service.
+ *
+ * The monitoring bridge runs as a background service within the Gateway
+ * process, polling session files and forwarding enriched security events
+ * to the Shield detection platform.
+ *
+ * Dual-mode design:
+ *   - Plugin mode: this file, registered via api.registerService()
+ *   - Standalone mode: src/index.ts, runs directly via `shield-bridge`
+ */
+interface OpenClawPluginAPI {
+    config?: Record<string, unknown>;
+    logger: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+        debug(msg: string): void;
+    };
+    registerService(service: {
+        id: string;
+        start: () => void | Promise<void>;
+        stop: () => void | Promise<void>;
+    }): void;
+    registerGatewayMethod(method: string, handler: (ctx: {
+        respond: (ok: boolean, data: unknown) => void;
+    }) => void): void;
+    registerCli(setup: (ctx: {
+        program: any;
+    }) => void, opts?: {
+        commands: string[];
+    }): void;
+}
+declare const _default: {
+    id: string;
+    name: string;
+    register(api: OpenClawPluginAPI): void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,365 @@
+"use strict";
+/**
+ * OpenClaw Shield — Plugin Entry Point
+ *
+ * This file is the OpenClaw plugin entry point, declared in package.json
+ * under `openclaw.extensions`. It registers the Shield plugin with the
+ * OpenClaw Gateway and starts the monitoring bridge as a managed service.
+ *
+ * The monitoring bridge runs as a background service within the Gateway
+ * process, polling session files and forwarding enriched security events
+ * to the Shield detection platform.
+ *
+ * Dual-mode design:
+ *   - Plugin mode: this file, registered via api.registerService()
+ *   - Standalone mode: src/index.ts, runs directly via `shield-bridge`
+ */
+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 });
+const config_1 = require("./src/config");
+const log_1 = require("./src/log");
+const log = __importStar(require("./src/log"));
+const version_1 = require("./src/version");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+// ─── Persistent status file ──────────────────────────────────────────────────
+// Written by the daemon after each poll; read by the CLI status command.
+const STATUS_FILE = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data', 'status.json');
+function persistState(extra = {}) {
+    try {
+        const dir = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data');
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.writeFileSync)(STATUS_FILE, JSON.stringify({
+            ...state, ...extra,
+            version: version_1.VERSION,
+            updatedAt: Date.now(),
+            pid: process.pid,
+        }, null, 2));
+    }
+    catch { /* non-fatal */ }
+}
+function readPersistedState() {
+    try {
+        if (!(0, fs_1.existsSync)(STATUS_FILE))
+            return null;
+        const d = JSON.parse((0, fs_1.readFileSync)(STATUS_FILE, 'utf8'));
+        const age = Date.now() - (d.updatedAt || 0);
+        if (age > 10 * 60 * 1000)
+            return null; // stale if >10min
+        return d;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Bridge state — shared between service lifecycle, RPC, and CLI
+// ---------------------------------------------------------------------------
+const state = {
+    running: false,
+    lastPollAt: 0,
+    eventsProcessed: 0,
+    quarantineCount: 0,
+    consecutiveFailures: 0,
+};
+const MAX_BACKOFF_MS = 5 * 60 * 1000;
+const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
+function getBackoffInterval(baseMs) {
+    if (state.consecutiveFailures === 0)
+        return baseMs;
+    const backoff = baseMs * Math.pow(2, Math.min(state.consecutiveFailures, 10));
+    return Math.min(backoff, MAX_BACKOFF_MS);
+}
+// ---------------------------------------------------------------------------
+// Plugin export
+// ---------------------------------------------------------------------------
+exports.default = {
+    id: 'shield',
+    name: 'OpenClaw Shield',
+    register(api) {
+        // Wire up the Gateway logger as the log backend
+        const gatewayAdapter = {
+            debug(tag, msg, data) {
+                api.logger.debug(`[${tag}] ${msg}${data !== undefined ? ' ' + JSON.stringify(data) : ''}`);
+            },
+            info(tag, msg) { api.logger.info(`[${tag}] ${msg}`); },
+            warn(tag, msg) { api.logger.warn(`[${tag}] ${msg}`); },
+            error(tag, msg, err) {
+                api.logger.error(`[${tag}] ${msg}${err ? ' ' + String(err) : ''}`);
+            },
+        };
+        (0, log_1.setAdapter)(gatewayAdapter);
+        const pluginConfig = (api.config ?? {});
+        const enabled = pluginConfig.enabled !== false;
+        if (!enabled) {
+            log.info('shield', 'Monitoring disabled via config (enabled: false)');
+            return;
+        }
+        // Build credentials from plugin config + config.env fallback (no process.env mutation)
+        const credentials = (0, config_1.loadCredentialsFromPluginConfig)(pluginConfig);
+        if (!credentials.apiUrl || !credentials.hmacSecret) {
+            log.warn('shield', 'Not configured. Credentials can come from:');
+            log.warn('shield', '  1. Run setup wizard: npx shield-setup');
+            log.warn('shield', '  2. Set in plugins.entries.shield.config (openclaw.json)');
+            log.warn('shield', '  3. Set env vars: SHIELD_API_URL + SHIELD_HMAC_SECRET');
+            return;
+        }
+        const config = (0, config_1.loadConfig)({
+            credentials,
+            dryRun: typeof pluginConfig.dryRun === 'boolean' ? pluginConfig.dryRun : undefined,
+            redactionEnabled: typeof pluginConfig.redactionEnabled === 'boolean' ? pluginConfig.redactionEnabled : undefined,
+            pollIntervalMs: typeof pluginConfig.pollIntervalMs === 'number' ? pluginConfig.pollIntervalMs : undefined,
+            collectHostMetrics: typeof pluginConfig.collectHostMetrics === 'boolean' ? pluginConfig.collectHostMetrics : undefined,
+        });
+        log.info('shield', `Starting monitoring bridge v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
+        // -----------------------------------------------------------------------
+        // RPC methods
+        // -----------------------------------------------------------------------
+        let pollFn = null;
+        api.registerGatewayMethod('shield.status', ({ respond }) => {
+            respond(true, {
+                running: state.running,
+                lastPollAt: state.lastPollAt,
+                eventsProcessed: state.eventsProcessed,
+                quarantineCount: state.quarantineCount,
+                consecutiveFailures: state.consecutiveFailures,
+                version: version_1.VERSION,
+            });
+        });
+        api.registerGatewayMethod('shield.flush', ({ respond }) => {
+            if (!pollFn) {
+                respond(false, { error: 'Bridge not started' });
+                return;
+            }
+            pollFn()
+                .then(() => respond(true, { flushed: true }))
+                .catch((err) => respond(false, { error: err instanceof Error ? err.message : String(err) }));
+        });
+        // -----------------------------------------------------------------------
+        // CLI commands
+        // -----------------------------------------------------------------------
+        api.registerCli(({ program }) => {
+            const shield = program.command('shield');
+            shield.command('status')
+                .description('Show Shield monitoring status')
+                .action(async () => {
+                // Prefer persisted state written by the daemon; fall back to local state
+                const s = readPersistedState() ?? state;
+                const lastPoll = s.lastPollAt ? new Date(s.lastPollAt).toISOString() : 'never';
+                const updatedAt = s.updatedAt ? `  (${Math.round((Date.now() - s.updatedAt) / 1000)}s ago)` : '';
+                console.log(`Shield v${s.version ?? version_1.VERSION}${updatedAt}`);
+                console.log(`  Running:    ${s.running}`);
+                console.log(`  Last poll:  ${lastPoll}`);
+                console.log(`  Events:     ${s.eventsProcessed}`);
+                console.log(`  Quarantine: ${s.quarantineCount}`);
+                console.log(`  Failures:   ${s.consecutiveFailures}`);
+                if (s.pid)
+                    console.log(`  Daemon PID: ${s.pid}`);
+            });
+            shield.command('flush')
+                .description('Trigger an immediate poll cycle')
+                .action(async () => {
+                if (!pollFn) {
+                    console.error('Bridge not started');
+                    return;
+                }
+                console.log('Flushing...');
+                await pollFn();
+                console.log('Done');
+            });
+        }, { commands: ['shield'] });
+        // -----------------------------------------------------------------------
+        // Register background service
+        // -----------------------------------------------------------------------
+        let pollHandle = null;
+        let telemetryHandle = null;
+        api.registerService({
+            id: 'shield-monitor',
+            async start() {
+                const { fetchNewEntries, commitCursors } = await Promise.resolve().then(() => __importStar(require('./src/fetcher')));
+                const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = await Promise.resolve().then(() => __importStar(require('./src/transformer')));
+                const { sendEvents, reportInstance } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
+                const { init: initRedactor, flush: flushRedactor, redactEvent } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                const { validate } = await Promise.resolve().then(() => __importStar(require('./src/validator')));
+                if (config.redactionEnabled)
+                    initRedactor();
+                state.running = true;
+                persistState(); // mark daemon as running immediately
+                // -- Telemetry --------------------------------------------------
+                const runTelemetry = async () => {
+                    if (!state.running)
+                        return;
+                    if (config.collectHostMetrics) {
+                        const hostEvent = generateHostTelemetry();
+                        if (hostEvent) {
+                            const batch = config.redactionEnabled
+                                ? [redactEvent(hostEvent)]
+                                : [hostEvent];
+                            const results = await sendEvents(batch, config);
+                            const ok = results.every(r => r.success);
+                            log.info('shield', `Host telemetry → Chronicle: success=${ok}`);
+                        }
+                    }
+                    const instancePayload = {
+                        machine: {
+                            hostname: config.hostname,
+                            os: process.platform,
+                            arch: process.arch,
+                            node_version: process.version,
+                        },
+                        software: {
+                            plugin_version: version_1.VERSION,
+                            openclaw_version: resolveOpenClawVersion(),
+                            agent_label: resolveAgentLabel('main'),
+                        },
+                    };
+                    const ok = await reportInstance(instancePayload, config.credentials);
+                    log.info('shield', `Instance report → Platform: success=${ok}`);
+                };
+                runTelemetry().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
+                telemetryHandle = setInterval(() => {
+                    runTelemetry().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
+                }, TELEMETRY_INTERVAL_MS);
+                // -- Poll -------------------------------------------------------
+                const poll = async () => {
+                    if (!state.running)
+                        return;
+                    try {
+                        const entries = await fetchNewEntries(config);
+                        if (entries.length === 0) {
+                            state.consecutiveFailures = 0;
+                            state.lastPollAt = Date.now();
+                            persistState();
+                            return;
+                        }
+                        let envelopes = transformEntries(entries);
+                        const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
+                        if (quarantined > 0) {
+                            state.quarantineCount += quarantined;
+                            log.warn('shield', `${quarantined} events quarantined (see ~/.openclaw/shield/data/quarantine.jsonl)`);
+                        }
+                        envelopes = envelopes.filter(e => validEvents.includes(e.event));
+                        if (config.redactionEnabled) {
+                            envelopes = envelopes.map(e => redactEvent(e));
+                        }
+                        const results = await sendEvents(envelopes, config);
+                        const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
+                        if (accepted > 0) {
+                            commitCursors(config, entries);
+                            flushRedactor();
+                            state.eventsProcessed += accepted;
+                            state.consecutiveFailures = 0;
+                        }
+                        else {
+                            state.consecutiveFailures++;
+                        }
+                        state.lastPollAt = Date.now();
+                        persistState();
+                    }
+                    catch (err) {
+                        state.consecutiveFailures++;
+                        log.error('shield', `Poll error: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                };
+                pollFn = poll;
+                await poll();
+                const schedulePoll = () => {
+                    if (!state.running)
+                        return;
+                    const interval = getBackoffInterval(config.pollIntervalMs);
+                    if (interval !== config.pollIntervalMs) {
+                        log.warn('shield', `Backing off: next poll in ${Math.round(interval / 1000)}s (${state.consecutiveFailures} consecutive failures)`);
+                    }
+                    pollHandle = setTimeout(() => {
+                        poll().catch((err) => {
+                            state.consecutiveFailures++;
+                            log.error('shield', `Poll error (unhandled): ${err instanceof Error ? err.message : String(err)}`);
+                        }).finally(() => {
+                            schedulePoll();
+                        });
+                    }, interval);
+                };
+                schedulePoll();
+                // ── Graceful shutdown on process signals ──────────────────────────
+                // Handles SIGTERM (gateway graceful stop) and SIGINT (Ctrl-C / dev).
+                // Uses once() so the handler self-removes after first signal.
+                const onSignal = async () => {
+                    if (!state.running)
+                        return; // already stopped
+                    state.running = false;
+                    persistState();
+                    if (pollHandle) {
+                        clearTimeout(pollHandle);
+                        pollHandle = null;
+                    }
+                    if (telemetryHandle) {
+                        clearInterval(telemetryHandle);
+                        telemetryHandle = null;
+                    }
+                    try {
+                        const { flush: fr } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                        fr();
+                    }
+                    catch { }
+                    log.info('shield', 'Service stopped (signal)');
+                };
+                process.once('SIGTERM', onSignal);
+                process.once('SIGINT', onSignal);
+            },
+            async stop() {
+                if (!state.running)
+                    return; // already stopped by signal handler
+                state.running = false;
+                persistState();
+                if (pollHandle) {
+                    clearTimeout(pollHandle);
+                    pollHandle = null;
+                }
+                if (telemetryHandle) {
+                    clearInterval(telemetryHandle);
+                    telemetryHandle = null;
+                }
+                try {
+                    const { flush: flushRedactor } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                    flushRedactor();
+                }
+                catch { /* ignore if module not loaded */ }
+                log.info('shield', 'Service stopped');
+            },
+        });
+    },
+};

package/dist/src/config.d.ts

@@ -0,0 +1,43 @@
+export interface ShieldCredentials {
+    apiUrl: string;
+    hmacSecret: string;
+    instanceId: string;
+    shieldEnv: string;
+}
+export interface Config {
+    dryRun: boolean;
+    pollIntervalMs: number;
+    sessionDirs: string[];
+    cursorFile: string;
+    hostname: string;
+    maxEvents: number;
+    collectHostMetrics: boolean;
+    redactionEnabled: boolean;
+    credentials: ShieldCredentials;
+}
+/** Canonical config location — shared by setup, bridge, and plugin entry. */
+export declare const SHIELD_CONFIG_PATH: string;
+/**
+ * Inject config file values into process.env so the standalone bridge
+ * (sender, fetcher, etc.) can read credentials via env vars.
+ * Values already set in the environment take precedence (allows override).
+ */
+export declare function injectConfigEnv(): void;
+/**
+ * Load credentials from config.env file and environment variables.
+ * Supports new env var names with backward compat for the old names.
+ */
+export declare function loadCredentials(): ShieldCredentials;
+/**
+ * Build credentials from a plugin config object (openclaw.json).
+ * Falls back to config.env / env vars for any missing values.
+ */
+export declare function loadCredentialsFromPluginConfig(pluginConfig: Record<string, unknown>): ShieldCredentials;
+export interface ConfigOverrides {
+    credentials?: ShieldCredentials;
+    dryRun?: boolean;
+    redactionEnabled?: boolean;
+    pollIntervalMs?: number;
+    collectHostMetrics?: boolean;
+}
+export declare function loadConfig(overrides?: ConfigOverrides): Config;