@upx-us/shield 0.2.12-beta → 0.2.14-beta

package/README.md

@@ -1,43 +1,84 @@
 # OpenClaw Shield
 
 > **This plugin requires an active OpenClaw Shield subscription provided by UPX.**
-> For more information, visit [upx.com](https://upx.com).
+> For access or more information, visit [upx.com](https://upx.com).
 
 Real-time security monitoring for your OpenClaw agents — powered by the UPX Shield detection platform.
 
 Shield runs silently alongside your OpenClaw Gateway, captures agent activity, and streams it to the Shield platform where security rules, playbooks, and case management give your team full visibility.
 
-📖 **New?** See the [Getting Started guide](https://github.com/UPX-US/openclaw-shield-plugin/blob/main/docs/GETTING_STARTED.md) for a step-by-step walkthrough.
+---
 
-## Install
+## Prerequisites
+
+- **OpenClaw Gateway** installed and running (`openclaw gateway status`)
+- An **installation key** provided by your Shield administrator (looks like: `A1B2C3D4E5F6...`)
+
+---
+
+## Step 1 — Install the plugin
 
 ```bash
 openclaw plugins install @upx-us/shield@beta
 ```
 
-Restart the Gateway after install. Shield starts automatically.
+---
 
-## Activate
+## Step 2 — Activate Shield
 
-You'll need an **installation key** from your Shield admin. Run the setup wizard:
+Run the setup wizard:
 
 ```bash
 npx -p @upx-us/shield@beta shield-setup
 ```
 
+The wizard will ask for your installation key:
+
 ```
 🛡️  OpenClaw Shield Setup
 ==========================
 
-Installation Key (from Shield portal): ████████████████
+Installation Key (from Shield portal): ████████████████████████
+
 Connecting... ok
 Registering instance... ok
-
 ✅ Shield activated!
    Restart your OpenClaw Gateway to start monitoring.
 ```
 
-That's it. Your instance is now registered and events will start flowing to the Shield platform.
+> **Note:** Each installation key is single-use. If the key is rejected, request a new one from your administrator.
+
+---
+
+## Step 3 — Restart the Gateway
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## Step 4 — Verify it's running
+
+```bash
+openclaw shield status
+```
+
+Expected output:
+
+```
+🛡️  Shield Status
+─────────────────────────────
+  Running:      true
+  Version:      0.2.x-beta
+  Last poll:    a few seconds ago
+  Events sent:  12
+  Failures:     0
+```
+
+Once `Running: true` and `Last poll` is recent, Shield is live.
+
+---
 
 ## What data is collected
 
@@ -48,49 +89,47 @@ Shield captures **agent activity events** — the things your OpenClaw agent doe
 | Shell commands | `git status`, `npm install`, `curl` calls |
 | File operations | Read, write, edit — path and action only |
 | Web requests | URLs fetched, search queries, browser actions |
-| Messages sent | Channel, direction — never message content |
+| Messages sent | Channel and direction — never message content |
 | Sessions spawned | Sub-agent launches |
 
 Shield does **not** collect:
 - Message content or conversation history
 - File contents
-- Credentials or secrets (see Redaction below)
-- Anything outside of OpenClaw agent activity
+- Credentials or secrets (automatically redacted before transmission)
+
+---
 
 ## How your data is protected
 
-**Redaction** runs locally before any data leaves your machine. The redactor automatically strips:
+**Redaction** runs locally before any data leaves your machine. The redactor automatically strips API keys, tokens, passwords, and any string matching known secret patterns — replacing them with `[REDACTED]`.
 
-- API keys, tokens, and passwords
-- File paths that look like sensitive locations (`~/.ssh`, credential files)
-- Usernames and hostnames from command output
-- Any string matching known secret patterns
+**Transmission** uses HTTPS with TLS 1.2+. Each instance has a unique signing key — your data is tied to your instance only and cannot be replayed or forged.
 
-You can verify what's being sent at any time by running:
+**Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600 — readable only by your user) and are never transmitted.
 
-```bash
-openclaw shield status
-```
+---
 
-**Transmission** uses HTTPS with TLS 1.2+. Each instance has a unique signing key — your data is tied to your instance only and cannot be replayed or forged.
+## Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| `Running: false` after restart | Check `openclaw shield status` for failure count. Re-run the setup wizard if credentials are missing. |
+| High failure count | Shield backs off automatically. Run `openclaw shield flush` to retry immediately. |
+| Installation key rejected | Keys are single-use. Request a new one from your administrator. |
+| Events not appearing in portal | Allow 1–2 minutes after first activation. Check that `Last poll` is recent. |
 
-**Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600 — readable only by your user). They are never transmitted.
+---
 
-## Check status
+## Uninstalling
 
 ```bash
-openclaw shield status
+openclaw plugins uninstall shield
 ```
 
-```
-Shield v0.2.1-beta  (12s ago)
-  Running:    true
-  Last poll:  2026-02-22T22:40:31Z
-  Events:     1,204
-  Quarantine: 0
-  Failures:   0
-```
+Stops the monitoring bridge and removes the plugin. Your instance record on the platform is preserved for audit purposes.
+
+---
 
 ## Need help?
 
-Contact your Shield administrator or reach out to UPX support.
+Contact your Shield administrator or reach out to UPX support at [upx.com](https://upx.com).

package/dist/src/index.js

@@ -134,6 +134,12 @@ async function poll() {
                 }
             }
             else {
+                // No new entries this poll — but still commit cursors so that
+                // initCursorsForDir positions (set to current file sizes) are
+                // persisted. Without this, the next poll re-initialises cursors
+                // to the NEW current size and silently skips any events that
+                // arrived between polls.
+                (0, fetcher_1.commitCursors)(config, []);
                 consecutiveFailures = 0;
             }
         }

package/dist/src/sender.js

@@ -49,6 +49,9 @@ const log = __importStar(require("./log"));
 const version_1 = require("./version");
 const BATCH_SIZE = 100;
 exports.REQUEST_TIMEOUT_MS = 30_000;
+/** Minimum delay between consecutive batch POSTs (ms). Prevents Cloud Armor rate-limit
+ *  from triggering during backfill bursts. 200ms ≈ 5 req/s = 300 req/min (well under 600/min limit). */
+const INTER_BATCH_DELAY_MS = 200;
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -97,6 +100,9 @@ async function sendEvents(events, config) {
     }
     const results = [];
     for (let i = 0; i < events.length; i += BATCH_SIZE) {
+        // Throttle between batches to avoid Cloud Armor rate-limit during backfill
+        if (i > 0)
+            await new Promise(r => setTimeout(r, INTER_BATCH_DELAY_MS));
         const batch = events.slice(i, i + BATCH_SIZE);
         const batchNum = Math.floor(i / BATCH_SIZE) + 1;
         const payload = JSON.stringify({ entries: batch });

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "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",
+  "version": "0.2.14-beta",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.2.12-beta",
+  "version": "0.2.14-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",