@upx-us/shield 0.2.12-beta

package/dist/src/transformer.js

@@ -0,0 +1,302 @@
+"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);
+    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.resolveOpenClawVersion = resolveOpenClawVersion;
+exports.resolveAgentLabel = resolveAgentLabel;
+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 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. */
+function resolveOpenClawVersion() {
+    if (process.env.OPENCLAW_VERSION)
+        return process.env.OPENCLAW_VERSION;
+    const candidates = [
+        '/opt/homebrew/lib/node_modules/openclaw/package.json',
+        '/usr/local/lib/node_modules/openclaw/package.json',
+        path.join(os.homedir(), '.nvm/versions/node/*/lib/node_modules/openclaw/package.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+        catch { /* skip */ }
+    }
+    // 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';
+    }
+    catch {
+        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;
+    try {
+        const cfgPath = path.join(os.homedir(), '.openclaw/openclaw.json');
+        const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+        const workspace = cfg?.agents?.defaults?.workspace || path.join(os.homedir(), '.openclaw/workspace');
+        const identityPath = path.join(workspace, 'IDENTITY.md');
+        if (fs.existsSync(identityPath)) {
+            const content = fs.readFileSync(identityPath, 'utf8');
+            const match = content.match(/^\s*-\s*\*\*Name:\*\*\s*(.+)$/m);
+            if (match)
+                return match[1].trim();
+        }
+    }
+    catch { /* skip */ }
+    return agentId;
+}
+/** Fetch the public (egress) IP from ipify.org — resolves once at startup. */
+function fetchPublicIp() {
+    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 {
+                    resolve(JSON.parse(data).ip || null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); 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}`);
+        }
+        return ip;
+    });
+}
+initPublicIp();
+function getSourceInfo() {
+    if (_source)
+        return _source;
+    const agentId = process.env.OPENCLAW_AGENT_ID || 'main';
+    _source = {
+        hostname: os.hostname(),
+        ip_addresses: Object.values(os.networkInterfaces())
+            .flat()
+            .filter((i) => i && i.family === 'IPv4' && !i.internal)
+            .map((i) => i.address),
+        os: {
+            type: os.type(),
+            platform: os.platform() === 'darwin' ? 'MAC' : os.platform() === 'linux' ? 'LINUX' : 'WINDOWS',
+            release: os.release(),
+            arch: os.arch(),
+        },
+        openclaw: {
+            version: resolveOpenClawVersion(),
+            agent_id: agentId,
+            agent_label: resolveAgentLabel(agentId),
+        },
+        plugin: { version: version_1.VERSION, transport: 'openclaw_plugin' },
+    };
+    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;
+    if (toolName === 'exec') {
+        const cmd = args.command || '';
+        if (/tools\/(deploy-rules|sync-rules|audit-meta|validate-rules|fix-meta)/.test(cmd))
+            return true;
+        if (/openclaw\s+cron\s+(list|log|runs|status)/.test(cmd))
+            return true;
+        if (/ps\s+aux.*grep.*(ts-node|bridge|shield)/.test(cmd))
+            return true;
+        if (/gcloud\s+auth\s+print-access-token/.test(cmd))
+            return true;
+    }
+    if (['read', 'write', 'edit'].includes(toolName)) {
+        const fp = args.file_path || args.path || args.filePath || '';
+        if (/openclaw-shield\/(rules|tools|playbooks|docs)\//.test(fp))
+            return true;
+        if (/team-dashboard\/data\/detection-rules\.json/.test(fp))
+            return true;
+        if (/memory\/squad-audit/.test(fp))
+            return true;
+    }
+    if (toolName === 'cron' && ['list', 'status', 'runs'].includes(args.action))
+        return true;
+    if (['sessions_list', 'sessions_history', 'session_status'].includes(toolName))
+        return true;
+    return false;
+}
+// ─── Main Transform ───────────────────────────────────────────────────────────
+function transformEntries(entries) {
+    const baseSource = getSourceInfo();
+    const envelopes = [];
+    for (const entry of entries) {
+        const msg = entry.message;
+        const agentId = entry._agentId || baseSource.openclaw.agent_id;
+        const source = {
+            ...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) {
+                if (item.type !== 'toolCall')
+                    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
+                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);
+                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)) {
+                if (!event.tool_metadata)
+                    event.tool_metadata = {};
+                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);
+            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;
+    const versionSortable = version.split('.').map((p, i) => i > 0 ? p.padStart(2, '0') : p).join('.');
+    let gatewayBind = '127.0.0.1';
+    let webhookUrl = null;
+    let webhookConfigured = 'false';
+    let webhookHasSecret = 'false';
+    let browserAuthRequired = 'false';
+    let gatewayUrl = null;
+    try {
+        const fs = require('fs');
+        const home = require('os').homedir();
+        const configPath = `${home}/.openclaw/openclaw.json`;
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            gatewayBind = config.gateway?.host || config.host || '127.0.0.1';
+            gatewayUrl = config.gateway?.url || null;
+            const wh = config.webhooks || config.webhook;
+            if (wh) {
+                webhookConfigured = 'true';
+                webhookUrl = typeof wh === 'string' ? wh : wh.url || wh.endpoint || null;
+                webhookHasSecret = (wh.secret || wh.hmac_secret || wh.signing_secret) ? 'true' : 'false';
+            }
+            if (config.browser?.requireAuth || config.browser?.password) {
+                browserAuthRequired = 'true';
+            }
+        }
+    }
+    catch { /* default values */ }
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'TOOL_CALL',
+        tool_name: 'host_telemetry',
+        tool_category: 'host_telemetry',
+        session_id: 'telemetry',
+        product_name: 'OpenClaw',
+        vendor_name: 'UPX',
+        principal: {
+            hostname: source.hostname,
+            ip: source.ip_addresses?.[0] || '',
+            platform: source.os.platform,
+            user: source.openclaw.agent_id,
+        },
+        tool_metadata: {
+            tool_name: 'host_telemetry',
+            'openclaw.version': version,
+            'openclaw.version_sortable': versionSortable,
+            'openclaw.gateway_bind': gatewayBind,
+            'openclaw.gateway_url': gatewayUrl,
+            'openclaw.webhook_url': webhookUrl,
+            'openclaw.webhook_configured': webhookConfigured,
+            'openclaw.webhook_has_secret': webhookHasSecret,
+            'openclaw.browser_auth_required': browserAuthRequired,
+        },
+    };
+    return { source, event };
+}

package/dist/src/validator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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

@@ -0,0 +1,110 @@
+"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);
+    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.QUARANTINE_FILE = void 0;
+exports.validate = validate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const events_1 = require("./events");
+const base_1 = require("./events/base");
+const log = __importStar(require("./log"));
+const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
+exports.QUARANTINE_FILE = path.join(SHIELD_DATA_DIR, 'quarantine.jsonl');
+function ensureDataDir() {
+    fs.mkdirSync(SHIELD_DATA_DIR, { recursive: true });
+}
+function appendQuarantine(event, error, field) {
+    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');
+    }
+    catch (e) {
+        // Quarantine write failure is non-fatal
+        console.error('[validator] Failed to write quarantine record:', e);
+    }
+}
+/**
+ * Validate a batch of events.
+ * Returns the valid events and the count of quarantined ones.
+ */
+function validate(events) {
+    const valid = [];
+    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);
+            }
+            continue;
+        }
+        const result = (0, base_1.validateEvent)(event, schema);
+        if (result.valid) {
+            log.debug('validator', `PASS tool=${event.tool_name} category=${event.tool_category}`);
+            valid.push(event);
+        }
+        else {
+            quarantined++;
+            appendQuarantine(event, result.error || 'validation_failed', result.field);
+            log.warn('validator', `QUARANTINE tool=${event.tool_name} field=${result.field} error=${result.error}`);
+            log.debug('validator', 'quarantined event', event);
+        }
+    }
+    if (quarantined > 0 || log.isDebug) {
+        log.info('validator', `${valid.length} valid, ${quarantined} quarantined`);
+    }
+    return { valid, quarantined };
+}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/src/version.js

@@ -0,0 +1,19 @@
+"use strict";
+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);
+        if ((0, fs_1.existsSync)(p)) {
+            try {
+                return JSON.parse((0, fs_1.readFileSync)(p, 'utf-8')).version ?? '0.0.0';
+            }
+            catch { /* next */ }
+        }
+    }
+    return '0.0.0';
+}
+exports.VERSION = loadVersion();

package/openclaw.plugin.json

@@ -0,0 +1,52 @@
+{
+  "id": "shield",
+  "name": "OpenClaw Shield",
+  "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.2.12-beta",
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "dryRun": {
+        "type": "boolean",
+        "default": false
+      },
+      "redactionEnabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "default": 30000
+      },
+      "collectHostMetrics": {
+        "type": "boolean",
+        "default": false
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable security monitoring"
+    },
+    "dryRun": {
+      "label": "Dry run (log events locally, do not transmit)"
+    },
+    "redactionEnabled": {
+      "label": "Redact sensitive values before transmitting"
+    },
+    "pollIntervalMs": {
+      "label": "Polling interval (milliseconds)"
+    },
+    "collectHostMetrics": {
+      "label": "Collect host telemetry metrics"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@upx-us/shield",
+  "version": "0.2.12-beta",
+  "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",
+  "bin": {
+    "shield-bridge": "dist/src/index.js",
+    "shield-setup": "dist/src/setup.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/src/",
+    "openclaw.plugin.json",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "start": "node dist/src/index.js",
+    "setup": "node dist/src/setup.js",
+    "lint": "tsc --noEmit",
+    "test": "node --require tsx/cjs --test --test-reporter spec tests/**/*.test.ts tests/*.test.ts",
+    "test:watch": "node --require tsx/cjs --test --watch tests/**/*.test.ts tests/*.test.ts",
+    "test:parser": "node tests/run-parser.js",
+    "test:parser:short": "node tests/run-parser.js --short",
+    "test:parser:verbose": "node tests/run-parser.js --verbose",
+    "test:parser:help": "node tests/run-parser.js help",
+    "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",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublish:check": "node scripts/prepublish-check.js"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "security",
+    "monitoring",
+    "detection",
+    "siem",
+    "compliance"
+  ],
+  "author": "UPX Security Services",
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "ts-json-schema-generator": "^2.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/shield/SKILL.md

@@ -0,0 +1,38 @@
+---
+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