@upx-us/shield 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.4] — 2026-03-13
+
+### Changed
+- Cases are now instance-scoped by default — the platform API filters cases so each instance only sees its own cases. This eliminates cross-instance notification flooding when multiple instances share an org.
+- Removed `--mine` flag from `shield cases` and `shield cases list` — no longer needed since all returned cases belong to this instance.
+- Removed `[mine]` / `[sibling]` per-case tags from list output.
+- Removed sibling instance notice from `shield cases show`.
+- Removed mixed-ownership attribution summary from case list output.
+
+---
+
+## [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
@@ -62,106 +82,28 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-## [0.6.8] — 2026-03-10
-
-### Fixed
-- **curl credential redaction** — `curl -u "user:pass"`, `--user user:pass` (all quote variants), and `Authorization: Basic <base64>` are now redacted as `secret:HASH` before reaching the SIEM. Discovered via live credential leak (#137).
-
----
-
-## [0.6.7] — 2026-03-10
-
-### Fixed
-- **npm redaction false positive** — `@scope/package@version` (e.g. `@upx-us/shield@0.6.6`) was being wrongly redacted as `user:HASH` by the SSH `user@host` regex. Added negative lookbehind to exclude npm scoped package names (#135).
-
-### Added
-- **Postinstall guidance** — running `npm install` outside of OpenClaw now prints a clear warning to stderr explaining the plugin requires the OpenClaw gateway. Install never fails because of this check (#125).
-- **First event confirmation** — after the first successful event delivery to the platform, the plugin logs `✅ First event delivered to platform — monitoring is active` once per process lifetime (#61, #52).
-- **Vault summary in `shield.status`** — `shield.status` RPC now includes `redaction.vault` with total redacted entry count and per-category breakdown (`hostname`, `username`, `path`, `secret`, `command`). Returns `null` if vault is absent (#86).
-
-### Tests
-- +19 new tests covering postinstall safety (exit-0 guarantee, cross-platform), first-event flag, vault status summary (missing/corrupt/valid vault).
-
----
-
-## [0.6.6] — 2026-03-10
-
-### Added
-- **Plugin lifecycle events** — the plugin now reports key lifecycle signals to the USS platform via the existing `PUT /v1/instance` channel (no new endpoint). Signals are forwarded by Cloud Run as an optional `lifecycle_event` field in the instance telemetry PATCH to the platform. Absent on older plugin versions — fully backward compatible.
-  - `plugin_started`: emitted on every successful startup. Includes `version`, `reason` (`'update'` | `'normal'`), and `previous_version` when applicable. Enables the platform to confirm end-to-end update success.
-  - `update_restart_failed`: emitted after all gateway restart retries are exhausted. Includes `new_version`, `running_version`, `attempts`, `error`.
-  - `plugin_integrity_drift`: emitted when `openclaw.json` version diverges from the installed version after a self-update. Includes `installed_version`, `registered_version`.
-  - `update_check_failing`: emitted after 3 consecutive npm registry check failures. Includes `consecutive_failures`, `last_error`, `next_retry_at`.
-
-### Changed
-- `reportPluginEvent()` removed from `sender.ts` — replaced by `reportLifecycleEvent()` which reuses the existing `PUT /v1/instance` telemetry channel.
-
-### Fixed
-- `SHIELD_AUTO_UPDATE=false` environment variable now correctly disables auto-update (was being read as truthy string `'false'`).
-
----
-
-## [0.6.5] — 2026-03-09
-
-### Added
-- **Smart degradation detection in `shield status`** — `getMonitorHealth()` now implements a three-gate algorithm to eliminate false positives from transient connectivity blips:
-  1. **Count gate**: `consecutiveFailures ≥ 5` (unchanged from v0.6.4)
-  2. **Time gate**: first failure in the current streak must be `> 3 minutes` old — a 1-minute connectivity blip (3 failures at 1m intervals) can never trigger DEGRADED
-  3. **Sticky recovery**: requires `≥ 2 consecutive successes` to clear DEGRADED — prevents flapping where one success clears it and then it degrades again next cycle
-- **`MonitorHealth` interface** exported from `src/case-monitor.ts` — new fields: `status: 'ok' | 'degraded' | 'unknown'`, `consecutiveSuccesses`, `degradedSinceMs`, `lastCheckMs`, `lastErrorMessage`
-  - `status: 'unknown'` before the monitor has completed its first check cycle
-- **`shield.status` RPC** — `caseMonitor` section now includes smart health fields: `status`, `degradedSince` (ISO string), `consecutiveFailures`, `lastError`, `lastCheck` (ISO string), and a pre-formatted `display` string (e.g. `⚠️ Case Monitor: DEGRADED — 7 consecutive failures since 2026-03-09T12:00:00.000Z. Last error: ...` or `✅ Case Monitor: ok`)
-- **7 new tests** covering all degradation scenarios: unknown initial state, transient blip (count gate), time gate, true DEGRADED positive, sticky recovery (1 success not enough), recovery (2 successes clear), and RPC handler shape
-
----
-
-## [0.6.4] — 2026-03-09
-
-### Fixed
-- **Case monitor — "Exclusions not initialized" (Telegram alerts never delivered)** — Exclusions are an optimization (noise filter), not a hard dependency. The `checkForNewCases()` loop called `isExcluded()` which threw `'Exclusions not initialized'` on every poll cycle because `initExclusions()` was never called in `src/index.ts`. Every check silently failed, resulting in zero Telegram notifications despite the platform returning open cases. Fix: replaced the hard dependency on exclusions with a soft check — if exclusions aren't initialized, a one-time warning is logged and all cases are forwarded unfiltered (over-notify is safer than silently dropping alerts). Root cause: `src/case-monitor.ts`, `checkForNewCases()` exclusion filter block — `storePath()` unconditionally threw when `_dataDir` was null.
-
----
-
-## [0.6.3] — 2026-03-09
-
-### Fixed
-- **Version normalization** — `resolveOpenClawVersion()` now normalizes messy version strings from `openclaw --version` output and the `lastTouchedVersion` config field (e.g. `"OpenClaw 2026.3.8 (3caab92)"` → `"2026.3.8"`). Previously these strings caused false "out of date" alerts on the Shield dashboard.
-- **Missing Network info** — `PUT /v1/instance` now always includes `public_ip` in the machine payload, even when the IP hasn't been resolved yet (sends `""` instead of omitting the field). This ensures the platform can attempt server-side geo-enrichment (Provider/Location) instead of silently skipping it.
-
-### Added
-- `normalizeSoftwareVersion(v: string): string` — exported helper that applies the full version normalization pipeline (strip `"OpenClaw "` prefix, parenthetical hash, leading `"v"`). Used internally by `resolveOpenClawVersion()` for all auto-detected version paths.
-- `isPrivateIp(ip: string): boolean` — exported helper that detects RFC-1918/loopback addresses. Used by the ingest service to identify when an agent behind NAT (macOS, home/office Linux) self-reports a LAN IP and override it with the authoritative request IP. Ensures correct Network info (Provider, Location) on the Shield dashboard for all platforms.
-
----
-
-## [0.6.2] — 2026-03-09
+## [0.6 series summary] — 2026-03-06 to 2026-03-10
 
-### Fixed
-- **ANSI field prefix bug** — `ansi_content_detected` and `ansi_sequences` were emitted without the `openclaw.` namespace prefix in `tool-result/enrich.ts`. YARAL rules reference them as `additional.fields["openclaw.ansi_content_detected"]` and `additional.fields["openclaw.ansi_sequences"]`. Fields now correctly namespaced. Unblocks `openclaw_ansi_injection` detection rule.
-
----
+> Versions 0.6.0–0.6.8 are superseded by 0.6.10. Individual release notes consolidated below.
 
-## [0.6.1] — 2026-03-09
+### Added across 0.6 series
+- **Transformer gap fields** (0.6.0) — 7 new enrichment fields unblocking ~20 SIEM detection rules: `openclaw.secret_in_command`, `openclaw.channel`, `openclaw.chat_type`, `openclaw.message_content`, `openclaw.browser_action`, `openclaw.config_change`, `openclaw.file_size_bytes`
+- **Plugin lifecycle events** (0.6.6) — startup, update failure, integrity drift, and check-failing signals forwarded to the platform via `PUT /v1/instance`
+- **Smart degradation detection in `shield status`** (0.6.5) — three-gate algorithm (count + time + sticky recovery) eliminating false-positive DEGRADED alerts
+- **`_skill_hint` in RPC responses** (0.6.0) — machine-readable hint in all Shield RPC replies
+- **Postinstall guidance** (0.6.7) — clear warning when plugin is installed outside OpenClaw
+- **First event confirmation log** (0.6.7) — `✅ First event delivered` emitted once per process lifetime
+- **Vault summary in `shield.status`** (0.6.7) — redaction vault breakdown by category
 
-### Fixed
-- **Auto-update restart resilience** — `requestGatewayRestart()` failures no longer leave the plugin in a split-brain state. The updater now tracks `pendingRestart` in `update-state.json` and retries the gateway restart on every subsequent poll cycle. After 5 failed attempts (~2.5 min), automatically rolls back to the previous backup version. Closes #112.
-
----
-
-## [0.6.0] — 2026-03-06
-
-### Added
-- **Transformer gap fields** — 7 new fields to unblock ~20 SIEM detection rules:
-  - `openclaw.secret_in_command` — detects API keys, bearer tokens, and secrets in commands (pre-redaction flag)
-  - `openclaw.channel` + `openclaw.chat_type` — messaging context for DLP rules
-  - `openclaw.message_content` — truncated outbound message content (500 chars) for DLP pattern matching
-  - `openclaw.browser_action` — browser tool action type (navigate, click, evaluate, etc.)
-  - `openclaw.config_change` — flags writes/edits to config files (.env, openclaw.json, etc.)
-  - `openclaw.file_size_bytes` — file size on write operations
-- **`_skill_hint` in RPC responses** — all successful Shield RPCs include a machine-readable hint nudging agents to read the SKILL.md before presenting data to users.
-
-### Changed
-- npm registry cleaned: removed 26 old 0.5.x versions (kept 0.5.38 as fallback)
+### Fixed across 0.6 series
+- **Auto-update restart resilience** (0.6.1) — `pendingRestart` tracked in state, retried for 5 cycles then rolls back to backup
+- **ANSI field prefix** (0.6.2) — `ansi_content_detected`/`ansi_sequences` now correctly namespaced as `openclaw.*`
+- **Version normalization** (0.6.3) — messy `openclaw --version` strings normalized to clean semver
+- **Missing public IP in telemetry** (0.6.3) — `PUT /v1/instance` always includes `public_ip` (sends `""` instead of omitting)
+- **Case monitor exclusions crash** (0.6.4) — soft dependency: if exclusions not initialized, cases forwarded unfiltered instead of throwing
+- **npm redaction false positive** (0.6.7) — `@scope/package@version` no longer matched by SSH `user@host` regex
+- **curl credential redaction** (0.6.8) — `curl -u`, `--user`, and `Authorization: Basic` all redacted as `secret:HASH`
+- **`SHIELD_AUTO_UPDATE=false` ignored** (0.6.6) — env var now correctly parsed as boolean
 
 ---
 

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/cli-cases.js

@@ -48,7 +48,7 @@ function registerCasesCli(shieldCommand) {
     const cases = shieldCommand.command('cases')
         .description('List and manage Shield security cases');
     cases.action(async () => {
-        await listCases({ status: 'open', limit: '20', format: 'table', mine: false });
+        await listCases({ status: 'open', limit: '20', format: 'table' });
     });
     cases
         .command('list')
@@ -56,7 +56,6 @@ function registerCasesCli(shieldCommand) {
         .option('--status <status>', 'Filter: open, resolved, all', 'open')
         .option('--limit <n>', 'Max results', '20')
         .option('--format <fmt>', 'Output format: table or json', 'table')
-        .option('--mine', 'Show only cases from this instance')
         .action(listCases);
     cases
         .command('show')
@@ -109,37 +108,15 @@ async function listCases(opts) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    const own = result.cases.filter((c) => c.ownership === 'own').length;
-    const sibling = result.cases.filter((c) => c.ownership === 'sibling').length;
-    const unknown = result.cases.filter((c) => c.ownership === 'unknown' || c.ownership == null).length;
-    const visible = opts.mine
-        ? result.cases.filter((c) => c.is_mine === true)
-        : result.cases;
-    if (visible.length === 0 && opts.mine && result.cases.length > 0) {
-        console.log('No cases attributed to this instance. Other org instances have open cases \u2014 run without --mine to see them.');
-        return;
-    }
-    if (visible.length === 0) {
+    if (result.cases.length === 0) {
         console.log('No open cases. \u2705');
         return;
     }
-    if (sibling > 0 || (own > 0 && unknown > 0)) {
-        const parts = [];
-        if (own > 0)
-            parts.push(`${own} from this instance`);
-        if (sibling > 0)
-            parts.push(`${sibling} from other instances`);
-        if (unknown > 0)
-            parts.push(`${unknown} unattributed`);
-        console.log(`Attribution: ${parts.join(', ')}  (use --mine to filter)\n`);
-    }
-    console.log(`Cases (${visible.length} of ${result.total}):\n`);
-    for (const c of visible) {
+    console.log(`Cases (${result.cases.length} of ${result.total}):\n`);
+    for (const c of result.cases) {
         const sev = (c.severity || '').padEnd(8);
         const time = new Date(c.created_at).toLocaleString();
-        const ownershipTag = c.ownership === 'own' ? ' [mine]' :
-            c.ownership === 'sibling' ? ' [sibling]' : '';
-        console.log(`  [${sev}]${ownershipTag} ${c.id}`);
+        console.log(`  [${sev}] ${c.id}`);
         console.log(`           ${c.rule_title || c.rule_id}`);
         console.log(`           ${c.summary || ''}`);
         console.log(`           Created: ${time}  Events: ${c.event_count || 0}\n`);
@@ -161,19 +138,10 @@ async function showCase(id, opts) {
     }
     console.log(`Case: ${result.id}`);
     console.log(`Status: ${result.status}  Severity: ${result.severity}`);
-    if (result.ownership === 'sibling') {
-        console.log(`Instance: sibling (belongs to another instance in your org \u2014 you can resolve it, but local log access is unavailable)`);
-    }
-    else if (result.ownership === 'own') {
-        console.log(`Instance: this instance`);
-    }
     console.log(`Rule: ${result.rule_title || result.rule_id}`);
     console.log(`Summary: ${result.summary || '\u2014'}`);
     console.log(`Created: ${new Date(result.created_at).toLocaleString()}`);
     console.log(`Events: ${result.event_count || 0}`);
-    if (result.attribution) {
-        console.log(`\n${result.attribution}`);
-    }
     if (result.rule) {
         console.log(`\nRule: ${result.rule.description || '\u2014'}`);
         if (result.rule.mitre_tactic)

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.4",
   "skills": [
     "./skills"
   ],

package/package.json

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

@@ -31,9 +31,7 @@ Shield requires the `@upx-us/shield` plugin and an active subscription.
 | `openclaw shield logs --type TOOL_CALL --since 1h` | Filter by event type or time window |
 | `openclaw shield logs --format json` | JSON output |
 | `openclaw shield vault show` | Agent and workspace inventory, redaction summary (hashed IDs) |
-| `openclaw shield cases` | List open security cases |
-| `openclaw shield cases --mine` | List only cases from this instance |
-| `openclaw shield cases list --mine` | Show only cases from this instance |
+| `openclaw shield cases` | List open security cases (scoped to this instance) |
 | `openclaw shield cases show <ID>` | Full case detail with events, rule, playbook |
 | `openclaw shield cases resolve <ID>` | Resolve a case (--resolution, --root-cause, --comment) |
 | `openclaw shield monitor` | Case notification cron — status, --on, --off, --interval |
@@ -77,11 +75,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.
+Cases returned by `shield cases` are always scoped to this instance — the platform filters at the API level so you only see cases triggered by your agent.
 
 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.