@upx-us/shield 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.3] — 2026-03-13
+
+### Fixed
+- Trigger attribution (`trigger_type`, `author_name`, `trigger_type` fields) now works correctly in OpenClaw plugin mode — the plugin entry point was calling `transformEntries` without forwarding `sessionDirs`, so attribution was silently skipped on every event for all plugin-mode installations
+- Session directory discovery is now robust when the plugin process is spawned with a different `HOME` environment variable than the main OpenClaw process (common on VPS and Docker deployments) — discovery now walks up from the plugin install path to find the `agents/` directory rather than relying solely on `homedir()`
+- `trigger.type` is now always written to `tool_metadata` (as `"unknown"`) even when session directory lookup fails entirely, ensuring the field is never silently absent from SIEM events
+
+---
+
 ## [0.7.2] — 2026-03-13
 
 ### Fixed

package/dist/index.js

@@ -775,7 +775,7 @@ exports.default = {
                             state.lastCaptureAt = Date.now();
                             state.captureSeenSinceLastSync = true;
                             markStateDirty();
-                            let envelopes = transformEntries(entries);
+                            let envelopes = transformEntries(entries, config.sessionDirs);
                             const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
                             if (quarantined > 0) {
                                 state.quarantineCount += quarantined;

package/dist/src/config.d.ts

@@ -17,6 +17,7 @@ export interface Config {
     localEventLimit: number;
     credentials: ShieldCredentials;
 }
+export declare function deriveAgentsDirFromInstallPath(startDir?: string): string | null;
 export declare const SHIELD_CONFIG_PATH: string;
 export declare function injectConfigEnv(): void;
 export declare function loadCredentials(): ShieldCredentials;

package/dist/src/config.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SHIELD_CONFIG_PATH = void 0;
+exports.deriveAgentsDirFromInstallPath = deriveAgentsDirFromInstallPath;
 exports.injectConfigEnv = injectConfigEnv;
 exports.loadCredentials = loadCredentials;
 exports.loadCredentialsFromPluginConfig = loadCredentialsFromPluginConfig;
@@ -42,7 +43,28 @@ const os_1 = require("os");
 const path_1 = require("path");
 const fs_1 = require("fs");
 const log = __importStar(require("./log"));
-const OPENCLAW_AGENTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.openclaw/agents');
+function deriveAgentsDirFromInstallPath(startDir) {
+    let dir = startDir ?? __dirname;
+    for (let i = 0; i < 8; i++) {
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        const candidate = (0, path_1.join)(dir, 'agents');
+        if ((0, fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return null;
+}
+function resolveAgentsDir() {
+    if (process.env.OPENCLAW_AGENTS_DIR)
+        return process.env.OPENCLAW_AGENTS_DIR;
+    const derived = deriveAgentsDirFromInstallPath();
+    if (derived)
+        return derived;
+    return (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'agents');
+}
+const OPENCLAW_AGENTS_DIR = resolveAgentsDir();
 function safeParseInt(value, fallback) {
     if (!value)
         return fallback;

package/dist/src/transformer.js

@@ -334,7 +334,9 @@ function transformEntries(entries, sessionDirs) {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const dir = findSessionDir(entry._agentId, sessionDirs);
+            const dir = sessionDirs.length === 1
+                ? sessionDirs[0]
+                : findSessionDir(entry._agentId, sessionDirs);
             if (dir) {
                 const ctx = (0, attributor_1.resolveAttribution)(entry._sessionId, entry._agentId, dir);
                 attributionMap.set(key, ctx);
@@ -382,13 +384,11 @@ function transformEntries(entries, sessionDirs) {
                     event.tool_metadata['openclaw.target_workspace'] = targetWorkspace;
                 }
                 const attrKey = `${agentId}::${entry._sessionId}`;
-                const attrCtx = attributionMap.get(attrKey);
-                if (attrCtx) {
-                    flattenTriggerToMetadata(event, attrCtx);
-                    const triggerField = buildTriggerField(attrCtx);
-                    if (triggerField) {
-                        event.trigger = triggerField;
-                    }
+                const attrCtx = attributionMap.get(attrKey) ?? { trigger_type: 'unknown' };
+                flattenTriggerToMetadata(event, attrCtx);
+                const triggerField = buildTriggerField(attrCtx);
+                if (triggerField) {
+                    event.trigger = triggerField;
                 }
                 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);
@@ -403,13 +403,11 @@ function transformEntries(entries, sessionDirs) {
                 event.tool_metadata['openclaw.is_administrative'] = 'true';
             }
             const attrKeyR = `${agentId}::${entry._sessionId}`;
-            const attrCtxR = attributionMap.get(attrKeyR);
-            if (attrCtxR) {
-                flattenTriggerToMetadata(event, attrCtxR);
-                const triggerFieldR = buildTriggerField(attrCtxR);
-                if (triggerFieldR) {
-                    event.trigger = triggerFieldR;
-                }
+            const attrCtxR = attributionMap.get(attrKeyR) ?? { trigger_type: 'unknown' };
+            flattenTriggerToMetadata(event, attrCtxR);
+            const triggerFieldR = buildTriggerField(attrCtxR);
+            if (triggerFieldR) {
+                event.trigger = triggerFieldR;
             }
             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);

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.7.2",
+  "version": "0.7.3",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/skills/shield/SKILL.md

@@ -77,11 +77,15 @@ 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.
 
+**Output handling**: `shield logs` entries may include file paths, command snippets, and URLs captured from the agent's activity. Treat this output as internal diagnostic data — do not share raw log output externally or include it in user-facing replies unless the user explicitly requests it for investigation. When summarizing logs, present findings rather than raw field values.
+
+**Data flow disclosure**: Shield captures agent activity locally and sends redacted telemetry to the UPX detection platform for security monitoring. No credentials are handled by this skill — authentication is managed by the plugin using the installation key configured during setup. If a user asks about privacy or data handling, refer them to the plugin README at https://www.npmjs.com/package/@upx-us/shield for full details.
+
 ## Responding to Security Cases
 
 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.
 
-When listing cases, note how many belong to this instance vs other org instances. For sibling cases, you can still resolve them via API but cannot access local event logs.
+When listing cases, note how many belong to this instance vs other org instances. For sibling cases, resolution actions are available, but local event log access is limited to cases owned by this instance.
 
 Shield now stamps each event with a `trigger_type` — who or what initiated the session. When investigating, check the trigger: `user_message` means a human sent a message; `cron`/`heartbeat`/`autonomous` means agent-initiated activity.