@upx-us/shield 0.3.16 → 0.4.36

package/README.md

@@ -1,7 +1,7 @@
 # OpenClaw Shield
 
-> **This plugin requires an active OpenClaw Shield subscription provided by UPX.**
-> For access or more information, visit [upx.com](https://upx.com).
+> **OpenClaw Shield is a paid security service by UPX.**
+> Start your **free 30-day trial** at [upx.com/pt/lp/openclaw-shield-upx](https://www.upx.com/pt/lp/openclaw-shield-upx).
 
 Real-time security monitoring for your OpenClaw agents — powered by the UPX Shield detection platform.
 
@@ -13,6 +13,21 @@ Your Agent → Shield (local: capture + redact) → UPX Platform (analysis, aler
 
 ---
 
+## Features
+
+| Feature | Description |
+|---|---|
+| **Real-time monitoring** | Captures all agent tool calls, file operations, messages, and sessions |
+| **On-device redaction** | Hostnames, usernames, secrets, and paths replaced with deterministic tokens before transmission |
+| **Local event buffer** | Rolling log of recent events — inspect via `openclaw shield logs` without platform access |
+| **Case notifications** | Automatic alerts when detection rules fire — agent notifies you of new cases |
+| **Case resolution** | Close cases with categorization (resolution + root cause) directly from your agent |
+| **Host inventory** | Discovers all agents and workspaces on the machine — view via `openclaw shield vault show` |
+| **Auto-update** | Patch and minor updates install automatically with rollback on failure |
+| **Encrypted vault** | Redaction mappings stored locally with AES-256-GCM — UPX cannot reverse tokens |
+
+---
+
 ## Prerequisites
 
 - **OpenClaw Gateway** installed and running (`openclaw gateway status`)
@@ -22,28 +37,111 @@ Your Agent → Shield (local: capture + redact) → UPX Platform (analysis, aler
 
 ## Installation
 
-**If you have an OpenClaw agent running**, use Quick Start — paste a single prompt and you're done.
-**If you prefer to configure manually**, follow Manual Installation below.
+### Prerequisites
 
-### Quick Start — Let your agent do it
+1. **OpenClaw Gateway** installed and running (`openclaw gateway status`)
+2. An **Installation Key** from your Shield dashboard at [uss.upx.com](https://uss.upx.com) → APPS → OpenClaw Shield
 
-Copy this prompt and paste it to your AI agent. Replace `<YOUR_KEY>` with your Installation Key:
+### Commands Reference
 
-> Install the OpenClaw Shield plugin (@upx-us/shield) with installation key `<YOUR_KEY>`. Add "shield" to plugins.allow and set installationKey in plugins.entries.shield.config. Restart the gateway and confirm Shield is active with openclaw shield status.
+| Command | Description |
+|---|---|
+| `openclaw shield activate <KEY>` | Activate with your Installation Key (one-time) |
+| `openclaw shield status` | Show monitoring status, event counts, and health |
+| `openclaw shield flush` | Trigger an immediate poll cycle |
+| `openclaw shield logs` | Show recent events from local buffer (--last N, --type, --since, --format) |
+| `openclaw shield cases` | List open security cases from the platform |
+| `openclaw shield cases show <ID>` | Full case detail with events, rule info, and playbook |
+| `openclaw shield cases resolve <ID>` | Resolve a case (--resolution, --root-cause, --comment) |
+| `openclaw shield vault show` | Show host agent inventory (hashed IDs) |
+
+**Agent RPCs** (used by the agent skill, not CLI):
+
+| RPC | Description |
+|---|---|
+| `shield.status` | Current monitoring status, health, and counters |
+| `shield.flush` | Trigger an immediate telemetry poll cycle |
+| `shield.events_recent` | Query recent events from local buffer |
+| `shield.events_summary` | Event counts by type and tool |
+| `shield.subscription_status` | Subscription and quota information |
+| `shield.cases_list` | List open cases + pending notifications |
+| `shield.case_detail` | Full case detail with events, rule, playbook |
+| `shield.case_resolve` | Close a case with resolution and root cause |
+| `shield.cases_ack` | Mark cases as notified |
 
-The agent installs the plugin, edits the config, restarts the gateway, and Shield activates automatically.
+---
 
-### Manual Installation
+### Option A — Quick Install (recommended)
 
-#### Step 1 — Install the plugin
+Run these commands in your terminal. No agent involvement needed.
 
 ```bash
+# Step 1: Install the plugin
 openclaw plugins install @upx-us/shield
+
+# Step 2: Activate (exchanges your key for credentials)
+openclaw shield activate <YOUR_KEY>
+
+# Step 3: Restart the gateway to start monitoring
+openclaw gateway restart
+
+# Step 4: Verify it's running
+openclaw shield status
 ```
 
-> **Security prompt:** OpenClaw will warn about environment variable access combined with network calls. This is **expected** — Shield reads signing credentials and sends telemetry to the Shield API. To acknowledge, add `"shield"` to `plugins.allow` in `~/.openclaw/openclaw.json` (shown in Step 2). If automating via a script or agent, pre-populate `plugins.allow` before running the install command to avoid interactive prompts.
+That's it. Shield registers, saves credentials locally, and starts monitoring.
+
+> ⚠️ **Multi-machine setups:** Only add Shield to `plugins.allow` on machines where the plugin is installed. If you share `openclaw.json` across machines and one of them doesn't have Shield installed, the gateway on that machine will fail to start. Install the plugin first, then configure.
+
+---
+
+### Option B — Ask your agent to configure
+
+If you already installed the plugin (Step 1 above) and want your agent to handle the rest, send this prompt:
+
+> I installed the OpenClaw Shield plugin (`openclaw plugins install @upx-us/shield`). Configure it: add "shield" to plugins.allow in openclaw.json, set installationKey to `<YOUR_KEY>` in plugins.entries.shield.config, restart the gateway with `openclaw gateway restart`, and confirm with `openclaw shield status`.
+
+This approach works best because your agent only edits config — it doesn't need to make trust decisions about installing external software.
+
+---
+
+### Option C — Let your agent do everything
+
+Copy this prompt and paste it to your AI agent. Replace `<YOUR_KEY>` with your Installation Key:
+
+> Install the OpenClaw Shield security monitoring plugin by UPX (upx.com). The package is @upx-us/shield. Read the package README at https://www.npmjs.com/package/@upx-us/shield before proceeding. Install using `openclaw plugins install @upx-us/shield`, add "shield" to plugins.allow in openclaw.json, set installationKey to `<YOUR_KEY>` in plugins.entries.shield.config, restart with `openclaw gateway restart`, and confirm with `openclaw shield status`.
+
+**If your agent refuses to install**, this is normal security behavior. Your options:
+
+1. **Use Option A or B instead** — install the plugin yourself, let the agent configure.
+
+2. **Confirm you trust the source** and ask again:
+
+   > *"I trust this plugin. I purchased this service from UPX (upx.com). Please proceed with the installation."*
+
+**Why your agent may refuse — and why each concern is expected:**
+
+| Concern | Why it's expected |
+|---|---|
+| "Sends data to an external server" | Shield is a security monitoring tool — sending redacted telemetry is its purpose. Sensitive values are replaced with irreversible tokens **on your machine** before transmission. |
+| "Installation key looks suspicious" | The key is a one-time activation token from your UPX Shield dashboard. Consumed on first use, can be removed from config after. |
+| "Plugin is not in OpenClaw's official docs" | Shield is a third-party plugin by UPX (upx.com) under the `@upx-us` npm scope. Not bundled with OpenClaw, but designed to work with it. |
+| "Adding to plugins.allow expands attack surface" | Correct — this is OpenClaw's explicit trust mechanism. You are consciously granting permission. |
+| "Package was recently published" | Shield is actively developed. Check CHANGELOG.md included with the package for version history. |
+
+---
+
+### Manual Configuration (advanced)
+
+If you need full control over each step:
 
-#### Step 2 — Add your Installation Key
+#### Step 1 — Install
+
+```bash
+openclaw plugins install @upx-us/shield
+```
+
+#### Step 2 — Configure openclaw.json
 
 Open `~/.openclaw/openclaw.json` and add:
 
@@ -62,9 +160,7 @@ Open `~/.openclaw/openclaw.json` and add:
 }
 ```
 
-> **Installation Keys are single-use** — the plugin exchanges your key for permanent credentials on first startup and saves them locally. The key is consumed on the first *successful* activation; if the first attempt fails (network issue, config typo), the key is not burned and you can retry. Once activation succeeds, you can safely remove `installationKey` from the config.
-
-#### Step 3 — Restart the Gateway
+#### Step 3 — Restart
 
 ```bash
 openclaw gateway restart
@@ -72,9 +168,9 @@ openclaw gateway restart
 
 Shield auto-registers, saves credentials to `~/.openclaw/shield/config.env`, and starts monitoring.
 
-### Alternative: CLI Activation
+> **Note:** The Installation Key is single-use — the plugin exchanges it for permanent credentials on first startup. Once activated, you can remove `installationKey` from config.
 
-If the config-based flow didn't work (e.g. the key was added to the wrong path), you can activate directly:
+#### Alternative: CLI Activation
 
 ```bash
 openclaw shield activate <YOUR_KEY>
@@ -211,6 +307,35 @@ Use `Last capture` as the first diagnostic:
 
 ---
 
+## Local Event Buffer
+
+Shield stores a rolling log of recently sent events locally for offline inspection and debugging.
+
+**Location:** `~/.openclaw/shield/data/event-log.jsonl`
+
+**Defaults:**
+- Last **123 events** or **24 hours** (whichever limit is reached first)
+- Enabled by default
+- Events are stored **after redaction** — same data sent to the platform
+
+**CLI usage:**
+```bash
+openclaw shield logs                  # last 10 events
+openclaw shield logs --last 20        # last N events
+openclaw shield logs --type TOOL_CALL # filter by event type
+openclaw shield logs --since 30m      # events from last 30 minutes
+openclaw shield logs --format json    # JSON output for piping
+```
+
+**Configuration** (in `config.env` or environment variables):
+
+| 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 |
+
+---
+
 ## What data is collected
 
 Shield captures agent activity locally, applies on-device redaction, and forwards telemetry to the UPX platform.
@@ -226,7 +351,7 @@ Shield captures agent activity locally, applies on-device redaction, and forward
 | 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 redaction works:** sensitive values are replaced with deterministic `category:hash` tokens before leaving your machine. Token categories: `host:HASH` (hostnames), `user:HASH` (usernames), `secret:HASH` (API keys/credentials), `agent:HASH` (agent identifiers), `workspace:HASH` (workspace paths). 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. Run `openclaw shield vault show` to inspect current token mappings.
 
 ---
 
@@ -278,6 +403,8 @@ Sent every poll cycle over HTTPS. This is the data stream subject to the full re
 
 ## Upgrading
 
+### Manual upgrade
+
 ```bash
 openclaw plugins update shield
 openclaw shield status
@@ -287,6 +414,34 @@ Cursors and credentials are preserved across upgrades. See the CHANGELOG (availa
 
 > **"Integrity drift detected"** during upgrade is expected — OpenClaw warns when plugin files change, which always happens on a legitimate upgrade. This only indicates a real problem if you see it without having explicitly upgraded.
 
+### Auto-update
+
+Shield can check for and install newer versions automatically.
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "shield": {
+        "config": {
+          "autoUpdate": "notify-only"
+        }
+      }
+    }
+  }
+}
+```
+
+| Mode | Behavior |
+|---|---|
+| `false` | Disabled. No version checks. |
+| `"notify-only"` | Logs available updates but does not install. |
+| `true` | **(default)** Automatically installs **patch and minor** versions. Major updates require manual upgrade. |
+
+When `autoUpdate` is `true`, Shield backs up the current version before installing and automatically rolls back if anything fails. Gateway is restarted after a successful update.
+
 ---
 
 ## Troubleshooting
@@ -330,7 +485,7 @@ Yes. Shield runs as a passive observer — it hooks into the event stream and do
 No. The key is consumed only on the first *successful* activation. If the attempt fails (network issue, config error), you can fix the issue and retry with the same key.
 
 **Where is the changelog?**
-the CHANGELOG, available on the Shield portal at uss.upx.com
+See CHANGELOG.md included with the plugin.
 
 ---
 

package/dist/index.js

@@ -44,10 +44,16 @@ const log_1 = require("./src/log");
 const log = __importStar(require("./src/log"));
 const version_1 = require("./src/version");
 const fs_1 = require("fs");
+const safe_io_1 = require("./src/safe-io");
 const path_1 = require("path");
 const os_1 = require("os");
 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 updater_1 = require("./src/updater");
+const rpc_1 = require("./src/rpc");
+const inventory_1 = require("./src/inventory");
 const SHIELD_API_URL = 'https://openclaw-shield.upx.com';
 async function performAutoRegistration(installationKey) {
     try {
@@ -192,11 +198,7 @@ function readAllTimeStats() {
     if (_allTimeStats)
         return _allTimeStats;
     try {
-        if (!(0, fs_1.existsSync)(STATS_FILE)) {
-            _allTimeStats = { eventsProcessed: 0, quarantineCount: 0 };
-            return _allTimeStats;
-        }
-        _allTimeStats = JSON.parse((0, fs_1.readFileSync)(STATS_FILE, 'utf8'));
+        _allTimeStats = (0, safe_io_1.readJsonSafe)(STATS_FILE, { eventsProcessed: 0, quarantineCount: 0 }, 'stats');
         return _allTimeStats;
     }
     catch {
@@ -219,7 +221,7 @@ function flushAllTimeStats() {
         const dir = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data');
         if (!(0, fs_1.existsSync)(dir))
             (0, fs_1.mkdirSync)(dir, { recursive: true });
-        (0, fs_1.writeFileSync)(STATS_FILE, JSON.stringify(_allTimeStats, null, 2));
+        (0, safe_io_1.writeJsonSafe)(STATS_FILE, _allTimeStats);
         _allTimeStatsDirty = false;
     }
     catch { }
@@ -244,24 +246,24 @@ function persistState(extra = {}) {
             };
         }
         catch { }
-        (0, fs_1.writeFileSync)(STATUS_FILE, JSON.stringify({
+        (0, safe_io_1.writeJsonSafe)(STATUS_FILE, {
             ...state, ...extra,
             version: version_1.VERSION,
             updatedAt: Date.now(),
             pid: process.pid,
             counters: countersSnapshot,
             allTime: readAllTimeStats(),
-        }, null, 2));
+        });
         _stateDirty = false;
     }
     catch { }
 }
 function readPersistedState() {
     try {
-        if (!(0, fs_1.existsSync)(STATUS_FILE))
+        const d = (0, safe_io_1.readJsonSafe)(STATUS_FILE, null, 'status');
+        if (!d)
             return null;
-        const d = JSON.parse((0, fs_1.readFileSync)(STATUS_FILE, 'utf8'));
-        const age = Date.now() - (d.updatedAt || 0);
+        const age = Date.now() - (Number(d.updatedAt) || 0);
         if (age > 10 * 60 * 1000)
             return null;
         return d;
@@ -371,8 +373,15 @@ function printActivatedStatus() {
     console.log(`  Events sent:  ${allTime.eventsProcessed.toLocaleString()}  (all-time)`);
     console.log(`  Quarantine:   ${allTime.quarantineCount.toLocaleString()}  (all-time)`);
     console.log(`  Failures:     ${s.consecutiveFailures ?? 0}  (consecutive)`);
-    if (s.pid)
-        console.log(`  Daemon PID:   ${s.pid}`);
+    if (s.pid) {
+        let pidAlive = false;
+        try {
+            process.kill(s.pid, 0);
+            pidAlive = true;
+        }
+        catch { }
+        console.log(`  Daemon PID:   ${s.pid}${pidAlive ? '' : '  ⚠️ stale (process not running)'}`);
+    }
     const statusWarnings = getStatusWarnings({
         running: isRunning,
         lastPollAt: s.lastPollAt ?? null,
@@ -455,6 +464,21 @@ function printActivatedStatus() {
         }
         console.log('  (original values never stored or transmitted)');
     }
+    const cmStatus = (0, case_monitor_1.getCaseMonitorStatus)();
+    {
+        console.log('');
+        console.log('── Case Monitor ──────────────────────────────');
+        const intervalSec = Math.round(cmStatus.intervalMs / 1000);
+        const nextSec = Math.round(cmStatus.nextCheckIn / 1000);
+        const lastCheckLabel = cmStatus.lastCheckAt > 0
+            ? (Date.now() - cmStatus.lastCheckAt < 60_000
+                ? `${Math.round((Date.now() - cmStatus.lastCheckAt) / 1000)}s ago`
+                : `${Math.floor((Date.now() - cmStatus.lastCheckAt) / 60_000)}m ago`)
+            : 'pending';
+        console.log(`  Interval:     ${intervalSec}s (adaptive: 60s active → 900s idle)`);
+        console.log(`  Last check:   ${lastCheckLabel}`);
+        console.log(`  Next check:   ~${nextSec}s`);
+    }
 }
 exports.default = {
     id: 'shield',
@@ -580,6 +604,36 @@ 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, case_monitor_1.initCaseMonitor)((0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data'));
+                    const autoUpdateMode = pluginConfig.autoUpdate ?? true;
+                    log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
+                    const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
+                    if (startupUpdate.action === 'updated') {
+                        log.info('updater', startupUpdate.message);
+                        const restarted = (0, updater_1.requestGatewayRestart)();
+                        if (restarted) {
+                            startGuard.endFailure();
+                            return;
+                        }
+                        log.warn('updater', 'Gateway restart failed — continuing with current version in memory. Restart the gateway manually to load the updated plugin.');
+                    }
+                    else if (startupUpdate.action === 'none') {
+                        log.info('updater', `Up to date (${version_1.VERSION})`);
+                    }
+                    else if (startupUpdate.action === 'notify') {
+                        log.info('updater', startupUpdate.message);
+                    }
+                    else if (startupUpdate.action === 'rollback' || startupUpdate.action === 'error') {
+                        log.warn('updater', startupUpdate.message);
+                    }
+                    try {
+                        const inv = (0, inventory_1.collectInventory)();
+                        const { setCachedInventory } = await Promise.resolve().then(() => __importStar(require('./src/inventory')));
+                        setCachedInventory(inv);
+                    }
+                    catch (err) {
+                        log.warn('shield', `Inventory collection failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                    }
                     const { fetchNewEntries, commitCursors } = await Promise.resolve().then(() => __importStar(require('./src/fetcher')));
                     const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = await Promise.resolve().then(() => __importStar(require('./src/transformer')));
                     const { sendEvents, reportInstance } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
@@ -623,6 +677,20 @@ exports.default = {
                         if (activeGeneration !== runtimeGeneration || !state.running)
                             return;
                         runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
+                        try {
+                            const updateResult = (0, updater_1.performAutoUpdate)(autoUpdateMode);
+                            if (updateResult.action !== 'none') {
+                                log.info('updater', updateResult.message);
+                                if (updateResult.action === 'updated') {
+                                    if (!(0, updater_1.requestGatewayRestart)()) {
+                                        log.warn('updater', 'Restart not available — new version loads on next manual restart');
+                                    }
+                                }
+                            }
+                        }
+                        catch (err) {
+                            log.warn('updater', `Periodic update check failed: ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }, TELEMETRY_INTERVAL_MS);
                     const poll = async () => {
                         if (!state.running || activeGeneration !== runtimeGeneration)
@@ -678,6 +746,7 @@ exports.default = {
                             }
                             const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
                             if (accepted > 0) {
+                                (0, case_monitor_1.notifyCaseMonitorActivity)();
                                 commitCursors(config, entries);
                                 flushRedactor();
                                 state.eventsProcessed += accepted;
@@ -700,6 +769,10 @@ exports.default = {
                             state.lastPollAt = Date.now();
                             markStateDirty();
                             persistState();
+                            const platformConfig = { apiUrl: config.credentials.apiUrl, instanceId: config.credentials.instanceId, hmacSecret: config.credentials.hmacSecret };
+                            await (0, case_monitor_1.checkForNewCases)(platformConfig).catch(err => {
+                                log.debug('case-monitor', `Check error: ${err instanceof Error ? err.message : String(err)}`);
+                            });
                         }
                         catch (err) {
                             if (activeGeneration !== runtimeGeneration)
@@ -758,6 +831,7 @@ exports.default = {
         api.registerGatewayMethod('shield.status', ({ respond }) => {
             const creds = (0, config_1.loadCredentials)();
             const activated = state.activated || hasValidCredentials(creds);
+            const caseStatus = (0, case_monitor_1.getCaseMonitorStatus)();
             respond(true, {
                 activated,
                 running: state.running,
@@ -768,6 +842,11 @@ exports.default = {
                 quarantineCount: state.quarantineCount,
                 consecutiveFailures: state.consecutiveFailures,
                 version: version_1.VERSION,
+                caseMonitor: {
+                    intervalMs: caseStatus.intervalMs,
+                    nextCheckInMs: caseStatus.nextCheckIn,
+                    lastCheckAt: caseStatus.lastCheckAt,
+                },
             });
         });
         api.registerGatewayMethod('shield.flush', ({ respond }) => {
@@ -779,8 +858,17 @@ exports.default = {
                 .then(() => respond(true, { flushed: true }))
                 .catch((err) => respond(false, { error: err instanceof Error ? err.message : String(err) }));
         });
+        const rpcCreds = (0, config_1.loadCredentials)();
+        const rpcConfig = (0, config_1.loadConfig)({});
+        const platformApiConfig = {
+            apiUrl: rpcConfig.platformApiUrl ?? null,
+            instanceId: state.instanceId || rpcCreds?.instanceId || '',
+            hmacSecret: rpcCreds?.hmacSecret || '',
+        };
+        (0, rpc_1.registerAllRpcs)(api, platformApiConfig);
         api.registerCli(({ program }) => {
             const shield = program.command('shield');
+            (0, cli_cases_1.registerCasesCli)(shield);
             shield.command('status')
                 .description('Show Shield monitoring status and activity')
                 .action(async () => {
@@ -826,6 +914,101 @@ exports.default = {
                     console.error('   Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
                 }
             });
+            const vault = shield.command('vault');
+            vault.command('show')
+                .description('Show Shield vault — agent inventory and redaction summary')
+                .action(async () => {
+                const vaultData = (0, inventory_1.readVault)();
+                const inventory = vaultData.host_inventory;
+                if (!inventory || !inventory.agents || inventory.agents.length === 0) {
+                    console.log('No host inventory collected yet.');
+                    console.log('Inventory is collected on gateway startup when Shield is activated.');
+                    return;
+                }
+                console.log(`Host Inventory  (collected: ${inventory.collected_at})`);
+                console.log('');
+                console.log(`  Agents:     ${inventory.agent_count}`);
+                console.log(`  Workspaces: ${inventory.workspace_count}`);
+                console.log('');
+                console.log('── Agents ────────────────────────────────────');
+                for (const agent of inventory.agents) {
+                    const agentHash = (0, crypto_1.createHash)('sha256').update(agent.id).digest('hex').slice(0, 8);
+                    const wsHash = (0, crypto_1.createHash)('sha256').update(agent.workspace).digest('hex').slice(0, 8);
+                    const bootstrapLabel = agent.is_bootstrapped ? '✅' : '⏳ pending';
+                    const identityLabel = agent.has_identity ? '✅' : '—';
+                    console.log(`  agent:${agentHash}  workspace:${wsHash}  identity=${identityLabel}  bootstrapped=${bootstrapLabel}`);
+                }
+                try {
+                    const { initVault, getAllMappings } = await Promise.resolve().then(() => __importStar(require('./src/redactor/vault')));
+                    initVault();
+                    const mappings = getAllMappings();
+                    const tokens = Object.keys(mappings);
+                    if (tokens.length > 0) {
+                        const counts = {};
+                        for (const token of tokens) {
+                            const colonIdx = token.indexOf(':');
+                            const category = colonIdx > 0 ? token.slice(0, colonIdx) : 'unknown';
+                            counts[category] = (counts[category] || 0) + 1;
+                        }
+                        console.log('');
+                        console.log(`── Redactions  (${tokens.length} tokens) ─────────────────────`);
+                        for (const [category, count] of Object.entries(counts)) {
+                            const label = count === 1 ? 'unique value' : 'unique values';
+                            console.log(`  ${(category + ':HASH').padEnd(20)} ${count} ${label}`);
+                        }
+                        console.log('');
+                        console.log('  (original values encrypted locally — never transmitted)');
+                    }
+                }
+                catch {
+                }
+            });
+            shield.command('logs')
+                .description('Show recent Shield events from local buffer')
+                .option('--last <n>', 'Number of events to show', '10')
+                .option('--type <type>', 'Filter by event type (TOOL_CALL, FILE_WRITE, etc.)')
+                .option('--since <duration>', 'Show events since duration (e.g. 30m, 2h, 1d)')
+                .option('--format <fmt>', 'Output format: table or json', 'table')
+                .action(async (opts) => {
+                const { queryEvents: qe, initEventStore: ie } = require('./src/event-store');
+                const os = require('os');
+                const path = require('path');
+                ie(path.join(os.homedir(), '.openclaw', 'shield', 'data'));
+                const limit = parseInt(opts.last, 10) || 10;
+                let sinceMs;
+                if (opts.since) {
+                    const match = opts.since.match(/^(\d+)(m|h|d)$/);
+                    if (match) {
+                        const val = parseInt(match[1], 10);
+                        const unit = match[2];
+                        sinceMs = val * (unit === 'm' ? 60000 : unit === 'h' ? 3600000 : 86400000);
+                    }
+                    else {
+                        console.error(`Invalid duration: ${opts.since}. Use format: 30m, 2h, 1d`);
+                        return;
+                    }
+                }
+                const events = qe({ limit, type: opts.type, sinceMs });
+                if (events.length === 0) {
+                    console.log('No events found.');
+                    console.log('Events are stored after successful transmission to the platform.');
+                    return;
+                }
+                if (opts.format === 'json') {
+                    console.log(JSON.stringify(events, null, 2));
+                    return;
+                }
+                console.log(`Recent Events (${events.length}):`);
+                console.log('');
+                for (const e of events) {
+                    const time = new Date(e.ts).toLocaleTimeString();
+                    const flag = e.redacted ? ' 🔒' : '';
+                    const summaryTrunc = e.summary.length > 60 ? e.summary.slice(0, 57) + '...' : e.summary;
+                    console.log(`  ${time}  ${e.type.padEnd(12)} ${e.tool.padEnd(10)} ${summaryTrunc}${flag}`);
+                }
+                console.log('');
+                console.log(`  Showing ${events.length} events. Use --last N for more, --format json for details.`);
+            });
         }, { commands: ['shield'] });
     },
 };

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

@@ -0,0 +1,24 @@
+import { type PlatformApiConfig } from './rpc/client';
+export interface CaseSummary {
+    id: string;
+    rule_id: string;
+    rule_title: string;
+    severity: string;
+    status: string;
+    created_at: string;
+    summary: string;
+    event_count: number;
+    agent_id?: string;
+}
+export declare function initCaseMonitor(dataDir: string): void;
+export declare function notifyCaseMonitorActivity(): void;
+export declare function getCaseMonitorStatus(): {
+    intervalMs: number;
+    nextCheckIn: number;
+    lastCheckAt: number;
+};
+export declare function checkForNewCases(config: PlatformApiConfig): Promise<void>;
+export declare function getPendingCases(): CaseSummary[];
+export declare function acknowledgeCases(caseIds: string[]): void;
+export declare function formatCaseNotification(c: CaseSummary): string;
+export declare function _resetForTesting(): void;