@upx-us/shield 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.5] — 2026-03-09
+
+### Added
+- **Smart degradation detection in `shield status`** — `getMonitorHealth()` now implements a three-gate algorithm to eliminate false positives from transient connectivity blips:
+  1. **Count gate**: `consecutiveFailures ≥ 5` (unchanged from v0.6.4)
+  2. **Time gate**: first failure in the current streak must be `> 3 minutes` old — a 1-minute connectivity blip (3 failures at 1m intervals) can never trigger DEGRADED
+  3. **Sticky recovery**: requires `≥ 2 consecutive successes` to clear DEGRADED — prevents flapping where one success clears it and then it degrades again next cycle
+- **`MonitorHealth` interface** exported from `src/case-monitor.ts` — new fields: `status: 'ok' | 'degraded' | 'unknown'`, `consecutiveSuccesses`, `degradedSinceMs`, `lastCheckMs`, `lastErrorMessage`
+  - `status: 'unknown'` before the monitor has completed its first check cycle
+- **`shield.status` RPC** — `caseMonitor` section now includes smart health fields: `status`, `degradedSince` (ISO string), `consecutiveFailures`, `lastError`, `lastCheck` (ISO string), and a pre-formatted `display` string (e.g. `⚠️ Case Monitor: DEGRADED — 7 consecutive failures since 2026-03-09T12:00:00.000Z. Last error: ...` or `✅ Case Monitor: ok`)
+- **7 new tests** covering all degradation scenarios: unknown initial state, transient blip (count gate), time gate, true DEGRADED positive, sticky recovery (1 success not enough), recovery (2 successes clear), and RPC handler shape
+
+---
+
+## [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

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) {
@@ -877,6 +879,10 @@ exports.default = {
             const creds = (0, config_1.loadCredentials)();
             const activated = state.activated || hasValidCredentials(creds);
             const caseStatus = (0, case_monitor_1.getCaseMonitorStatus)();
+            const monitorHealth = (0, case_monitor_1.getMonitorHealth)();
+            const caseMonitorDisplay = monitorHealth.status === 'degraded'
+                ? `⚠️ Case Monitor: DEGRADED — ${monitorHealth.consecutiveFailures} consecutive failures since ${monitorHealth.degradedSinceMs ? new Date(monitorHealth.degradedSinceMs).toISOString() : 'unknown'}. Last error: ${monitorHealth.lastErrorMessage}`
+                : `✅ Case Monitor: ok`;
             respond(true, {
                 activated,
                 running: state.running,
@@ -891,6 +897,16 @@ exports.default = {
                     intervalMs: caseStatus.intervalMs,
                     nextCheckInMs: caseStatus.nextCheckIn,
                     lastCheckAt: caseStatus.lastCheckAt,
+                    status: monitorHealth.status,
+                    degradedSince: monitorHealth.degradedSinceMs
+                        ? new Date(monitorHealth.degradedSinceMs).toISOString()
+                        : null,
+                    consecutiveFailures: monitorHealth.consecutiveFailures,
+                    lastError: monitorHealth.lastErrorMessage,
+                    lastCheck: monitorHealth.lastCheckMs
+                        ? new Date(monitorHealth.lastCheckMs).toISOString()
+                        : null,
+                    display: caseMonitorDisplay,
                 },
             });
         });

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

@@ -56,6 +56,15 @@ export interface CaseDetail extends CaseSummary {
 }
 export declare function initCaseMonitor(dataDir: string): void;
 export declare function notifyCaseMonitorActivity(): void;
