@upx-us/shield 0.6.8 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.0] — 2026-03-13
+
+### Added
+- **Event authorship & source attribution** — Shield now captures the source of every monitored agent action: who or what triggered it. Each event is tagged with an authorship category — a user via a messaging channel (Telegram, Discord, WhatsApp, etc.), a scheduled job, a periodic health check, a spawned sub-agent, or an autonomous agent action. This context appears alongside every event in your security dashboard, enabling "who caused this?" forensics on any alert or case.
+- **Sender identity captured when available** — when an action is triggered by a user via a messaging channel, the user's display name and channel are captured in plain text for human-readable alerting. The raw user identifier is stored as a reversible token (recoverable locally via `openclaw shield vault show`).
+
+### Changed
+- **README updated** — new "Authorship & Event Source" section documents the authorship categories available in the dashboard.
+
+### Notes
+- Fully backward compatible. Existing deployments continue to work without any configuration changes. Authorship context is captured automatically on upgrade.
+
+---
+
+## [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

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 |
 
 ---
 
@@ -350,6 +350,24 @@ Shield captures agent activity locally, applies on-device redaction, and forward
 
 ---
 
+## Authorship & Event Source
+
+Shield captures the **source** of every event — who or what triggered the agent action being monitored.
+
+Each event is tagged with an authorship category:
+
+| Category | Description |
+|---|---|
+| Communication channel | A user interacted with the agent via a messaging platform (e.g. Telegram, Discord, WhatsApp) |
+| Scheduled job | The action was triggered by a scheduled or automated task |
+| Heartbeat | The action was triggered by a periodic health check |
+| Sub-agent | The action originated from a child agent spawned by a parent |
+| Autonomous | The agent acted on its own initiative without a direct human trigger |
+
+This information appears alongside every event in your security dashboard, enabling you to answer **"who caused this?"** for any alert or case.
+
+---
+
 ## What is sent to the platform
 
 Shield uses two separate channels with different privacy properties:
@@ -498,24 +516,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:
 
