@upx-us/shield 0.6.7 → 0.6.10

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.10] — 2026-03-12
+
+### Fixed
+- **Local event buffer not populated in plugin mode** — `appendEvents` and `initEventStore` were implemented in the standalone bridge (`src/index.ts`) but never wired into the plugin-mode poll loop (`index.ts`). As a result, `openclaw shield logs` always returned "No events found" even when events were being sent successfully to the platform. Fixed by wiring the event store into the plugin-mode startup and poll cycle (#148).
+
+### Changed
+- **Local event buffer default increased to 250** — was 123. Provides better forensic coverage (~24h of normal activity) without significant storage impact. `SHIELD_LOCAL_EVENT_LIMIT` env var still overrides this. README and config updated (#148).
+- **Version corrected from 1.3.0 → 0.6.10** — the 1.3.0 version in `package.json` was premature; this release re-anchors versioning at the correct next increment after 0.6.8.
+
+### Added
+- **`openclaw.message_length_bytes` enrichment field** — message events now include the byte length of the message body as `openclaw.message_length_bytes`. Enables detection rules based on message size thresholds (#152).
+- **Event buffer diagnostics in `shield.status`** — `shield.status` RPC now includes an `eventBuffer` section showing: `enabled`, `path`, `total` events buffered, `oldest`/`newest` timestamps, and `redactedCount`. Makes it immediately diagnosable if the local log is empty or disabled (#148).
+
+### Docs
+- **Case investigation workflow in SKILL.md** — documents the standard 4-step forensic procedure: cases + logs + vault correlation for complete incident context. Covers correlating case timestamps, log event windows, and redaction vault lookups (#148, #151).
+- **Expanded uninstall documentation in README** — step-by-step uninstall guide covering plugin removal, local data cleanup (with file-by-file breakdown), and platform instance deactivation. Includes redaction vault retention warning (#151).
+
+---
+
+## [0.6.8] — 2026-03-10
+
+### Fixed
+- **curl credential redaction** — `curl -u "user:pass"`, `--user user:pass` (all quote variants), and `Authorization: Basic <base64>` are now redacted as `secret:HASH` before reaching the SIEM. Discovered via live credential leak (#137).
+
+---
+
 ## [0.6.7] — 2026-03-10
 
 ### Fixed

package/README.md

@@ -309,7 +309,7 @@ Shield stores a rolling log of recently sent events locally for offline inspecti
 **Location:** `~/.openclaw/shield/data/event-log.jsonl`
 
 **Defaults:**
-- Last **123 events** or **24 hours** (whichever limit is reached first)
+- Last **250 events** or **24 hours** (whichever limit is reached first)
 - Enabled by default
 - Events are stored **after redaction** — same data sent to the platform
 
@@ -327,7 +327,7 @@ openclaw shield logs --format json    # JSON output for piping
 | Variable | Default | Description |
 |---|---|---|
 | `SHIELD_LOCAL_EVENT_BUFFER` | `true` | Set to `false` to disable local storage |
-| `SHIELD_LOCAL_EVENT_LIMIT` | `123` | Maximum number of events to retain |
+| `SHIELD_LOCAL_EVENT_LIMIT` | `250` | Maximum number of events to retain |
 
 ---
 
@@ -498,24 +498,49 @@ Events generated during an expiry or quota period are permanently lost. Renew yo
 
 ## Uninstalling
 
+### 1. Remove the plugin
+
 ```bash
 openclaw plugins uninstall shield
 ```
 
-This removes the plugin code. To fully remove all local Shield data:
+### 2. Remove local Shield data (optional — recommended for privacy hygiene)
 
 ```bash
 rm -rf ~/.openclaw/shield/
 ```
 
-This deletes credentials, cursors, IP cache, and the redaction vault. 
+This removes all local files Shield writes at runtime:
+
+| File | Contents |
+|---|---|
+| `config.env` | HMAC secret and instance fingerprint |
+| `data/cursor.json` | Event cursor positions per log source |
+| `data/public-ip.cache` | Cached public IP for telemetry |
+| `data/instance-cache.json` | Cached instance metadata |
+| `data/exclusions.json` | Allowlist entries (suppress specific patterns) |
+| `data/case-monitor-state.json` | Case notification state (acknowledged case IDs) |
+| `data/event-log.jsonl` | Local event ring buffer (24h) |
+| `data/redaction-vault.json` | **Redaction token → original value mapping** |
+
+> ⚠️ **Redaction vault**: `data/redaction-vault.json` maps redaction tokens back to original values (secrets, hostnames, file paths). Once deleted, you cannot reverse-lookup redacted values from past events. Retain this file for as long as your data retention policy requires before deleting.
+
+### 3. Deactivate the platform instance
 
-> **Note:** The redaction vault (`data/redaction-vault.json`) contains the mapping from redaction tokens back to original values. Deleting it means you can no longer reverse-lookup redacted values from past events. Retain this file for as long as your data retention policy requires.
+Removing local files does **not** automatically deactivate your registration on the UPX platform.
 
-Platform-side instance data can be managed via [uss.upx.com](https://uss.upx.com).
+To fully remove your instance: log in to **[uss.upx.com](https://uss.upx.com)** → Instances → Delete.
+
+Until deactivated, the instance remains registered and may count against your subscription quota.
 
 ---
 
 ## Need help?
 
 Visit [uss.upx.com](https://uss.upx.com) or contact your Shield administrator.
+
+---
+
+## License & Distribution
+
+The skill wrapper is distributed under MIT-0 on ClaWHub as required by the platform. The underlying plugin and platform remain proprietary UPX Technologies, Inc. IP.

package/dist/index.js

@@ -52,6 +52,7 @@ 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 event_store_1 = require("./src/event-store");
 const updater_1 = require("./src/updater");
 const rpc_1 = require("./src/rpc");
 const inventory_1 = require("./src/inventory");
@@ -594,6 +595,9 @@ exports.default = {
                     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'));
+                    if (config.localEventBuffer) {
+                        (0, event_store_1.initEventStore)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'), { maxEvents: config.localEventLimit });
+                    }
                     const runtime = api.runtime;
                     if (runtime?.system?.enqueueSystemEvent && runtime?.system?.requestHeartbeatNow) {
                         const config = api.config;
@@ -826,6 +830,18 @@ exports.default = {
                                 state.lastSync = lastSync;
                                 state.captureSeenSinceLastSync = false;
                                 writeAllTimeStats({ eventsProcessed: accepted, lastSync });
+                                if (config.localEventBuffer) {
+                                    const summaries = envelopes.map(env => ({
+                                        ts: env.event.timestamp,
+                                        type: env.event.event_type || 'UNKNOWN',
+                                        tool: env.event.tool_name || 'unknown',
+                                        summary: env.event.tool_metadata?.['openclaw.display_summary'] || env.event.tool_name || 'event',
+                                        session: env.event.session_id || '?',
+                                        model: env.event.model || '?',
+                                        redacted: !!env.source?.plugin?.redaction_applied,
+                                    }));
+                                    (0, event_store_1.appendEvents)(summaries);
+                                }
                             }
                             else {
                                 state.consecutiveFailures++;
@@ -918,8 +934,11 @@ exports.default = {
                     vaultSummary = null;
                 }
             }
+            const hasSecret = !!creds?.hmacSecret && !PLACEHOLDER_VALUES.has((creds.hmacSecret || '').trim().toLowerCase());
+            const stateField = hasSecret ? (activated ? 'connected' : 'pending') : 'unconfigured';
             respond(true, {
                 activated,
+                state: stateField,
                 running: state.running,
                 lastPollAt: state.lastPollAt,
                 lastCaptureAt: state.lastCaptureAt,
@@ -946,6 +965,24 @@ exports.default = {
                 redaction: {
                     vault: vaultSummary,
                 },
+                eventBuffer: (() => {
+                    try {
+                        const { summarizeEvents: se } = require('./src/event-store');
+                        const rpcConfig = (0, config_1.loadConfig)({});
+                        const summary = se();
+                        return {
+                            enabled: rpcConfig.localEventBuffer,
+                            path: (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data', 'event-log.jsonl'),
+                            total: summary.total,
+                            oldest: summary.oldest,
+                            newest: summary.newest,
+                            redactedCount: summary.redactedCount,
+                        };
+                    }
+                    catch (_) {
+                        return { enabled: false, path: null, total: 0, oldest: null, newest: null, redactedCount: 0 };
+                    }
+                })(),
             });
         });
         api.registerGatewayMethod('shield.flush', ({ respond }) => {

package/dist/src/config.js

@@ -141,7 +141,7 @@ function loadConfig(overrides) {
         collectHostMetrics: overrides?.collectHostMetrics ?? (process.env.COLLECT_HOST_METRICS === 'true'),
         redactionEnabled: overrides?.redactionEnabled ?? (process.env.REDACTION_ENABLED !== 'false'),
         localEventBuffer: process.env.SHIELD_LOCAL_EVENT_BUFFER !== 'false',
-        localEventLimit: safeParseInt(process.env.SHIELD_LOCAL_EVENT_LIMIT, 123),
+        localEventLimit: safeParseInt(process.env.SHIELD_LOCAL_EVENT_LIMIT, 250),
         credentials,
     };
 }

package/dist/src/event-store.js

@@ -42,7 +42,7 @@ exports._getConfigForTesting = _getConfigForTesting;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const log = __importStar(require("./log"));
-const DEFAULT_MAX_EVENTS = 123;
+const DEFAULT_MAX_EVENTS = 250;
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 let _config = null;
 function initEventStore(dataDir, opts) {

package/dist/src/events/message/enrich.js

@@ -34,6 +34,7 @@ function enrich(tool, ctx) {
         const content = args.message || args.caption || '';
         if (content) {
             meta['openclaw.message_content'] = content.length > 500 ? content.slice(0, 500) : content;
+            meta['openclaw.message_length_bytes'] = String(Buffer.byteLength(String(content), 'utf8'));
         }
     }
     if (args.buffer) {

package/dist/src/redactor/strategies/secret-key.js

@@ -29,6 +29,14 @@ exports.secretKeyStrategy = {
             (0, counters_1.recordRedaction)('BEARER_TOKEN');
             return `${prefix}${hmac('secret', token)}`;
         });
+        result = result.replace(/(-u|--user)\s+(['"]?)([^\s'"]+:[^\s'"]*)\2/g, (_, flag, _quote, credential) => {
+            (0, counters_1.recordRedaction)('CURL_CREDENTIAL');
+            return `${flag} ${hmac('secret', credential)}`;
+        });
+        result = result.replace(/(Authorization:\s*Basic\s+)([A-Za-z0-9+/]+=*)/g, (_, prefix, token) => {
+            (0, counters_1.recordRedaction)('CURL_CREDENTIAL');
+            return `${prefix}${hmac('secret', token)}`;
+        });
         result = result.replace(/((?:SECRET|TOKEN|KEY|PASSWORD|API_KEY)=)(\S+)/gi, (_, prefix, secret) => {
             const prefixUpper = prefix.toUpperCase();
             if (prefixUpper.startsWith('PASSWORD'))

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "shield",
   "name": "OpenClaw Shield",
-  "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.6.7",
+  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.6.10",
   "skills": [
     "./skills"
   ],
@@ -54,7 +54,7 @@
   "uiHints": {
     "installationKey": {
       "label": "Installation Key",
-      "description": "One-time key from your trial signup at https://www.upx.com/en/lp/openclaw-shield-upx — Required for first-time activation only. After activation, log in at https://uss.upx.com"
+      "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": "0.6.5",
+    "skillVersion": "0.6.6",
     "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.7",
+  "version": "0.6.10",
   "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",
@@ -58,7 +58,10 @@
     "threat-detection",
     "agent-protection",
     "audit",
+    "protect",
     "realtime-monitoring",
+    "event-monitoring",
+    "security-monitoring",
     "dlp",
     "anomaly-detection"
   ],

package/skills/shield/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-shield-upx
-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."
+description: "Security monitoring and threat detection for OpenClaw agents — protect your agent with real-time SIEM, detect threats, monitor agent activity, and audit events. Use when: user asks about security status, Shield health, event logs, redaction vault, setting up agent protection, enabling SIEM, detecting threats, monitoring agent activity, or auditing agent actions. 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."
@@ -37,12 +37,40 @@ Shield requires the `@upx-us/shield` plugin and an active subscription.
 
 ## 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.
+Before responding to ANY Shield-related request, run `openclaw shield status` and interpret the result:
+
+### State A — Plugin not installed
+(command not found, or exit code non-zero with plugin_not_found)
+Respond with:
+> Shield is not installed yet. Start your free 30-day trial at:
+> https://www.upx.com/en/lp/openclaw-shield-upx
+>
+> Then install the plugin:
+> ```
+> openclaw plugins install @upx-us/shield
+> openclaw plugins run shield setup
+> ```
+
+### State B — Plugin installed but no installationKey
+(status contains installationKey: null or state: "unconfigured")
+Respond with:
+> Shield is installed but not activated. Sign up for a trial at:
+> https://www.upx.com/en/lp/openclaw-shield-upx
+>
+> Once you have your installation key, run:
+> ```
+> openclaw plugins run shield setup
+> ```
+
+### State C — Key set but not yet activated
+(status contains state: "pending" or state: "unregistered")
+Respond with:
+> Shield has an installation key but hasn't activated yet. This usually takes under a minute.
+> If it has been more than 5 minutes, check your key at https://uss.upx.com or contact support.
+
+### State D — Fully active
+(status contains state: "connected" or connected: true)
+Proceed normally. No onboarding message needed.
 
 **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.
 
@@ -50,6 +78,20 @@ Before responding to any Shield-related request, run `openclaw shield status` an
 
 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.
 
+## Case Investigation Workflow
+
+When a Shield case fires, correlate three data sources to determine true positive vs. false positive:
+
+**Step 1 — Case detail** (`openclaw shield cases show <CASE_ID>`): What triggered the rule. Note the case timestamp — it anchors the correlation window.
+
+**Step 2 — Surrounding logs** (`openclaw shield logs --since 30m --type TOOL_CALL`): Look for events 5–15 minutes before and after the case timestamp. Reveals if the alert was isolated or part of a sequence.
+
+**Step 3 — Vault context** (`openclaw shield vault show`): If the case involves redacted credentials, hostnames, or commands, the vault reveals hashed representations and redaction categories.
+
+**Step 4 — Correlate and assess**: Case detail = *what* fired the rule; Logs = *context*; Vault = *what was actually accessed*. Present findings and ask whether to resolve, investigate further, or add to the allowlist.
+
+Note: a future `openclaw shield investigate <CASE_ID>` helper command will automate this workflow.
+
 ## 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.
@@ -104,6 +146,25 @@ RPC responses include a `display` field with pre-formatted text. When present, u
 
 When discussing a case, offer action buttons (resolve, false positive, investigate) via the message tool so users can act with one tap.
 
+## Uninstalling
+
+To fully remove Shield:
+
+1. Uninstall the plugin:
+   ```
+   openclaw plugins uninstall shield
+   ```
+
+2. Optionally remove local Shield data:
+   ```
+   rm -rf ~/.openclaw/shield/
+   ```
+   Files removed include: `config.json`, `data/event-buffer.jsonl`, `data/redaction-vault.json`, `data/cursor.json`, `data/instance.json`, `logs/shield.log`, `logs/bridge.log`, `state/monitor.json`.
+
+   ⚠️ Deleting `data/redaction-vault.json` removes the ability to reverse-lookup past redacted values. Check your data retention needs before deleting.
+
+3. Deactivate your instance at [uss.upx.com](https://uss.upx.com) — local uninstall does not deactivate your platform subscription or instance.
+
 ## Notes
 
 - Shield does not interfere with agent behavior or performance