@upx-us/shield 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.4] — 2026-03-09
+
+### Fixed
+- **Case monitor — "Exclusions not initialized" (Telegram alerts never delivered)** — Exclusions are an optimization (noise filter), not a hard dependency. The `checkForNewCases()` loop called `isExcluded()` which threw `'Exclusions not initialized'` on every poll cycle because `initExclusions()` was never called in `src/index.ts`. Every check silently failed, resulting in zero Telegram notifications despite the platform returning open cases. Fix: replaced the hard dependency on exclusions with a soft check — if exclusions aren't initialized, a one-time warning is logged and all cases are forwarded unfiltered (over-notify is safer than silently dropping alerts). Root cause: `src/case-monitor.ts`, `checkForNewCases()` exclusion filter block — `storePath()` unconditionally threw when `_dataDir` was null.
+
+---
+
+## [0.6.3] — 2026-03-09
+
+### Fixed
+- **Version normalization** — `resolveOpenClawVersion()` now normalizes messy version strings from `openclaw --version` output and the `lastTouchedVersion` config field (e.g. `"OpenClaw 2026.3.8 (3caab92)"` → `"2026.3.8"`). Previously these strings caused false "out of date" alerts on the Shield dashboard.
+- **Missing Network info** — `PUT /v1/instance` now always includes `public_ip` in the machine payload, even when the IP hasn't been resolved yet (sends `""` instead of omitting the field). This ensures the platform can attempt server-side geo-enrichment (Provider/Location) instead of silently skipping it.
+
+### Added
+- `normalizeSoftwareVersion(v: string): string` — exported helper that applies the full version normalization pipeline (strip `"OpenClaw "` prefix, parenthetical hash, leading `"v"`). Used internally by `resolveOpenClawVersion()` for all auto-detected version paths.
+- `isPrivateIp(ip: string): boolean` — exported helper that detects RFC-1918/loopback addresses. Used by the ingest service to identify when an agent behind NAT (macOS, home/office Linux) self-reports a LAN IP and override it with the authoritative request IP. Ensures correct Network info (Provider, Location) on the Shield dashboard for all platforms.
+
+---
+
 ## [0.6.2] — 2026-03-09
 
 ### Fixed

package/dist/index.js

@@ -51,6 +51,7 @@ const crypto_1 = require("crypto");
 const counters_1 = require("./src/counters");
 const cli_cases_1 = require("./src/cli-cases");
 const case_monitor_1 = require("./src/case-monitor");
+const exclusions_1 = require("./src/exclusions");
 const updater_1 = require("./src/updater");
 const rpc_1 = require("./src/rpc");
 const inventory_1 = require("./src/inventory");
