@upx-us/shield 0.3.16 → 0.4.36

package/package.json

@@ -1,72 +1,82 @@
 {
-    "name": "@upx-us/shield",
-    "version": "0.3.16",
-    "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",
-    "bin": {
-        "shield-bridge": "dist/src/index.js",
-        "shield-setup": "dist/src/setup.js"
-    },
-    "files": [
-        "dist/index.js",
-        "dist/index.d.ts",
-        "dist/src/**/*.js",
-        "dist/src/**/*.d.ts",
-        "openclaw.plugin.json",
-        "skills/",
-        "README.md",
-        "LICENSE"
-    ],
-    "scripts": {
-        "prebuild": "npm run clean",
-        "build": "tsc",
-        "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-        "lint": "tsc --noEmit",
-        "test": "node --require tsx/cjs --test --test-reporter spec tests/**/*.test.ts tests/*.test.ts",
-        "test:watch": "node --require tsx/cjs --test --watch tests/**/*.test.ts tests/*.test.ts",
-        "test:parser": "node tests/run-parser.js",
-        "test:parser:short": "node tests/run-parser.js --short",
-        "test:parser:verbose": "node tests/run-parser.js --verbose",
-        "test:parser:help": "node tests/run-parser.js help",
-        "dev": "tsx scripts/dev-harness.ts",
-        "dev:dry": "tsx scripts/dev-harness.ts --dry-run",
-        "generate:schemas": "tsx scripts/generate-schemas.ts",
-        "package:check": "node scripts/prepublish-check.js",
-        "package:build": "npm run build",
-        "package:validate": "npm run build && npm run test && npm run package:check",
-        "package:pack": "npm pack",
-        "package:publish": "npm run package:validate && npm publish --access public",
-        "start": "node dist/src/index.js",
-        "setup": "node dist/src/setup.js"
-    },
-    "keywords": [
-        "openclaw",
-        "openclaw-plugin",
-        "security",
-        "monitoring",
-        "detection",
-        "siem",
-        "compliance"
-    ],
-    "author": "UPX Security Services",
-    "license": "SEE LICENSE IN LICENSE",
-    "publishConfig": {
-        "tag": "latest",
-        "access": "public"
-    },
-    "engines": {
-        "node": ">=20.0.0"
-    },
-    "openclaw": {
-        "extensions": [
-            "./dist/index.js"
-        ]
-    },
-    "devDependencies": {
-        "@types/node": "^25.2.3",
-        "ts-json-schema-generator": "^2.5.0",
-        "tsx": "^4.21.0",
-        "typescript": "^5.9.3"
-    }
+  "name": "@upx-us/shield",
+  "version": "0.4.36",
+  "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",
+  "bin": {
+    "shield-bridge": "dist/src/index.js",
+    "shield-setup": "dist/src/setup.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
+    "openclaw.plugin.json",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "tsc --noEmit",
+    "test": "node --require tsx/cjs --test --test-reporter spec tests/**/*.test.ts tests/*.test.ts",
+    "test:watch": "node --require tsx/cjs --test --watch tests/**/*.test.ts tests/*.test.ts",
+    "test:parser": "node tests/run-parser.js",
+    "test:parser:short": "node tests/run-parser.js --short",
+    "test:parser:verbose": "node tests/run-parser.js --verbose",
+    "test:parser:help": "node tests/run-parser.js help",
+    "dev": "tsx scripts/dev-harness.ts",
+    "dev:dry": "tsx scripts/dev-harness.ts --dry-run",
+    "generate:schemas": "tsx scripts/generate-schemas.ts",
+    "package:check": "node scripts/prepublish-check.js",
+    "package:build": "npm run build",
+    "package:validate": "npm run build && npm run test && npm run package:check",
+    "package:pack": "npm pack",
+    "package:publish": "npm run package:validate && npm publish --access public",
+    "start": "node dist/src/index.js",
+    "setup": "node dist/src/setup.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agent-monitoring",
+    "ai-security",
+    "clawhub",
+    "compliance",
+    "detection",
+    "monitoring",
+    "openclaw",
+    "openclaw-plugin",
+    "openclaw-skill",
+    "security",
+    "siem"
+  ],
+  "author": "UPX Security Services",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "tag": "latest",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "ts-json-schema-generator": "^2.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx",
+  "clawhub": {
+    "slug": "openclaw-shield-upx"
+  }
 }

package/skills/shield/README.md

