@upx-us/shield 0.2.16-beta → 0.3.5

package/README.md

@@ -5,118 +5,243 @@
 
 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.
+**Shield is a local collector.** It captures agent activity, redacts sensitive data, and forwards clean telemetry to the UPX platform at [uss.upx.com](https://uss.upx.com) — where security rules, correlation, alerting, playbooks, and case management give your team full visibility. The plugin itself stays lean and transparent; all the heavy lifting happens on the platform side.
+
+```
+Your Agent → Shield (local: capture + redact) → UPX Platform (analysis, alerts, detections)
+```
 
 ---
 
 ## Prerequisites
 
 - **OpenClaw Gateway** installed and running (`openclaw gateway status`)
-- An **installation key** provided by your Shield administrator (looks like: `A1B2C3D4E5F6...`)
+- An **Installation Key** provided by your Shield administrator (looks like: `A1B2C3D4E5F6...`)
 
 ---
 
-## Step 1 — Install the plugin
+## Quick Start — Suggested bot prompt
 
-```bash
-openclaw plugins install @upx-us/shield@beta
-```
+Copy this prompt and paste it to your AI agent. Replace `<YOUR_KEY>` with your Installation Key:
+
+> Run `openclaw plugins install @upx-us/shield` to install the Shield plugin. Then update `~/.openclaw/openclaw.json`: add `"shield"` to `plugins.allow`, and under `plugins.entries.shield.config` set `"installationKey": "<YOUR_KEY>"`. Then run `openclaw gateway restart`. Confirm Shield is active with `openclaw shield status`.
+
+That's it. The bot installs the plugin, configures the key, restarts the gateway, and Shield activates automatically.
 
 ---
 
-## Step 2 — Activate Shield
+## Manual Installation
 
-Run the setup wizard:
+### Step 1 — Install the plugin
 
 ```bash
-npx -p @upx-us/shield@beta shield-setup
+openclaw plugins install @upx-us/shield
 ```
 
-The wizard will ask for your installation key:
-
+> OpenClaw will show a security warning about environment variable access and network calls — this is **expected** for a security monitoring plugin. Add `"shield"` to `plugins.allow` in `openclaw.json` to suppress it.
+
+### Step 2 — Add your Installation Key
+
+Open `~/.openclaw/openclaw.json` and add the following:
+
+```json
+{
+  "plugins": {
+    "allow": ["shield"],
+    "entries": {
+      "shield": {
+        "config": {
+          "installationKey": "YOUR_KEY_HERE"
+        }
+      }
+    }
+  }
+}
 ```
-🛡️  OpenClaw Shield Setup
-==========================
 
-Installation Key (from Shield portal): ████████████████████████
+> **Note:** Each Installation Key is single-use. The plugin exchanges it for credentials on first startup and saves them locally — you can remove `installationKey` from the config after activation.
+
+### Step 3 — Restart the Gateway
 
-Connecting... ok
-Registering instance... ok
-✅ Shield activated!
-   Restart your OpenClaw Gateway to start monitoring.
+```bash
+openclaw gateway restart
 ```
 
-> **Note:** Each installation key is single-use. If the key is rejected, request a new one from your administrator.
+Shield auto-registers, saves credentials to `~/.openclaw/shield/config.env`, and starts monitoring.
 
 ---
 
-## Step 3 — Restart the Gateway
+## Alternative: CLI Activation
+
+If the config-based flow didn't work (e.g. the key was added to the wrong path), you can activate directly:
 
 ```bash
+openclaw shield activate <YOUR_KEY>
 openclaw gateway restart
 ```
 
 ---
 
-## Step 4 — Verify it's running
+## Verify it's running
 
 ```bash
 openclaw shield status
 ```
 
-Expected output:
+**When activated:**
 
 ```
-🛡️  Shield Status
-─────────────────────────────
-  Running:      true
-  Version:      0.2.x-beta
-  Last poll:    a few seconds ago
-  Events sent:  12
-  Failures:     0
+OpenClaw Shield — v0.3.0  (5s ago)
+
+── Plugin Health ─────────────────────────────
+  Connection:   ✅ Connected
+  Version:      0.3.0
+  Instance:     a1b2c3d4…
+  Last poll:    5s ago
+  Events sent:  1,842  (all-time)
+  Quarantine:   0  (all-time)
+  Failures:     0  (consecutive)
+  Daemon PID:   12345
+  Session:      4h 12m
+
+── Activity ──────────────────────────────────
+
+📡 Last sync  (29s ago — 5 events)
+  TOOL_RESULT          ████████  3
+  TOOL_CALL            █████     2
+
+📊 This session  (since restart 4h 12m ago — 142 events)
+  TOOL_CALL            ████████  78
+  TOOL_RESULT          ███████   64
+
+🔒 Redactions  (10x this session)
+  hostname data            redacted 5x
+  username data            redacted 5x
+  (original values stored encrypted locally — never transmitted)
 ```
 
-Once `Running: true` and `Last poll` is recent, Shield is live.
+**When not activated:**
+
+```
+OpenClaw Shield — v0.3.0
+
+  Status: Loaded (not activated)
+
+  To activate, provide your Installation Key:
+    1. openclaw shield activate <YOUR_KEY>
+    2. Add to openclaw.json:
+         plugins.entries.shield.config.installationKey = "<YOUR_KEY>"
+       Then: openclaw gateway restart
+
+  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield
+```
 
 ---
 
-## What data is collected
+## Understanding the status output
+
+### Event types
 
-Shield captures **agent activity events** — the things your OpenClaw agent does:
+Shield captures what your agent *does* — not what it says. Each line in the Activity section represents a category of tool calls:
 
-| Event type | Examples |
+| Event type | What it means |
 |---|---|
-| 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 and direction — never message content |
-| Sessions spawned | Sub-agent launches |
+| `TOOL_CALL` | A tool was invoked by the agent (exec, read, write, web search, etc.) |
+| `TOOL_RESULT` | The result returned from a tool call |
+| `exec` | Shell command executed |
+| `file` | File read, written, or edited |
+| `web` | URL fetched, web search, or browser action |
+| `message` | Message sent via a channel (Telegram, WhatsApp, etc.) |
+| `sessions_spawn` | A sub-agent was launched |
+| `browser` | Browser automation action |
+| `cron` | A scheduled task fired |
+
+Shield captures what your agent *does* — tool invocations and their results. Each event carries metadata about the operation (tool name, paths, URLs) along with a redacted summary of the result.
+
+### Quarantine
+
+Quarantine counts events that failed local schema validation and were **held back** rather than forwarded to the platform. They are not lost — they're written to `~/.openclaw/shield/data/quarantine.jsonl` for inspection. A non-zero quarantine count usually means a plugin version mismatch between the collector and the platform schema; upgrading Shield typically resolves it.
 
-Shield does **not** collect:
-- Message content or conversation history
-- File contents
-- Credentials or secrets (automatically redacted before transmission)
+### Redactions
+
+Redaction runs locally before anything leaves your machine. The counts shown are **occurrences** — how many times that category of sensitive data was detected and replaced with a reversible token (e.g. `host:a3f9b1c2`, `user:7b2c4a1f`). The original values are stored in an encrypted local vault (`~/.openclaw/shield/data/redaction-vault.json`) so they can be recovered for investigation — they are never transmitted to the platform.
+
+### All-time vs. session
+
+- **Events sent / Quarantine** in the health section = all-time totals, persisted across gateway restarts
+- **This session** in the activity section = since the last gateway restart
+- **Last sync** = the most recent poll cycle only
+
+To see the full picture — detections, alerts, rules, and cases — visit [uss.upx.com](https://uss.upx.com).
+
+---
+
+## What data is collected
+
+Shield captures agent activity locally, applies on-device redaction, and forwards telemetry to the UPX platform.
+
+| Data type | Captured | Redacted on-device before transmission |
+|---|---|---|
+| Tool name | ✅ | — |
+| Command strings | ✅ | ✅ secrets, paths replaced with tokens |
+| File paths | ✅ | ✅ username segment replaced with token |
+| Tool result output | ✅ | ✅ truncated and redacted |
+| Hostname | ✅ | ✅ replaced with token |
+| Username | ✅ | ✅ replaced with token |
+| URLs | ✅ | — |
+| API keys detected in commands | ✅ | ✅ replaced with token |
+
+> **How redaction works:** sensitive values are replaced with deterministic `category:hash` tokens (e.g. `host:a3f9b1c2`, `user:7b2c4a1f`) before leaving your machine. The mapping from token → original value is stored in an encrypted local vault (`~/.openclaw/shield/data/redaction-vault.json`, AES-256-GCM) so your team can reverse-lookup locally if needed. Original values are never transmitted to the platform.
 
 ---
 
 ## How your data is protected
 
-**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]`.
+**Redaction** runs locally before any data leaves your machine. The redactor detects hostnames, usernames, file paths, API keys, and secrets — replacing them with deterministic `category:hash` tokens. The token→original mapping is stored in an AES-256-GCM encrypted vault (`~/.openclaw/shield/data/redaction-vault.json`, mode 0600). Original values are never transmitted.
 
-**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.
+**Authentication** uses HMAC-SHA256 with a per-instance signing key. Every request is signed — requests with invalid signatures are rejected by the platform.
 
-**Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600 — readable only by your user) and are never transmitted.
+**Credentials** are stored locally at `~/.openclaw/shield/config.env` (mode 0600) and are never transmitted.
+
+---
+
+## Upgrading
+
+- Standard upgrade command: `openclaw plugins update shield`
+- Cursors and credentials are preserved across upgrades
+- After upgrade verify with: `openclaw shield status`
+- See CHANGELOG.md for version history
 
 ---
 
 ## 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. |
+**Shield shows "not activated"**
+→ Get your Installation Key at [uss.upx.com](https://uss.upx.com) → APPS → OpenClaw Shield → Install
+→ Add to `openclaw.json`:
+```json
+"plugins": { "entries": { "shield": { "config": { "installationKey": "YOUR_KEY" } } } }
+```
+→ Restart OpenClaw
+
+**Activated but no events reaching platform**
+→ Run `openclaw shield status` — check Failures count and Last sync time
+→ Verify network access to the Shield API endpoint (check your config for the URL)
+→ Enable debug logging: set `LOG_LEVEL=debug` in your environment
+
+**High CPU or memory usage**
+→ Increase poll interval in config: `"pollIntervalMs": 60000` (default is 30000ms)
+→ Shield processes at most 5000 events per poll cycle regardless of backlog size
+
+**Cursor file issues**
+→ Cursor file location: `~/.openclaw/shield/data/cursors.json`
+→ To reset: delete the file — Shield will reinitialize on next poll (some events may re-process)
+
+**Enable debug logging**
+→ `LOG_LEVEL=debug openclaw start` — verbose output including poll cycles and send results
+
+**Dry-run mode (no events sent)**
+→ Add `"dryRun": true` to plugin config — events are processed and logged but never transmitted
 
 ---
 
@@ -126,10 +251,10 @@ Shield does **not** collect:
 openclaw plugins uninstall shield
 ```
 
-Stops the monitoring bridge and removes the plugin. Your instance record on the platform is preserved for audit purposes.
+Stops the monitoring bridge and removes the plugin.
 
 ---
 
 ## Need help?
 
-Contact your Shield administrator or reach out to UPX support at [upx.com](https://upx.com).
+Visit the Shield portal at [uss.upx.com](https://uss.upx.com) or contact your Shield administrator. For UPX support, reach out at [upx.com](https://upx.com).

package/dist/index.d.ts

@@ -1,20 +1,18 @@
-/**
- * OpenClaw Shield — Plugin Entry Point
- *
- * This file is the OpenClaw plugin entry point, declared in package.json
- * under `openclaw.extensions`. It registers the Shield plugin with the
- * OpenClaw Gateway and starts the monitoring bridge as a managed service.
- *
- * The monitoring bridge runs as a background service within the Gateway
- * process, polling session files and forwarding enriched security events
- * to the Shield detection platform.
- *
- * Dual-mode design:
- *   - Plugin mode: this file, registered via api.registerService()
- *   - Standalone mode: src/index.ts, runs directly via `shield-bridge`
- */
+import { ShieldCredentials } from './src/config';
+export declare function performAutoRegistration(installationKey: string): Promise<ShieldCredentials | null>;
+export declare function resolveInstallationKey(pluginConfig: Record<string, unknown>): string | null;
+export declare function maskPluginConfigForLogs(pluginConfig: Record<string, unknown>): Record<string, unknown>;
+export declare function createSingleflightRunner(task: () => Promise<void>): () => Promise<void>;
+interface StartGuard {
+    begin: () => boolean;
+    endSuccess: () => void;
+    endFailure: () => void;
+    reset: () => void;
+}
+export declare function createStartGuard(): StartGuard;
 interface OpenClawPluginAPI {
     config?: Record<string, unknown>;
+    pluginConfig?: Record<string, unknown>;
     logger: {
         info(msg: string): void;
         warn(msg: string): void;