-> **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.
+| File | Contents |
+|---|---|
+| `config.env` | Signing key 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
+
+Removing local files does **not** automatically deactivate your registration on the UPX platform.
+
+To fully remove your instance: log in to **[uss.upx.com](https://uss.upx.com)** → Instances → Delete.
 
-Platform-side instance data can be managed via [uss.upx.com](https://uss.upx.com).
+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/attributor.d.ts

@@ -0,0 +1,15 @@
+export type TriggerType = 'user_message' | 'cron' | 'heartbeat' | 'subagent' | 'autonomous' | 'unknown';
+export declare const TRIGGER_TYPES: readonly TriggerType[];
+export interface AttributionContext {
+    trigger_type: TriggerType;
+    author_name?: string;
+    author_channel?: string;
+    author_hash?: string;
+    prompt_hash?: string;
+    session_label?: string;
+    parent_agent_id?: string;
+    cron_schedule?: string;
+    conversation_depth?: number;
+}
+export declare function clearAttributionCache(): void;
+export declare function resolveAttribution(sessionId: string, agentId: string, sessionDir: string): AttributionContext;

package/dist/src/attributor.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRIGGER_TYPES = void 0;
+exports.clearAttributionCache = clearAttributionCache;
+exports.resolveAttribution = resolveAttribution;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const vault_1 = require("./redactor/vault");
+exports.TRIGGER_TYPES = [
+    'user_message', 'cron', 'heartbeat', 'subagent', 'autonomous', 'unknown',
+];
+const _attributionCache = new Map();
+function clearAttributionCache() {
+    _attributionCache.clear();
+}
+const MAX_SCAN_LINES = 50;
+const READ_BUF_SIZE = 32768;
+function readFirstLines(filePath, maxLines) {
+    if (!fs.existsSync(filePath))
+        return [];
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(READ_BUF_SIZE);
+        const bytesRead = fs.readSync(fd, buf, 0, READ_BUF_SIZE, 0);
+        const text = buf.toString('utf8', 0, bytesRead);
+        return text
+            .split('\n')
+            .map(l => l.trim())
+            .filter(l => l.length > 0)
+            .slice(0, maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}
+function extractSenderBlock(text) {
+    const match = text.match(/Sender \(untrusted metadata\):\s*```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+    if (!match)
+        return null;
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+function extractConversationBlock(text) {
+    const match = text.match(/Conversation info \(untrusted metadata\):\s*```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+    if (!match)
+        return null;
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+function inferChannel(block) {
+    if (!block)
+        return undefined;
+    if (block.channel)
+        return block.channel;
+    const label = block.conversation_label || '';
+    if (!label)
+        return undefined;
+    if (/id:-\d+/.test(label))
+        return 'telegram';
+    if (/discord/i.test(label))
+        return 'discord';
+    if (/whatsapp/i.test(label))
+        return 'whatsapp';
+    if (/slack/i.test(label))
+        return 'slack';
+    if (/signal/i.test(label))
+        return 'signal';
+    if (/imessage/i.test(label))
+        return 'imessage';
+    return undefined;
+}
+const HEARTBEAT_PATTERN = /\bHEARTBEAT_OK\b|\bRead HEARTBEAT\.md\b|\bheartbeat\b/i;
+const CRON_PATTERN = /\bcron\b|\bscheduled job\b|\bscheduled task\b/i;
+const SCHEDULE_EXPR_RE = /(?:\*\/\d+|\d+|\*)\s+(?:\*\/\d+|\d+|\*)\s+(?:\*\/\d+|\d+|\*)\s+(?:\*\/\d+|\d+|\*)\s+(?:\*\/\d+|\d+|\*)/;
+const SUBAGENT_PATTERN = /subagent|sub-agent/i;
+function extractCronSchedule(text) {
+    const m = text.match(SCHEDULE_EXPR_RE);
+    return m ? m[0].trim() : undefined;
+}
+function resolveAttribution(sessionId, agentId, sessionDir) {
+    const cached = _attributionCache.get(sessionId);
+    if (cached)
+        return cached;
+    const filePath = path.join(sessionDir, `${sessionId}.jsonl`);
+    const lines = readFirstLines(filePath, MAX_SCAN_LINES);
+    if (lines.length === 0) {
+        return { trigger_type: 'unknown' };
+    }
+    let sessionLabel;
+    let parentAgentId;
+    try {
+        const first = JSON.parse(lines[0]);
+        if (first.type === 'session') {
+            if (first.label)
+                sessionLabel = String(first.label);
+            if (first.parentAgentId)
+                parentAgentId = String(first.parentAgentId);
+        }
+    }
+    catch { }
+    if ((sessionLabel && SUBAGENT_PATTERN.test(sessionLabel)) ||
+        SUBAGENT_PATTERN.test(sessionId) ||
+        (parentAgentId != null)) {
+        const ctx = {
+            trigger_type: 'subagent',
+            session_label: sessionLabel,
+            parent_agent_id: parentAgentId || agentId,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    let userMessageCount = 0;
+    let firstUserText;
+    let senderBlock = null;
+    let conversationBlock = null;
+    for (const line of lines) {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type !== 'message')
+            continue;
+        const msg = entry.message;
+        if (!msg || msg.role !== 'user')
+            continue;
+        userMessageCount++;
+        const textContent = Array.isArray(msg.content)
+            ? msg.content
+                .filter((c) => c.type === 'text')
+                .map((c) => String(c.text || ''))
+                .join('\n')
+            : typeof msg.content === 'string'
+                ? msg.content
+                : '';
+        if (!firstUserText)
+            firstUserText = textContent;
+        if (!senderBlock)
+            senderBlock = extractSenderBlock(textContent);
+        if (!conversationBlock)
+            conversationBlock = extractConversationBlock(textContent);
+        if (senderBlock && conversationBlock)
+            break;
+    }
+    if (userMessageCount === 0) {
+        const ctx = {
+            trigger_type: 'autonomous',
+            session_label: sessionLabel,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    if (firstUserText && HEARTBEAT_PATTERN.test(firstUserText)) {
+        const ctx = {
+            trigger_type: 'heartbeat',
+            session_label: sessionLabel,
+            conversation_depth: userMessageCount,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    if (firstUserText && (CRON_PATTERN.test(firstUserText) || SCHEDULE_EXPR_RE.test(firstUserText))) {
+        const cronSchedule = extractCronSchedule(firstUserText);
+        const ctx = {
+            trigger_type: 'cron',
+            session_label: sessionLabel,
+            cron_schedule: cronSchedule,
+            conversation_depth: userMessageCount,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    if (senderBlock) {
+        const authorName = senderBlock.label || senderBlock.name || senderBlock.username;
+        const authorChannel = inferChannel(conversationBlock) ?? (senderBlock.channel);
+        const rawId = senderBlock.id != null
+            ? String(senderBlock.id)
+            : senderBlock.username || authorName;
+        const authorIdHash = rawId ? (0, vault_1.hmacHash)('trigger.author_id', rawId) : undefined;
+        const promptHash = firstUserText ? (0, vault_1.hmacHash)('trigger.prompt', firstUserText) : undefined;
+        const ctx = {
+            trigger_type: 'user_message',
+            author_name: authorName,
+            author_channel: authorChannel,
+            author_hash: authorIdHash,
+            prompt_hash: promptHash,
+            session_label: sessionLabel,
+            conversation_depth: userMessageCount,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    if (userMessageCount > 0 && firstUserText) {
+        const promptHash = (0, vault_1.hmacHash)('trigger.prompt', firstUserText);
+        const ctx = {
+            trigger_type: 'user_message',
+            prompt_hash: promptHash,
+            session_label: sessionLabel,
+            conversation_depth: userMessageCount,
+        };
+        _attributionCache.set(sessionId, ctx);
+        return ctx;
+    }
+    return { trigger_type: 'unknown' };
+}

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/base.d.ts

@@ -1,3 +1,5 @@
+import type { TriggerType as _TriggerType } from '../attributor';
+export type TriggerType = _TriggerType;
 export interface BaseEvent {
     timestamp: string;
     event_type: 'TOOL_CALL' | 'TOOL_RESULT';
@@ -14,6 +16,17 @@ export interface BaseEvent {
         user: string;
     };
     tool_metadata?: Record<string, string | null>;
+    trigger?: {
+        type: TriggerType;
+        author_name?: string;
+        author_channel?: string;
+        author_hash?: string;
+        prompt_hash?: string;
+        session_label?: string;
+        parent_agent_id?: string;
+        cron_schedule?: string;
+        conversation_depth?: number;
+    };
 }
 export interface NetworkBlock {
     network: {

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/index.js

@@ -172,7 +172,7 @@ async function poll() {
                 }
             }
             if (entries.length > 0) {
-                let envelopes = (0, transformer_1.transformEntries)(entries);
+                let envelopes = (0, transformer_1.transformEntries)(entries, config.sessionDirs);
                 const { valid: validEnvelopes, quarantined } = (0, validator_1.validate)(envelopes.map(e => e.event));
                 if (quarantined > 0) {
                     log.warn('bridge', `${quarantined} events quarantined (see ~/.openclaw/shield/data/quarantine.jsonl)`);

package/dist/src/transformer.d.ts

@@ -15,5 +15,5 @@ export declare function resolveAgentLabel(agentId: string): string;
 export declare function getCachedPublicIp(): string | null;
 export declare function isPrivateIp(ip: string): boolean;
 export declare function resolveOutboundIp(): Promise<string | null>;
-export declare function transformEntries(entries: RawEntry[]): EnvelopeEvent[];
+export declare function transformEntries(entries: RawEntry[], sessionDirs?: string[]): EnvelopeEvent[];
 export declare function generateHostTelemetry(): EnvelopeEvent | null;

package/dist/src/transformer.js

@@ -52,6 +52,7 @@ const log = __importStar(require("./log"));
 const version_1 = require("./version");
 const counters_1 = require("./counters");
 const inventory_1 = require("./inventory");
+const attributor_1 = require("./attributor");
 let _cachedOpenClawVersion = "";
 function normalizeSoftwareVersion(v) {
     return v
@@ -273,9 +274,72 @@ function isAdministrativeEvent(toolName, args, sessionId) {
         return true;
     return false;
 }
-function transformEntries(entries) {
+function findSessionDir(agentId, sessionDirs) {
+    const normalized = agentId.toLowerCase();
+    return sessionDirs.find(dir => {
+        const parts = dir.replace(/\\/g, '/').split('/');
+        return parts.length >= 2 &&
+            parts[parts.length - 1] === 'sessions' &&
+            parts[parts.length - 2].toLowerCase() === normalized;
+    });
+}
+function flattenTriggerToMetadata(event, ctx) {
+    if (ctx.trigger_type === 'unknown')
+        return;
+    if (!event.tool_metadata)
+        event.tool_metadata = {};
+    const m = event.tool_metadata;
+    m['trigger.type'] = ctx.trigger_type;
+    if (ctx.author_hash)
+        m['trigger.author_hash'] = ctx.author_hash;
+    if (ctx.prompt_hash)
+        m['trigger.prompt_hash'] = ctx.prompt_hash;
+    if (ctx.conversation_depth !== undefined)
+        m['trigger.conversation_depth'] = String(ctx.conversation_depth);
+    if (ctx.author_name)
+        m['trigger.author_name'] = ctx.author_name;
+    if (ctx.author_channel)
+        m['trigger.author_channel'] = ctx.author_channel;
+    if (ctx.session_label)
+        m['trigger.session_label'] = ctx.session_label;
+    if (ctx.parent_agent_id)
+        m['trigger.parent_agent_id'] = ctx.parent_agent_id;
+    if (ctx.cron_schedule)
+        m['trigger.cron_schedule'] = ctx.cron_schedule;
+}
+function buildTriggerField(ctx) {
+    if (ctx.trigger_type === 'unknown')
+        return undefined;
+    return {
+        type: ctx.trigger_type,
+        ...(ctx.author_name !== undefined && { author_name: ctx.author_name }),
+        ...(ctx.author_channel !== undefined && { author_channel: ctx.author_channel }),
+        ...(ctx.author_hash !== undefined && { author_hash: ctx.author_hash }),
+        ...(ctx.prompt_hash !== undefined && { prompt_hash: ctx.prompt_hash }),
+        ...(ctx.session_label !== undefined && { session_label: ctx.session_label }),
+        ...(ctx.parent_agent_id !== undefined && { parent_agent_id: ctx.parent_agent_id }),
+        ...(ctx.cron_schedule !== undefined && { cron_schedule: ctx.cron_schedule }),
+        ...(ctx.conversation_depth !== undefined && { conversation_depth: ctx.conversation_depth }),
+    };
+}
+function transformEntries(entries, sessionDirs) {
     const baseSource = getSourceInfo();
     const envelopes = [];
+    const attributionMap = new Map();
+    if (sessionDirs && sessionDirs.length > 0) {
+        const seen = new Set();
+        for (const entry of entries) {
+            const key = `${entry._agentId}::${entry._sessionId}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const dir = findSessionDir(entry._agentId, sessionDirs);
+            if (dir) {
+                const ctx = (0, attributor_1.resolveAttribution)(entry._sessionId, entry._agentId, dir);
+                attributionMap.set(key, ctx);
+            }
+        }
+    }
     for (const entry of entries) {
         const msg = entry.message;
         const agentId = entry._agentId || baseSource.openclaw.agent_id;
@@ -311,6 +375,15 @@ function transformEntries(entries) {
                     event.tool_metadata['openclaw.cross_workspace_access'] = 'true';
                     event.tool_metadata['openclaw.target_workspace'] = targetWorkspace;
                 }
+                const attrKey = `${agentId}::${entry._sessionId}`;
+                const attrCtx = attributionMap.get(attrKey);
+                if (attrCtx) {
+                    const triggerField = buildTriggerField(attrCtx);
+                    if (triggerField) {
+                        event.trigger = triggerField;
+                        flattenTriggerToMetadata(event, attrCtx);
+                    }
+                }
                 log.debug('transformer', `TOOL_CALL tool=${toolName} session=${entry._sessionId} agent=${agentId} schema=${schema.constructor?.name || 'unknown'} admin=${event.tool_metadata?.['openclaw.is_administrative'] === 'true'}`, log.isDebug ? event : undefined);
                 (0, counters_1.recordEventType)(event.event_type);
                 envelopes.push({ source, event });
@@ -323,6 +396,15 @@ function transformEntries(entries) {
                     event.tool_metadata = {};
                 event.tool_metadata['openclaw.is_administrative'] = 'true';
             }
+            const attrKeyR = `${agentId}::${entry._sessionId}`;
+            const attrCtxR = attributionMap.get(attrKeyR);
+            if (attrCtxR) {
+                const triggerFieldR = buildTriggerField(attrCtxR);
+                if (triggerFieldR) {
+                    event.trigger = triggerFieldR;
+                    flattenTriggerToMetadata(event, attrCtxR);
+                }
+            }
             log.debug('transformer', `TOOL_RESULT tool=${event.tool_name} session=${entry._sessionId} agent=${agentId}`, log.isDebug ? event : undefined);
             (0, counters_1.recordEventType)(event.event_type);
             envelopes.push({ source, event });

package/dist/src/validator.js

@@ -40,9 +40,31 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const events_1 = require("./events");
 const base_1 = require("./events/base");
+const attributor_1 = require("./attributor");
 const log = __importStar(require("./log"));
 const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
 exports.QUARANTINE_FILE = path.join(SHIELD_DATA_DIR, 'quarantine.jsonl');
+function validateTriggerField(event) {
+    const trigger = event.trigger;
+    if (!trigger)
+        return null;
+    if (!attributor_1.TRIGGER_TYPES.includes(trigger.type)) {
+        return `trigger.type '${trigger.type}' is not a valid TriggerType`;
+    }
+    if (trigger.author_hash !== undefined) {
+        if (typeof trigger.author_hash !== 'string' ||
+            !/^trigger\.author_id:[a-f0-9]{12}$/.test(trigger.author_hash)) {
+            return `trigger.author_hash has invalid format (expected trigger.author_id:[a-f0-9]{12})`;
+        }
+    }
+    if (trigger.prompt_hash !== undefined) {
+        if (typeof trigger.prompt_hash !== 'string' ||
+            !/^trigger\.prompt:[a-f0-9]{12}$/.test(trigger.prompt_hash)) {
+            return `trigger.prompt_hash has invalid format (expected trigger.prompt:[a-f0-9]{12})`;
+        }
+    }
+    return null;
+}
 function ensureDataDir() {
     fs.mkdirSync(SHIELD_DATA_DIR, { recursive: true });
 }
@@ -66,6 +88,18 @@ function validate(events) {
         if (!schema) {
             const baseResult = base_1.baseValidations.validate(event);
             if (baseResult.valid) {
+                const triggerError = validateTriggerField(event);
+                if (triggerError) {
+                    quarantined++;
+                    quarantineBuffer.push(JSON.stringify({
+                        quarantined_at: new Date().toISOString(),
+                        validation_error: triggerError,
+                        validation_field: 'trigger',
+                        event,
+                    }) + '\n');
+                    log.warn('validator', `QUARANTINE tool=${event.tool_name} field=trigger error=${triggerError}`);
+                    continue;
+                }
                 valid.push(event);
             }
             else {
@@ -80,6 +114,20 @@ function validate(events) {
             continue;
         }
         const result = (0, base_1.validateEvent)(event, schema);
+        if (result.valid) {
+            const triggerError = validateTriggerField(event);
+            if (triggerError) {
+                quarantined++;
+                quarantineBuffer.push(JSON.stringify({
+                    quarantined_at: new Date().toISOString(),
+                    validation_error: triggerError,
+                    validation_field: 'trigger',
+                    event,
+                }) + '\n');
+                log.warn('validator', `QUARANTINE tool=${event.tool_name} field=trigger error=${triggerError}`);
+                continue;
+            }
+        }
         if (result.valid) {
             log.debug('validator', `PASS tool=${event.tool_name} category=${event.tool_category}`);
             valid.push(event);

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.8",
+  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.7.0",
   "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.8",
+  "version": "0.7.0",
   "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