+export interface MonitorHealth {
+    status: 'ok' | 'degraded' | 'unknown';
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    degradedSinceMs: number | null;
+    lastCheckMs: number | null;
+    lastErrorMessage: string | null;
+}
+export declare function getMonitorHealth(): MonitorHealth;
 export declare function getCaseMonitorStatus(): {
     intervalMs: number;
     nextCheckIn: number;
@@ -66,4 +75,6 @@ export declare function getPendingCases(): CaseSummary[];
 export declare function acknowledgeCases(caseIds: string[]): void;
 export declare function formatCaseNotification(c: CaseSummary | CaseDetail): string;
 export declare function _resetForTesting(): void;
+export declare function _simulateFailuresForTesting(count: number, firstFailureAgeMs: number): void;
+export declare function _simulateSuccessForTesting(): void;
 export {};

package/dist/src/case-monitor.js

@@ -37,12 +37,15 @@ exports.setCaseNotificationDispatcher = setCaseNotificationDispatcher;
 exports.setDirectSendDispatcher = setDirectSendDispatcher;
 exports.initCaseMonitor = initCaseMonitor;
 exports.notifyCaseMonitorActivity = notifyCaseMonitorActivity;
+exports.getMonitorHealth = getMonitorHealth;
 exports.getCaseMonitorStatus = getCaseMonitorStatus;
 exports.checkForNewCases = checkForNewCases;
 exports.getPendingCases = getPendingCases;
 exports.acknowledgeCases = acknowledgeCases;
 exports.formatCaseNotification = formatCaseNotification;
 exports._resetForTesting = _resetForTesting;
+exports._simulateFailuresForTesting = _simulateFailuresForTesting;
+exports._simulateSuccessForTesting = _simulateSuccessForTesting;
 const safe_io_1 = require("./safe-io");
 const client_1 = require("./rpc/client");
 const exclusions_1 = require("./exclusions");
@@ -161,6 +164,16 @@ let _dataDir = null;
 let _lastCheckAt = 0;
 let _lastEventAt = 0;
 let _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
+let _exclusionsWarnedOnce = false;
+let _consecutiveCheckFailures = 0;
+let _consecutiveSuccesses = 0;
+let _degradedSinceMs = null;
+let _firstFailureInStreakMs = null;
+let _lastCheckMs = null;
+let _lastErrorMessage = null;
+const DEGRADED_THRESHOLD = 5;
+const DEGRADED_TIME_GATE_MS = 3 * 60 * 1000;
+const RECOVERY_THRESHOLD = 2;
 function computeInterval() {
     if (_lastCheckAt === 0)
         return MIN_CHECK_INTERVAL_MS;
@@ -181,6 +194,59 @@ function initCaseMonitor(dataDir) {
 function notifyCaseMonitorActivity() {
     _lastEventAt = Date.now();
 }
+function getMonitorHealth() {
+    const now = Date.now();
+    const isDegraded = _consecutiveCheckFailures >= DEGRADED_THRESHOLD &&
+        _firstFailureInStreakMs !== null &&
+        (now - _firstFailureInStreakMs) >= DEGRADED_TIME_GATE_MS;
+    if (isDegraded && _degradedSinceMs === null) {
+        _degradedSinceMs = now;
+    }
+    let status;
+    if (_lastCheckMs === null) {
+        status = 'unknown';
+    }
+    else if (isDegraded) {
+        status = 'degraded';
+    }
+    else {
+        status = 'ok';
+    }
+    return {
+        status,
+        consecutiveFailures: _consecutiveCheckFailures,
+        consecutiveSuccesses: _consecutiveSuccesses,
+        degradedSinceMs: _degradedSinceMs,
+        lastCheckMs: _lastCheckMs,
+        lastErrorMessage: _lastErrorMessage,
+    };
+}
+function recordCheckFailure(message) {
+    const now = Date.now();
+    if (_consecutiveCheckFailures === 0) {
+        _firstFailureInStreakMs = now;
+    }
+    _consecutiveCheckFailures++;
+    _consecutiveSuccesses = 0;
+    _lastCheckMs = now;
+    _lastErrorMessage = message;
+    if (_degradedSinceMs === null &&
+        _consecutiveCheckFailures >= DEGRADED_THRESHOLD &&
+        _firstFailureInStreakMs !== null &&
+        (now - _firstFailureInStreakMs) >= DEGRADED_TIME_GATE_MS) {
+        _degradedSinceMs = now;
+    }
+}
+function recordCheckSuccess() {
+    _consecutiveSuccesses++;
+    _lastCheckMs = Date.now();
+    _lastErrorMessage = null;
+    if (_consecutiveSuccesses >= RECOVERY_THRESHOLD) {
+        _consecutiveCheckFailures = 0;
+        _firstFailureInStreakMs = null;
+        _degradedSinceMs = null;
+    }
+}
 function getCaseMonitorStatus() {
     const interval = computeInterval();
     const nextCheckIn = Math.max(0, (_lastCheckAt + interval) - Date.now());
@@ -210,7 +276,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')) {
+                recordCheckFailure(result.error ?? 'unknown error');
                 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 +289,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 +316,15 @@ async function checkForNewCases(config) {
         }
         state.lastCheckAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(stateFile, state);
+        recordCheckSuccess();
     }
     catch (err) {
-        log.warn('case-monitor', `Check failed: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = err instanceof Error ? err.message : String(err);
+        recordCheckFailure(msg);
+        log.warn('case-monitor', `Check failed: ${msg}`);
+        if (_consecutiveCheckFailures >= DEGRADED_THRESHOLD) {
+            log.warn('case-monitor', `[case-monitor] DEGRADED: ${_consecutiveCheckFailures} consecutive check failures — notifications may be silently dropped`);
+        }
     }
 }
 function getPendingCases() {
@@ -337,5 +422,37 @@ function getTimeAgo(isoDate) {
 function _resetForTesting() {
     _dataDir = null;
     _lastCheckAt = 0;
+    _lastEventAt = 0;
     _currentIntervalMs = MAX_CHECK_INTERVAL_MS;
+    _exclusionsWarnedOnce = false;
+    _consecutiveCheckFailures = 0;
+    _consecutiveSuccesses = 0;
+    _degradedSinceMs = null;
+    _firstFailureInStreakMs = null;
+    _lastCheckMs = null;
+    _lastErrorMessage = null;
+    _enqueueSystemEvent = null;
+    _requestHeartbeatNow = null;
+    _agentId = 'main';
+    _directSendFn = null;
+    _directSendTo = null;
+    _directSendChannel = null;
+}
+function _simulateFailuresForTesting(count, firstFailureAgeMs) {
+    const now = Date.now();
+    _firstFailureInStreakMs = now - firstFailureAgeMs;
+    _consecutiveCheckFailures = count;
+    _consecutiveSuccesses = 0;
+    _lastCheckMs = now - firstFailureAgeMs;
+    _lastErrorMessage = 'simulated failure';
+}
+function _simulateSuccessForTesting() {
+    _consecutiveSuccesses++;
+    _lastCheckMs = Date.now();
+    _lastErrorMessage = null;
+    if (_consecutiveSuccesses >= RECOVERY_THRESHOLD) {
+        _consecutiveCheckFailures = 0;
+        _firstFailureInStreakMs = null;
+        _degradedSinceMs = 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 });

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.3",
+  "version": "0.6.5",
   "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": "0.6.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.3",
+  "version": "0.6.5",
   "description": "Security monitoring plugin for OpenClaw agents — streams enriched security events to the Shield detection platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -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`