@upx-us/shield 0.3.29 → 0.4.36

package/dist/src/transformer.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOpenClawVersion = resolveOpenClawVersion;
+exports._resetCachedOpenClawVersion = _resetCachedOpenClawVersion;
 exports.resolveAgentLabel = resolveAgentLabel;
 exports.getCachedPublicIp = getCachedPublicIp;
 exports.resolveOutboundIp = resolveOutboundIp;
@@ -41,37 +42,59 @@ exports.transformEntries = transformEntries;
 exports.generateHostTelemetry = generateHostTelemetry;
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
+const safe_io_1 = require("./safe-io");
 const path = __importStar(require("path"));
 const dgram_1 = require("dgram");
 const events_1 = require("./events");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
 const counters_1 = require("./counters");
+const inventory_1 = require("./inventory");
+let _cachedOpenClawVersion = "";
 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;
-            }
+    if (_cachedOpenClawVersion !== "")
+        return _cachedOpenClawVersion;
+    if (process.env.OPENCLAW_VERSION) {
+        _cachedOpenClawVersion = process.env.OPENCLAW_VERSION;
+        return _cachedOpenClawVersion;
+    }
+    try {
+        const pkgPath = require.resolve('openclaw/package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (pkg.version) {
+            _cachedOpenClawVersion = pkg.version;
+            return _cachedOpenClawVersion;
         }
-        catch { }
     }
+    catch { }
     try {
-        const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.openclaw/openclaw.json'), 'utf8'));
-        return cfg?.meta?.lastTouchedVersion || 'unknown';
+        const { execSync } = require('child_process');
+        const output = execSync('openclaw --version', {
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+        }).trim();
+        const version = output.includes('/') ? output.split('/').pop() : output;
+        if (version && version !== 'unknown') {
+            _cachedOpenClawVersion = version;
+            return _cachedOpenClawVersion;
+        }
     }
-    catch {
-        return 'unknown';
+    catch { }
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.openclaw/openclaw.json'), 'utf8'));
+        const v = cfg?.meta?.lastTouchedVersion;
+        if (v) {
+            _cachedOpenClawVersion = v;
+            return _cachedOpenClawVersion;
+        }
     }
+    catch { }
+    _cachedOpenClawVersion = 'unknown';
+    return _cachedOpenClawVersion;
+}
+function _resetCachedOpenClawVersion() {
+    _cachedOpenClawVersion = "";
 }
 function resolveAgentLabel(agentId) {
     if (process.env.OPENCLAW_AGENT_LABEL)
@@ -113,7 +136,7 @@ function writeIpCache(ip) {
         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() }));
+        (0, safe_io_1.writeJsonSafe)(IP_CACHE_FILE, { ip, resolvedAt: Date.now() });
     }
     catch { }
 }
@@ -205,6 +228,8 @@ function isAdministrativeEvent(toolName, args, sessionId) {
             return true;
         if (/openclaw\s+cron\s+(list|log|runs|status)/.test(cmd))
             return true;
+        if (/openclaw\s+shield\s+cases/.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))
@@ -223,6 +248,8 @@ function isAdministrativeEvent(toolName, args, sessionId) {
         return true;
     if (['sessions_list', 'sessions_history', 'session_status'].includes(toolName))
         return true;
+    if (/^shield\.cases_/.test(toolName) || /^shield\.status$/.test(toolName))
+        return true;
     return false;
 }
 function transformEntries(entries) {
@@ -251,6 +278,18 @@ function transformEntries(entries) {
                         event.tool_metadata = {};
                     event.tool_metadata['openclaw.is_administrative'] = 'true';
                 }
+                const crossText = [
+                    args.command || '',
+                    args.file_path || args.path || args.filePath || '',
+                    args.url || '',
+                ].join(' ');
+                const targetWorkspace = (0, inventory_1.detectCrossWorkspace)(crossText, agentId);
+                if (targetWorkspace) {
+                    if (!event.tool_metadata)
+                        event.tool_metadata = {};
+                    event.tool_metadata['openclaw.cross_workspace_access'] = 'true';
+                    event.tool_metadata['openclaw.target_workspace'] = targetWorkspace;
+                }
                 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 });

package/dist/src/updater.js

@@ -47,6 +47,7 @@ exports.performAutoUpdate = performAutoUpdate;
 exports.requestGatewayRestart = requestGatewayRestart;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
+const safe_io_1 = require("./safe-io");
 const path_1 = require("path");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