@@ -589,6 +590,7 @@ exports.default = {
                     if (persistedStats.lastSync)
                         state.lastSync = persistedStats.lastSync;
                     log.info('shield', `Starting monitoring bridge v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
+                    (0, exclusions_1.initExclusions)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'));
                     (0, case_monitor_1.initCaseMonitor)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'));
                     const runtime = api.runtime;
                     if (runtime?.system?.enqueueSystemEvent && runtime?.system?.requestHeartbeatNow) {

package/dist/src/case-monitor.d.ts

@@ -56,6 +56,10 @@ export interface CaseDetail extends CaseSummary {
 }
 export declare function initCaseMonitor(dataDir: string): void;
 export declare function notifyCaseMonitorActivity(): void;
+export declare function getMonitorHealth(): {
+    status: 'ok' | 'degraded';
+    consecutiveFailures: number;
+};
 export declare function getCaseMonitorStatus(): {
     intervalMs: number;
     nextCheckIn: number;

package/dist/src/case-monitor.js

@@ -37,6 +37,7 @@ exports.setCaseNotificationDispatcher = setCaseNotificationDispatcher;
 exports.setDirectSendDispatcher = setDirectSendDispatcher;
 exports.initCaseMonitor = initCaseMonitor;
 exports.notifyCaseMonitorActivity = notifyCaseMonitorActivity;
+exports.getMonitorHealth = getMonitorHealth;
 exports.getCaseMonitorStatus = getCaseMonitorStatus;
 exports.checkForNewCases = checkForNewCases;
 exports.getPendingCases = getPendingCases;
@@ -161,6 +162,9 @@ let _dataDir = null;
 let _lastCheckAt = 0;
 let _lastEventAt = 0;
 let _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
+let _exclusionsWarnedOnce = false;
+let _consecutiveCheckFailures = 0;
+const DEGRADED_THRESHOLD = 5;
 function computeInterval() {
     if (_lastCheckAt === 0)
         return MIN_CHECK_INTERVAL_MS;
@@ -181,6 +185,12 @@ function initCaseMonitor(dataDir) {
 function notifyCaseMonitorActivity() {
     _lastEventAt = Date.now();
 }
+function getMonitorHealth() {
+    return {
+        status: _consecutiveCheckFailures >= DEGRADED_THRESHOLD ? 'degraded' : 'ok',
+        consecutiveFailures: _consecutiveCheckFailures,
+    };
+}
 function getCaseMonitorStatus() {
     const interval = computeInterval();
     const nextCheckIn = Math.max(0, (_lastCheckAt + interval) - Date.now());
@@ -210,7 +220,11 @@ async function checkForNewCases(config) {
         const result = await (0, client_1.callPlatformApi)(config, '/v1/agent/cases', params, 'GET');
         if (!result.ok) {
             if (!result.error?.includes('not configured')) {
+                _consecutiveCheckFailures++;
                 log.warn('case-monitor', `Failed to check cases: ${result.error}`);
+                if (_consecutiveCheckFailures >= DEGRADED_THRESHOLD) {
+                    log.warn('case-monitor', `[case-monitor] DEGRADED: ${_consecutiveCheckFailures} consecutive check failures — notifications may be silently dropped`);
+                }
             }
             return;
         }
@@ -219,14 +233,23 @@ async function checkForNewCases(config) {
         const pendingSet = new Set(state.pendingCases.map(c => c.id));
         const newCasesRaw = cases.filter(c => !ackSet.has(c.id) && !pendingSet.has(c.id));
         const newCases = [];
-        for (const c of newCasesRaw) {
-            const hash = (0, exclusions_1.computePatternHash)(c.rule_id, c.summary || '');
-            if ((0, exclusions_1.isExcluded)(c.rule_id, hash, c.agent_id)) {
-                log.info('case-monitor', `Case ${c.id} matched FP exclusion (rule=${c.rule_id}) — auto-acknowledging`);
-                state.acknowledgedIds = [...state.acknowledgedIds, c.id].slice(-MAX_ACKNOWLEDGED_IDS);
+        if (!(0, exclusions_1.isInitialized)()) {
+            if (!_exclusionsWarnedOnce) {
+                log.warn('case-monitor', 'Exclusions not initialized — proceeding without FP filtering');
+                _exclusionsWarnedOnce = true;
             }
-            else {
-                newCases.push(c);
+            newCases.push(...newCasesRaw);
+        }
+        else {
+            for (const c of newCasesRaw) {
+                const hash = (0, exclusions_1.computePatternHash)(c.rule_id, c.summary || '');
+                if ((0, exclusions_1.isExcluded)(c.rule_id, hash, c.agent_id)) {
+                    log.info('case-monitor', `Case ${c.id} matched FP exclusion (rule=${c.rule_id}) — auto-acknowledging`);
+                    state.acknowledgedIds = [...state.acknowledgedIds, c.id].slice(-MAX_ACKNOWLEDGED_IDS);
+                }
+                else {
+                    newCases.push(c);
+                }
             }
         }
         if (newCases.length > 0) {
@@ -237,9 +260,14 @@ async function checkForNewCases(config) {
         }
         state.lastCheckAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(stateFile, state);
+        _consecutiveCheckFailures = 0;
     }
     catch (err) {
+        _consecutiveCheckFailures++;
         log.warn('case-monitor', `Check failed: ${err instanceof Error ? err.message : String(err)}`);
+        if (_consecutiveCheckFailures >= DEGRADED_THRESHOLD) {
+            log.warn('case-monitor', `[case-monitor] DEGRADED: ${_consecutiveCheckFailures} consecutive check failures — notifications may be silently dropped`);
+        }
     }
 }
 function getPendingCases() {
@@ -337,5 +365,14 @@ function getTimeAgo(isoDate) {
 function _resetForTesting() {
     _dataDir = null;
     _lastCheckAt = 0;
+    _lastEventAt = 0;
     _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
+    _exclusionsWarnedOnce = false;
+    _consecutiveCheckFailures = 0;
+    _enqueueSystemEvent = null;
+    _requestHeartbeatNow = null;
+    _agentId = 'main';
+    _directSendFn = null;
+    _directSendTo = null;
+    _directSendChannel = null;
 }

package/dist/src/exclusions.d.ts

@@ -7,6 +7,7 @@ export interface Exclusion {
     reason?: string;
 }
 export declare function initExclusions(dataDir: string): void;
+export declare function isInitialized(): boolean;
 export declare function normalizePattern(input: string): string;
 export declare function computePatternHash(ruleId: string, command: string): string;
 export declare function addExclusion(ruleId: string, patternHash: string, agentId?: string, reason?: string): Exclusion;

package/dist/src/exclusions.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initExclusions = initExclusions;
+exports.isInitialized = isInitialized;
 exports.normalizePattern = normalizePattern;
 exports.computePatternHash = computePatternHash;
 exports.addExclusion = addExclusion;
@@ -52,6 +53,9 @@ function initExclusions(dataDir) {
     _dataDir = dataDir;
     log.info('exclusions', 'Initialized');
 }
+function isInitialized() {
+    return _dataDir !== null;
+}
 function storePath() {
     if (!_dataDir)
         throw new Error('Exclusions not initialized');

package/dist/src/index.js

@@ -47,6 +47,7 @@ const fs_1 = require("fs");
 const version_1 = require("./version");
 const event_store_1 = require("./event-store");
 const case_monitor_1 = require("./case-monitor");
+const exclusions_1 = require("./exclusions");
 const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
 let running = true;
 let lastTelemetryAt = 0;
@@ -66,6 +67,7 @@ async function poll() {
     if (config.redactionEnabled) {
         (0, redactor_1.init)();
     }
+    (0, exclusions_1.initExclusions)(SHIELD_DATA_DIR);
     (0, case_monitor_1.initCaseMonitor)(SHIELD_DATA_DIR);
     if (config.localEventBuffer) {
         (0, event_store_1.initEventStore)(SHIELD_DATA_DIR, { maxEvents: config.localEventLimit });
@@ -104,7 +106,7 @@ async function poll() {
                         os: process.platform,
                         arch: process.arch,
                         node_version: process.version,
-                        public_ip: (0, transformer_1.getCachedPublicIp)() ?? undefined,
+                        public_ip: (0, transformer_1.getCachedPublicIp)() ?? '',
                     },
                     software: {
                         plugin_version: version_1.VERSION,
@@ -118,6 +120,9 @@ async function poll() {
                         }),
                     },
                 };
+                if (!(0, transformer_1.getCachedPublicIp)()) {
+                    log.warn('bridge', 'Public IP not yet resolved — sending empty public_ip so platform can enrich server-side');
+                }
                 const result = await (0, sender_1.reportInstance)(instancePayload, config.credentials);
                 log.info('bridge', `Instance report → Platform: success=${result.ok}`);
                 if (result.ok) {

package/dist/src/transformer.d.ts

@@ -8,10 +8,12 @@ export interface EnvelopeEvent {
 export interface IngestPayload {
     entries: EnvelopeEvent[];
 }
+export declare function normalizeSoftwareVersion(v: string): string;
 export declare function resolveOpenClawVersion(): string;
 export declare function _resetCachedOpenClawVersion(): void;
 export declare function resolveAgentLabel(agentId: string): string;
 export declare function getCachedPublicIp(): string | null;
+export declare function isPrivateIp(ip: string): boolean;
 export declare function resolveOutboundIp(): Promise<string | null>;
 export declare function transformEntries(entries: RawEntry[]): EnvelopeEvent[];
 export declare function generateHostTelemetry(): EnvelopeEvent | null;

package/dist/src/transformer.js

@@ -33,10 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSoftwareVersion = normalizeSoftwareVersion;
 exports.resolveOpenClawVersion = resolveOpenClawVersion;
 exports._resetCachedOpenClawVersion = _resetCachedOpenClawVersion;
 exports.resolveAgentLabel = resolveAgentLabel;
 exports.getCachedPublicIp = getCachedPublicIp;
+exports.isPrivateIp = isPrivateIp;
 exports.resolveOutboundIp = resolveOutboundIp;
 exports.transformEntries = transformEntries;
 exports.generateHostTelemetry = generateHostTelemetry;
@@ -51,6 +53,13 @@ const version_1 = require("./version");
 const counters_1 = require("./counters");
 const inventory_1 = require("./inventory");
 let _cachedOpenClawVersion = "";
+function normalizeSoftwareVersion(v) {
+    return v
+        .replace(/^openclaw\s+/i, '')
+        .replace(/\s*\([^)]*\)/g, '')
+        .replace(/^v/, '')
+        .trim();
+}
 function resolveOpenClawVersion() {
     if (_cachedOpenClawVersion !== "")
         return _cachedOpenClawVersion;
@@ -62,7 +71,7 @@ function resolveOpenClawVersion() {
         const pkgPath = require.resolve('openclaw/package.json');
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
         if (pkg.version) {
-            _cachedOpenClawVersion = pkg.version;
+            _cachedOpenClawVersion = normalizeSoftwareVersion(pkg.version);
             return _cachedOpenClawVersion;
         }
     }
@@ -74,7 +83,8 @@ function resolveOpenClawVersion() {
             stdio: ['ignore', 'pipe', 'ignore'],
             encoding: 'utf8',
         }).trim();
-        const version = output.includes('/') ? output.split('/').pop() : output;
+        const raw = output.includes('/') ? output.split('/').pop() : output;
+        const version = normalizeSoftwareVersion(raw);
         if (version && version !== 'unknown') {
             _cachedOpenClawVersion = version;
             return _cachedOpenClawVersion;
@@ -85,8 +95,11 @@ function resolveOpenClawVersion() {
         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;
+            const normalized = normalizeSoftwareVersion(v);
+            if (normalized) {
+                _cachedOpenClawVersion = normalized;
+                return _cachedOpenClawVersion;
+            }
         }
     }
     catch { }
@@ -141,7 +154,15 @@ function writeIpCache(ip) {
     catch { }
 }
 function getCachedPublicIp() {
-    return readIpCache()?.ip ?? (_source?.ip_addresses[0] ?? null);
+    return readIpCache()?.ip ?? null;
+}
+function isPrivateIp(ip) {
+    return /^10\./.test(ip) ||
+        /^172\.(1[6-9]|2[0-9]|3[01])\./.test(ip) ||
+        /^192\.168\./.test(ip) ||
+        /^127\./.test(ip) ||
+        /^::1$/.test(ip) ||
+        /^fd/i.test(ip);
 }
 function resolveOutboundIp() {
     return new Promise((resolve) => {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "skills": [
     "./skills"
   ],
@@ -12,7 +12,7 @@
     "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."
+        "description": "One-time installation key obtained after subscribing at upx.com/en/lp/openclaw-shield-upx. The plugin uses this to register the instance and obtain credentials automatically. Can be removed from config after first activation."
       },
       "enabled": {
         "type": "boolean",
@@ -54,7 +54,7 @@
   "uiHints": {
     "installationKey": {
       "label": "Installation Key",
-      "description": "One-time key from the Shield portal (https://uss.upx.com). Required for first-time activation only."
+      "description": "One-time key from your trial signup at https://www.upx.com/en/lp/openclaw-shield-upx \u2014 Required for first-time activation only. After activation, log in at https://uss.upx.com"
     },
     "enabled": {
       "label": "Enable security monitoring"
@@ -78,7 +78,7 @@
   },
   "clawhub": {
     "slug": "openclaw-shield-upx",
-    "skillVersion": "1.0.2",
+    "skillVersion": "1.2.5",
     "note": "ClawHub auto-increments on publish. Update this after each clawhub submission."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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",
@@ -53,7 +53,13 @@
     "openclaw-plugin",
     "openclaw-skill",
     "security",
-    "siem"
+    "siem",
+    "threat-detection",
+    "agent-protection",
+    "audit",
+    "realtime-monitoring",
+    "dlp",
+    "anomaly-detection"
   ],
   "author": "UPX Security Services",
   "license": "SEE LICENSE IN LICENSE",

package/skills/shield/SKILL.md

@@ -1,10 +1,10 @@
 ---
 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."
+description: "SIEM and security monitoring for OpenClaw agents — protect your agent, detect threats, audit events, monitor suspicious activity. Use when: user asks about security status, SIEM, Shield health, event logs, redaction vault, protecting their agent, threat detection, or suspicious activity. NOT for: general OS hardening, firewall config, or network security unrelated to OpenClaw agents."
 homepage: https://www.upx.com/en/lp/openclaw-shield-upx
 source: https://www.npmjs.com/package/@upx-us/shield
 license: "Proprietary — UPX Technologies, Inc. All rights reserved."
-metadata: {"openclaw": {"requires": {"config": ["plugins.entries.shield"]}, "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx", "emoji": "🛡️"}}
+metadata: {"openclaw": {"requires": {"bins": ["openclaw"]}, "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx", "emoji": "🛡️"}}
 ---
 
 # OpenClaw Shield
@@ -35,6 +35,29 @@ Shield requires the `@upx-us/shield` plugin and an active subscription.
 | `openclaw shield cases resolve <ID>` | Resolve a case (--resolution, --root-cause, --comment) |
 | `openclaw shield monitor` | Case notification cron — status, --on, --off, --interval |
 
+## Plugin State Check
+
+Before responding to any Shield-related request, run `openclaw shield status` and branch on the result:
+
+- **Command not found / exit non-zero**: Shield plugin is not installed. Tell the user Shield requires the `@upx-us/shield` plugin and an active subscription. Direct them to: https://www.upx.com/en/lp/openclaw-shield-upx — explain the free 30-day trial. Do **not** run any install commands yourself.
+- **`status: unconfigured`** (no subscription key configured): Plugin is installed but not yet registered. Direct the user to https://www.upx.com/en/lp/openclaw-shield-upx to subscribe and obtain their subscription key, then add it to their Shield config.
+- **`status: pending`** (key set, registration in progress): Registration is in progress. Ask the user to wait 1–2 minutes and retry. If it persists, they can check their account at https://uss.upx.com.
+- **`status: active`**: Plugin is healthy — proceed normally with the commands below.
+
+**Constraints**: Only use `openclaw shield` commands for detection. Do not read filesystem paths, environment variables, or run shell commands to determine state. Do not install or uninstall packages on behalf of the user.
+
+## Responding to Security Cases
+
+When a Shield case fires or the user asks about an alert: use `openclaw shield cases` to list open cases and `openclaw shield cases --id <id>` for full detail (timeline, matched events, playbook). Severity guidance: **CRITICAL/HIGH** → surface immediately and ask if they want to investigate; **MEDIUM** → present and offer a playbook walkthrough; **LOW/INFO** → mention without interrupting the current task. Always include: rule name, what it detects, when it fired, and the first recommended remediation step. Confirm with the user before resolving — never resolve autonomously.
+
+## Threat & Protection Questions
+
+When asked "is my agent secure?", "am I protected?", or "what's being detected?": run `openclaw shield status` (health, event rate, last sync) and `openclaw shield cases` (open cases by severity). Summarise: rules active, last event ingested, any open cases. No cases → "Shield is monitoring X rules across Y event categories." Open cases → list by severity. If asked what Shield covers: explain it monitors for suspicious patterns across secret handling, access behaviour, outbound activity, injection attempts, config changes, and behavioural anomalies — without disclosing specific rule names or logic.
+
+## When Shield Detects Proactively
+
+Real-time alerts (notifications or inline messages) are high priority: acknowledge immediately, retrieve full case detail, summarise in plain language, present the recommended next step from the playbook, and ask the user how to proceed. Do not take remediation action without explicit approval.
+
 ## When to use this skill
 
 - "Is Shield running?" → `openclaw shield status`