@@ -0,0 +1,39 @@
+# OpenClaw Shield — Security Specialist
+
+A skill that turns your OpenClaw agent into a cybersecurity specialist.
+
+## What it does
+
+When Shield is installed, your agent can:
+
+- **Monitor** — check Shield health, event counts, and sync status
+- **Inspect** — view host agent inventory and redaction vault via `shield vault show`
+- **Interpret** — analyze security events and explain what they mean
+- **Advise** — recommend remediation, hardening, and next steps
+- **Triage** — assess alert severity and prioritize response
+- **Explain** — break down attack techniques, privacy model, and detection scope
+
+## Requirements
+
+- [OpenClaw Shield plugin](https://www.npmjs.com/package/@upx-us/shield) installed and activated
+- Active Shield subscription from [UPX](https://upx.com) — [start a free 30-day trial](https://www.upx.com/pt/lp/openclaw-shield-upx)
+
+## Install
+
+This skill is bundled with the Shield plugin. Install the plugin and the skill is available automatically:
+
+```bash
+openclaw plugins install @upx-us/shield
+openclaw shield activate <YOUR_KEY>
+openclaw gateway restart
+```
+
+## Links
+
+- **Plugin (npm)**: [@upx-us/shield](https://www.npmjs.com/package/@upx-us/shield)
+- **Skill (ClawHub)**: [openclaw-shield-upx](https://clawhub.ai/brunopradof/openclaw-shield-upx)
+- **Dashboard**: [uss.upx.com](https://uss.upx.com)
+
+## About
+
+Made by [UPX](https://upx.com) — cybersecurity engineering for critical environments.

package/skills/shield/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: openclaw-shield-upx
+description: "Security monitoring for OpenClaw agents — check Shield health, review events, inspect vault. Use when: user asks about security status, Shield health, event logs, or redaction vault. NOT for: general OS hardening, firewall config, or network security."
+metadata: {"openclaw": {"requires": {"config": ["plugins.entries.shield"]}, "homepage": "https://clawhub.ai/brunopradof/openclaw-shield-upx", "emoji": "🛡️"}}
+---
+
+# OpenClaw Shield
+
+Security monitoring for OpenClaw agents by [UPX](https://www.upx.com). Shield runs as a plugin inside the OpenClaw gateway, capturing agent activity and sending redacted telemetry to the UPX detection platform.
+
+## Getting started
+
+Shield requires the `@upx-us/shield` plugin and an active subscription.
+
+- **Plugin (npm)**: [@upx-us/shield](https://www.npmjs.com/package/@upx-us/shield)
+- **Subscribe / Free 30-day trial**: [upx.com/pt/lp/openclaw-shield-upx](https://www.upx.com/pt/lp/openclaw-shield-upx)
+- **Dashboard**: [uss.upx.com](https://uss.upx.com)
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `openclaw shield status` | Plugin health, connection state, event counts, last sync |
+| `openclaw shield flush` | Force an immediate sync to the platform |
+| `openclaw shield activate <KEY>` | One-time activation with an Installation Key |
+| `openclaw shield logs` | Recent events from the local buffer (last 24h) |
+| `openclaw shield logs --last 20` | Show last N events |
+| `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 (hashed IDs) |
+| `openclaw shield vault redactions` | Redaction summary — token categories and counts |
+| `openclaw shield cases` | List open security cases |
+| `openclaw shield cases show <ID>` | Full case detail with events, rule, playbook |
+| `openclaw shield cases resolve <ID>` | Resolve a case (--resolution, --root-cause, --comment) |
+
+## When to use this skill
+
+- "Is Shield running?" → `openclaw shield status`
+- "What did Shield capture recently?" → `openclaw shield logs`
+- "How many agents are on this machine?" → `openclaw shield vault show`
+- "Force a sync now" → `openclaw shield flush`
+- User asks about a security alert or event → interpret using your security knowledge and Shield data
+- User asks about Shield's privacy model → all data is redacted on-device before transmission; raw values never leave the machine
+
+## Status interpretation
+
+After running `openclaw shield status`, check:
+
+- **Connected** → healthy, nothing to do
+- **Disconnected** → gateway may need a restart
+- **High failure count** → platform connectivity issue, usually self-recovers; try `openclaw shield flush`
+- **Rising quarantine** → possible version mismatch, suggest checking for plugin updates
+
+## Cases
+
+Cases are created automatically when detection rules fire. Check during heartbeats via `shield.cases_list`. If `pending_count > 0`, notify the user, then call `shield.cases_ack` to mark seen.
+
+| RPC | Params | Purpose |
+|---|---|---|
+| `shield.cases_list` | `status`, `limit`, `since` | List open cases + pending notifications |
+| `shield.case_detail` | `id` | Full case with events, rule, playbook |
+| `shield.case_resolve` | `id`, `resolution`, `root_cause`, `comment` | Close a case |
+| `shield.cases_ack` | `ids` | Mark cases as notified |
+
+**Resolve values:** `true_positive`, `false_positive`, `benign`, `duplicate`
+**Root cause values:** `user_initiated`, `misconfiguration`, `expected_behavior`, `actual_threat`, `testing`, `unknown`