@@ -101,13 +102,7 @@ function ensureDir(dir) {
         (0, fs_1.mkdirSync)(dir, { recursive: true });
 }
 function loadUpdateState() {
-    try {
-        if ((0, fs_1.existsSync)(UPDATE_STATE_FILE)) {
-            return JSON.parse((0, fs_1.readFileSync)(UPDATE_STATE_FILE, 'utf-8'));
-        }
-    }
-    catch { }
-    return {
+    const defaults = {
         lastCheckAt: 0,
         lastUpdateAt: 0,
         currentVersion: version_1.VERSION,
@@ -117,10 +112,14 @@ function loadUpdateState() {
         rollbackVersion: null,
         consecutiveFailures: 0,
     };
+    if (!(0, fs_1.existsSync)(UPDATE_STATE_FILE))
+        return defaults;
+    const loaded = (0, safe_io_1.readJsonSafe)(UPDATE_STATE_FILE, {}, 'update-state');
+    return { ...defaults, ...loaded };
 }
 function saveUpdateState(state) {
     ensureDir((0, path_1.dirname)(UPDATE_STATE_FILE));
-    (0, fs_1.writeFileSync)(UPDATE_STATE_FILE, JSON.stringify(state, null, 2));
+    (0, safe_io_1.writeJsonSafe)(UPDATE_STATE_FILE, state);
 }
 function checkNpmVersion() {
     try {
@@ -291,7 +290,7 @@ function updateOpenClawPluginMetadata(newVersion, shasum) {
             delete install.shasum;
         }
         install.installedAt = new Date().toISOString();
-        (0, fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2) + '\n');
+        (0, safe_io_1.writeJsonSafe)(configPath, config);
         log.info('updater', `Updated openclaw.json plugin metadata → ${newVersion}`);
     }
     catch (err) {

package/openclaw.plugin.json

@@ -1,79 +1,84 @@
 {
-    "id": "shield",
-    "name": "OpenClaw Shield",
-    "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-    "version": "0.3.29",
-    "skills": [
-        "./skills"
-    ],
-    "configSchema": {
-        "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
-            },
-            "dryRun": {
-                "type": "boolean",
-                "default": false
-            },
-            "redactionEnabled": {
-                "type": "boolean",
-                "default": true
-            },
-            "pollIntervalMs": {
-                "type": "number",
-                "default": 30000
-            },
-            "collectHostMetrics": {
-                "type": "boolean",
-                "default": false
-            },
-            "autoUpdate": {
-                "oneOf": [
-                    {
-                        "type": "boolean"
-                    },
-                    {
-                        "type": "string",
-                        "enum": [
-                            "notify-only"
-                        ]
-                    }
-                ],
-                "default": true,
-                "description": "Auto-update mode: true (auto-update patch versions), false (disabled), or 'notify-only' (log available updates without installing)."
-            }
-        }
+  "id": "shield",
+  "name": "OpenClaw Shield",
+  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.4.36",
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "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
+      },
+      "dryRun": {
+        "type": "boolean",
+        "default": false
+      },
+      "redactionEnabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "default": 30000
+      },
+      "collectHostMetrics": {
+        "type": "boolean",
+        "default": false
+      },
+      "autoUpdate": {
+        "oneOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "string",
+            "enum": [
+              "notify-only"
+            ]
+          }
+        ],
+        "default": true,
+        "description": "Auto-update mode: true (auto-update patch versions), false (disabled), or 'notify-only' (log available updates without installing)."
+      }
+    }
+  },
+  "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"
+    },
+    "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"
     },
-    "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"
-        },
-        "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"
-        },
-        "autoUpdate": {
-            "label": "Auto-update mode",
-            "description": "true = auto-install patch updates, 'notify-only' = log only, false = disabled"
-        }
+    "autoUpdate": {
+      "label": "Auto-update mode",
+      "description": "true = auto-install patch updates, 'notify-only' = log only, false = disabled"
     }
+  },
+  "clawhub": {
+    "slug": "openclaw-shield-upx",
+    "skillVersion": "1.0.2",
+    "note": "ClawHub auto-increments on publish. Update this after each clawhub submission."
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.3.29",
-  "description": "Security monitoring plugin for OpenClaw agents \u2014 streams enriched security events to the Shield detection platform",
+  "version": "0.4.36",
+  "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": {
@@ -39,16 +39,21 @@
     "package:pack": "npm pack",
     "package:publish": "npm run package:validate && npm publish --access public",
     "start": "node dist/src/index.js",
-    "setup": "node dist/src/setup.js"
+    "setup": "node dist/src/setup.js",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
+    "agent-monitoring",
+    "ai-security",
+    "clawhub",
+    "compliance",
+    "detection",
+    "monitoring",
     "openclaw",
     "openclaw-plugin",
+    "openclaw-skill",
     "security",
-    "monitoring",
-    "detection",
-    "siem",
-    "compliance"
+    "siem"
   ],
   "author": "UPX Security Services",
   "license": "SEE LICENSE IN LICENSE",
@@ -69,5 +74,9 @@
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
+  },
+  "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx",
+  "clawhub": {
+    "slug": "openclaw-shield-upx"
   }
-}
+}

package/skills/shield/README.md

