@upx-us/shield 0.6.10 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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

package/README.md

@@ -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:
@@ -514,7 +532,7 @@ This removes all local files Shield writes at runtime:
 
 | File | Contents |
 |---|---|
-| `config.env` | HMAC secret and instance fingerprint |
+| `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 |

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/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/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

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.6.10",
+  "version": "0.7.0",
   "skills": [
     "./skills"
   ],

package/package.json

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