@@ -0,0 +1,39 @@
+# OpenClaw Shield — Security Specialist
+
+A skill that turns your OpenClaw agent into a cybersecurity specialist.
+
+## What it does
+
+When Shield is installed, your agent can:
+
+- **Monitor** — check Shield health, event counts, and sync status
+- **Inspect** — view host agent inventory and redaction vault via `shield vault show`
+- **Interpret** — analyze security events and explain what they mean
+- **Advise** — recommend remediation, hardening, and next steps
+- **Triage** — assess alert severity and prioritize response
+- **Explain** — break down attack techniques, privacy model, and detection scope
+
+## Requirements
+
+- [OpenClaw Shield plugin](https://www.npmjs.com/package/@upx-us/shield) installed and activated
+- Active Shield subscription from [UPX](https://upx.com) — [start a free 30-day trial](https://www.upx.com/pt/lp/openclaw-shield-upx)
+
+## Install
+
+This skill is bundled with the Shield plugin. Install the plugin and the skill is available automatically:
+
+```bash
+openclaw plugins install @upx-us/shield
+openclaw shield activate <YOUR_KEY>
+openclaw gateway restart
+```
+
+## Links
+
+- **Plugin (npm)**: [@upx-us/shield](https://www.npmjs.com/package/@upx-us/shield)
+- **Skill (ClawHub)**: [openclaw-shield-upx](https://clawhub.ai/brunopradof/openclaw-shield-upx)
+- **Dashboard**: [uss.upx.com](https://uss.upx.com)
+
+## About
+
+Made by [UPX](https://upx.com) — cybersecurity engineering for critical environments.

package/skills/shield/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: openclaw-shield-upx
+description: "Security monitoring for OpenClaw agents — check Shield health, review events, inspect vault. Use when: user asks about security status, Shield health, event logs, or redaction vault. NOT for: general OS hardening, firewall config, or network security."
+metadata: {"openclaw": {"requires": {"config": ["plugins.entries.shield"]}, "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx", "emoji": "🛡️"}}
+---
+
+# OpenClaw Shield
+
+Security monitoring for OpenClaw agents by [UPX](https://www.upx.com). Shield runs as a plugin inside the OpenClaw gateway, capturing agent activity and sending redacted telemetry to the UPX detection platform.
+
+## Getting started
+
+Shield requires the `@upx-us/shield` plugin and an active subscription.
+
+- **Plugin (npm)**: [@upx-us/shield](https://www.npmjs.com/package/@upx-us/shield)
+- **Subscribe / Free 30-day trial**: [upx.com/pt/lp/openclaw-shield-upx](https://www.upx.com/pt/lp/openclaw-shield-upx)
+- **Dashboard**: [uss.upx.com](https://uss.upx.com)
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `openclaw shield status` | Plugin health, connection state, event counts, last sync |
+| `openclaw shield flush` | Force an immediate sync to the platform |
+| `openclaw shield activate <KEY>` | One-time activation with an Installation Key |
+| `openclaw shield logs` | Recent events from the local buffer (last 24h) |
+| `openclaw shield logs --last 20` | Show last N events |
+| `openclaw shield logs --type TOOL_CALL --since 1h` | Filter by event type or time window |
+| `openclaw shield logs --format json` | JSON output |
+| `openclaw shield vault show` | Agent and workspace inventory (hashed IDs) |
+| `openclaw shield vault redactions` | Redaction summary — token categories and counts |
+| `openclaw shield cases` | List open security cases |
+| `openclaw shield cases show <ID>` | Full case detail with events, rule, playbook |
+| `openclaw shield cases resolve <ID>` | Resolve a case (--resolution, --root-cause, --comment) |
+
+## When to use this skill
+
+- "Is Shield running?" → `openclaw shield status`
+- "What did Shield capture recently?" → `openclaw shield logs`
+- "How many agents are on this machine?" → `openclaw shield vault show`
+- "Force a sync now" → `openclaw shield flush`
+- User asks about a security alert or event → interpret using your security knowledge and Shield data
+- User asks about Shield's privacy model → all data is redacted on-device before transmission; raw values never leave the machine
+
+## Status interpretation
+
+After running `openclaw shield status`, check:
+
+- **Connected** → healthy, nothing to do
+- **Disconnected** → gateway may need a restart
+- **High failure count** → platform connectivity issue, usually self-recovers; try `openclaw shield flush`
+- **Rising quarantine** → possible version mismatch, suggest checking for plugin updates
+
+## Cases
+
+Cases are created automatically when detection rules fire. Check during heartbeats via `shield.cases_list`. If `pending_count > 0`, notify the user, then call `shield.cases_ack` to mark seen.
+
+| RPC | Params | Purpose |
+|---|---|---|
+| `shield.cases_list` | `status`, `limit`, `since` | List open cases + pending notifications |
+| `shield.case_detail` | `id` | Full case with events, rule, playbook |
+| `shield.case_resolve` | `id`, `resolution`, `root_cause`, `comment` | Close a case |
+| `shield.cases_ack` | `ids` | Mark cases as notified |
+
+**Resolve values:** `true_positive`, `false_positive`, `benign`, `duplicate`
+**Root cause values:** `user_initiated`, `misconfiguration`, `expected_behavior`, `actual_threat`, `testing`, `unknown`