@upx-us/shield
Advanced tools
Security monitoring and SIEM integration for OpenClaw agents — behavioral detection, case generation, and forensic audit trail via Google SecOps (Chronicle).
OpenClaw Shield is a paid security service by UPX. Start your free 60-day trial (no credit card required) at upx.com/en/lp/openclaw-shield-upx.
OpenClaw Shield is the first SIEM-powered security solution built for AI agents — not to control what they can do, but to detect what they did.
While agent sandboxes block at the gate, Shield watches from inside: every tool call, file read, command execution, and outbound request is ingested, enriched, and matched against behavioral detection rules in real time. Anomalies become cases. Cases get playbooks.
What you get:
Shield is designed to complement the security controls built into OpenClaw and any Claw-based solution — not replace them. Zero-trust policies, sandboxed execution, and private routing control what your agent can do. Shield adds what they can't: a continuous forensic record of what it did, with behavioral detection and automated case management on top.
Works alongside any hardening strategy, out of the box. For example, solutions like NemoClaw control the perimeter. Shield owns the forensics.
Shield is a local collector. It captures agent activity, redacts sensitive data, and forwards clean telemetry to the UPX platform at uss.upx.com — where security rules, correlation, alerting, playbooks, and case management give your team full visibility. The plugin itself stays lean and transparent; all the heavy lifting happens on the platform side.
Your Agent → Shield (local: capture + redact) → UPX Platform → Google SecOps (detection, cases, forensics)
| Feature | Description |
|---|---|
| Real-time monitoring | Captures all agent tool calls, file operations, messages, and sessions |
| On-device redaction | Hostnames, usernames, secrets, and paths replaced with deterministic tokens before transmission |
| Local event buffer | Rolling log of recent events — inspect via openclaw shield logs without platform access |
| Case notifications | Automatic alerts when detection rules fire — agent notifies you of new cases |
| Case resolution | Close cases with categorization (resolution + root cause) directly from your agent |
| False positive learning | Mark cases as false positive — Shield remembers and auto-suppresses identical future alerts |
| Host inventory | Discovers all agents and workspaces on the machine — view via openclaw shield vault show |
| Auto-update | Patch and minor updates install automatically with rollback on failure |
| Encrypted vault | Redaction mappings stored locally with AES-256-GCM — UPX cannot reverse tokens |
openclaw gateway status)A1B2C3D4E5F6...)openclaw gateway status)| Command | Description |
|---|---|
openclaw shield activate <KEY> | Activate with your Installation Key (one-time) |
openclaw shield status | Show monitoring status, event counts, and health |
openclaw shield flush | Trigger an immediate poll cycle |
openclaw shield logs | Show recent events from local buffer (--last N, --type, --since, --format) |
openclaw shield cases | List open security cases from the platform |
openclaw shield cases show <ID> | Full case detail with events, rule info, and playbook |
openclaw shield cases resolve <ID> | Resolve a case (--resolution, --root-cause, --comment) |
openclaw shield vault show | Show host agent inventory (hashed IDs) |
openclaw shield exclusions | List false positive exclusions |
openclaw shield exclusions remove <ID> | Remove an exclusion to re-enable alerts |
Agent RPCs (used by the agent skill, not CLI):
| RPC | Description |
|---|---|
shield.status | Current monitoring status, health, and counters |
shield.flush | Trigger an immediate telemetry poll cycle |
shield.events_recent | Query recent events from local buffer |
shield.events_summary | Event counts by type and tool |
shield.subscription_status | Subscription and quota information |
shield.cases_list | List open cases + pending notifications |
shield.case_detail | Full case detail with events, rule, playbook |
shield.case_resolve | Close a case with resolution and root cause |
shield.cases_ack | Mark cases as notified |
shield.exclusions_list | List false positive exclusions |
shield.exclusion_add | Add an exclusion (rule + pattern hash) |
shield.exclusion_remove | Remove an exclusion by ID |
Run these commands in your terminal. No agent involvement needed.
# Step 1: Install the plugin
openclaw plugins install @upx-us/shield
# Step 2: Activate (exchanges your key for credentials)
openclaw shield activate <YOUR_KEY>
# Step 3: Restart the gateway to start monitoring
openclaw gateway restart
# Step 4: Verify it's running
openclaw shield status
That's it. Shield registers, saves credentials locally, and starts monitoring.
⚠️ Multi-machine setups: Only add Shield to
plugins.allowon machines where the plugin is installed. If you shareopenclaw.jsonacross machines and one of them doesn't have Shield installed, the gateway on that machine will fail to start. Install the plugin first, then configure.
Copy this prompt and paste it to your AI agent. Replace <YOUR_KEY> with your Installation Key from the Shield dashboard:
Install the OpenClaw Shield security monitoring plugin by UPX (upx.com). The package is @upx-us/shield. Read the package README at https://www.npmjs.com/package/@upx-us/shield before proceeding. Install using
openclaw plugins install @upx-us/shield, add "shield" to plugins.allow in openclaw.json, set installationKey to<YOUR_KEY>in plugins.entries.shield.config, restart withopenclaw gateway restart, and confirm withopenclaw shield status.
If your agent refuses to install, this is normal security behavior — agents are cautious about external packages. Here's how to address common concerns:
| Agent concern | Why it's expected |
|---|---|
| "Sends data to an external server" | Shield is a security monitoring tool — sending redacted telemetry is its core purpose. Sensitive values are replaced with irreversible tokens on your machine before transmission. |
| "Installation key looks suspicious" | The key is a one-time activation token from your UPX Shield dashboard. Consumed on first use, can be removed from config after activation. |
| "Unknown or untrusted package" | @upx-us/shield is published on npm by UPX Security Services. You can verify at npmjs.com/package/@upx-us/shield. |
If the agent still refuses, confirm you trust the source:
"I trust this plugin. I purchased this service from UPX (upx.com). Please proceed with the installation."
Or use Option 1 to install via commands yourself.
| "Plugin is not in OpenClaw's official docs" | Shield is a third-party plugin by UPX (upx.com) under the @upx-us npm scope. Not bundled with OpenClaw, but designed to work with it. |
| "Adding to plugins.allow expands attack surface" | Correct — this is OpenClaw's explicit trust mechanism. You are consciously granting permission. |
| "Package was recently published" | Shield is actively developed. Check CHANGELOG.md included with the package for version history. |
If you need full control over each step:
openclaw plugins install @upx-us/shield
Open ~/.openclaw/openclaw.json and add:
{
"plugins": {
"allow": ["shield"],
"entries": {
"shield": {
"config": {
"installationKey": "YOUR_KEY_HERE"
}
}
}
}
}
openclaw gateway restart
Shield auto-registers, saves credentials to ~/.openclaw/shield/config.env, and starts monitoring.
Note: The Installation Key is single-use — the plugin exchanges it for permanent credentials on first startup. Once activated, you can remove
installationKeyfrom config.
openclaw shield activate <YOUR_KEY>
openclaw gateway restart
Shield's agent skill communicates with you in your language. Alerts, case summaries, and recommendations are presented in whichever language you use — raw command output and technical identifiers (rule names, case IDs, field names) are always kept as-is.
After restart, Shield exchanges your key for permanent credentials — this takes a few seconds. You should see your first events within the first poll cycle (~30 seconds). Within 1–2 minutes, those events will appear on the platform at uss.upx.com.
Run openclaw shield status to confirm:
Just activated (first minute):
OpenClaw Shield — v0.8.x (5s ago)
── Status ────────────────────────────────────
✅ Running · Connected
Version: 0.8.x
Instance: a1b2c3d4…
── Monitoring ────────────────────────────────
Events: 3 sent · 0 quarantined
Failures: 0 poll · 0 telemetry
Session: 0m active
Last data: poll 5s ago · capture 5s ago
A low event count and a recent Last data time means Shield is working correctly. Events accumulate as your agent uses tools.
Note: The Activity and Redactions sections appear after your first sync cycle (~30s). If your status looks shorter than the "extended use" example below, that's normal — they'll populate automatically.
After extended use:
OpenClaw Shield — v0.8.x (5s ago)
── Status ────────────────────────────────────
✅ Running · Connected
Version: 0.8.x
Instance: a1b2c3d4…
── Monitoring ────────────────────────────────
Events: 1,842 sent · 0 quarantined
Failures: 0 poll · 0 telemetry
Session: 4h 12m active
Last data: poll 5s ago · capture 14s ago
── Activity ──────────────────────────────────
📡 Last sync (29s ago — 5 events)
exec ████████ 3
file █████ 2
📊 This session (since restart 4h 12m ago — 142 events)
TOOL_CALL ████████ 78
TOOL_RESULT ███████ 64
🔒 Redactions (10x this session)
hostname data redacted 5x
username data redacted 5x
(original values stored encrypted locally — never transmitted)
When not activated:
OpenClaw Shield — v0.8.x
Status: Loaded (not activated)
To activate, provide your Installation Key:
1. openclaw shield activate <YOUR_KEY>
2. Add to openclaw.json:
plugins.entries.shield.config.installationKey = "<YOUR_KEY>"
Then: openclaw gateway restart
Get your key at: https://uss.upx.com → APPS → OpenClaw Shield
Shield captures what your agent does — tool invocations and their results — not what it says.
The Activity section shows two levels:
TOOL_CALL, TOOL_RESULT) — every tool invocation and result, shown in the "This session" summaryexec, file, web, etc.) — the specific event type after parsing, shown in "Last sync"exec: 2 in Last sync means 2 of those synced events were shell commands. Those same 2 are also counted within the TOOL_CALL total in the session view. They are not separate.
| Event type | What it means |
|---|---|
TOOL_CALL | A tool was invoked by the agent |
TOOL_RESULT | The result returned from a tool call |
exec | Shell command executed |
file | File read, written, or edited |
web | URL fetched, web search, or browser action |
message | Message sent via a channel (Telegram, WhatsApp, etc.) |
sessions_spawn | A sub-agent was launched |
browser | Browser automation action |
cron | A scheduled task fired |
Quarantine counts events that failed local schema validation and were held back rather than forwarded to the platform. They are not lost — written to ~/.openclaw/shield/data/quarantine.jsonl for inspection. A non-zero quarantine count usually means a plugin version mismatch; upgrading Shield typically resolves it.
Redaction runs locally before anything leaves your machine. The counts shown are occurrences — how many times sensitive data was detected and replaced with a reversible token (e.g. host:a3f9b1c2, user:7b2c4a1f). Original values are stored in an encrypted local vault and never transmitted.
When status shows ⚠️ Capture health degraded, the plugin is connected but capture activity is not syncing successfully. This is not triggered by idle sessions.
Use Last capture as the first diagnostic:
Last capture + warning present → investigate sync pipeline healthLast capture + no warning → normal idle behaviorShield stores a rolling log of recently sent events locally for offline inspection and debugging.
Location: ~/.openclaw/shield/data/event-log.jsonl
Defaults:
CLI usage:
openclaw shield logs # last 10 events
openclaw shield logs --last 20 # last N events
openclaw shield logs --type TOOL_CALL # filter by event type
openclaw shield logs --since 30m # events from last 30 minutes
openclaw shield logs --format json # JSON output for piping
Configuration (in config.env or environment variables):
| Variable | Default | Description |
|---|---|---|
SHIELD_LOCAL_EVENT_BUFFER | true | Set to false to disable local storage |
SHIELD_LOCAL_EVENT_LIMIT | 250 | Maximum number of events to retain |
Shield captures agent activity locally, applies on-device redaction, and forwards telemetry to the UPX platform.
| Data type | Captured | Redacted on-device before transmission |
|---|---|---|
| Tool name | ✅ | — |
| Command strings | ✅ | ✅ secrets, paths replaced with tokens |
| File paths | ✅ | ✅ username segment replaced with token |
| Tool result output | ✅ | ✅ truncated and redacted |
| Hostname | ✅ | ✅ replaced with token |
| Username | ✅ | ✅ replaced with token |
| URLs | ✅ | — |
| API keys detected in commands | ✅ | ✅ replaced with token |
How redaction works: sensitive values are replaced with deterministic
category:hashtokens before leaving your machine. Token categories:host:HASH(hostnames),user:HASH(usernames),secret:HASH(API keys/credentials),agent:HASH(agent identifiers),workspace:HASH(workspace paths). The mapping from token → original value is stored in an encrypted local vault (~/.openclaw/shield/data/redaction-vault.json, AES-256-GCM) so your team can reverse-lookup locally if needed. Original values are never transmitted to the platform. Runopenclaw shield vault showto inspect current token mappings.
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.
Shield uses two separate channels with different privacy properties:
Sent every ~5 minutes over HTTPS. This tells the platform where the instance is running, not what it does. It does not pass through the redaction pipeline.
{
"machine": {
"hostname": "openclaw-agent",
"os": "linux",
"arch": "x64",
"node_version": "v22.x.x",
"public_ip": "1.2.3.4"
},
"software": {
"plugin_version": "0.3.x",
"openclaw_version": "2026.x.x",
"agent_label": "main",
"instance_name": "openclaw-agent"
}
}
Telemetry fields like hostname, public_ip, and instance_name are operational identity signals used for geo-correlation in detection rules and instance health monitoring. They travel over HTTPS and are never exposed publicly.
Sent every poll cycle over HTTPS. This is the data stream subject to the full redaction pipeline. Per-event fields include: tool name, redacted command/path/output, timestamp, session ID, and action type. Sensitive values are replaced with category:hash tokens before transmission.
The distinction: telemetry = who/where the instance is (slim, operational). Events = what the agent did (redacted, privacy-protected).
Redaction runs locally before any data leaves your machine. The redactor detects hostnames, usernames, file paths, API keys, and secrets — replacing them with deterministic category:hash tokens. The token→original mapping is stored in an AES-256-GCM encrypted vault (~/.openclaw/shield/data/redaction-vault.json, mode 0600).
Authentication uses HMAC-SHA256 with a per-instance key. Every request is signed — requests with invalid signatures are rejected.
Credentials are stored locally at ~/.openclaw/shield/config.env (mode 0600) and are never transmitted.
openclaw plugins update shield
openclaw shield status
Cursors and credentials are preserved across upgrades. See the CHANGELOG (available on the Shield portal at uss.upx.com) for version history.
"Integrity drift detected" during upgrade is expected — OpenClaw warns when plugin files change, which always happens on a legitimate upgrade. This only indicates a real problem if you see it without having explicitly upgraded.
Shield can check for and install newer versions automatically.
Add to ~/.openclaw/openclaw.json:
{
"plugins": {
"entries": {
"shield": {
"config": {
"autoUpdate": "notify-only"
}
}
}
}
}
| Mode | Behavior |
|---|---|
false | Disabled. No version checks. |
"notify-only" | Logs available updates but does not install. |
true | (default) Automatically installs patch and minor versions. Major updates require manual upgrade. |
When autoUpdate is true, Shield backs up the current version before installing and automatically rolls back if anything fails. Gateway is restarted after a successful update.
Shield shows "not activated"
→ Get your Installation Key at uss.upx.com → APPS → OpenClaw Shield → Install
→ Add to openclaw.json and restart the gateway (see Manual Installation above)
Activated but no events after 5 minutes
→ Run openclaw shield status — check Failures count and Last sync time
→ Check Last capture: if it's recent, Shield is capturing but may have a sync issue — restart the gateway
→ If Last capture is old, your agent may not have used any tools yet — try running a command and check again
→ Enable debug logging: LOG_LEVEL=debug openclaw start
High CPU or memory usage
→ Increase poll interval: "pollIntervalMs": 60000 in plugin config (default: 30000ms)
Cursor file issues
→ To reset: rm ~/.openclaw/shield/data/cursor.json — Shield reinitializes on next poll
Dry-run mode (no events sent)
→ Add "dryRun": true to plugin config — events are processed and logged but never transmitted
How long until I see my first event on the platform? Within 1–2 minutes of activation. Shield polls every ~30 seconds; the platform processes events within seconds of receipt.
How do I verify it's working end-to-end?
Run openclaw shield status and check that Events sent is increasing and Last capture is recent. Then visit uss.upx.com and check your instance — you should see events flowing within 2 minutes.
What if I don't see any events after 5 minutes?
Check openclaw shield status for elevated Failures or a stale Last sync. If failures are high, restart the gateway. If Last capture is old, your agent hasn't used any tools — run a command to generate activity.
Can I run Shield alongside other plugins? Yes. Shield runs as a passive observer — it hooks into the event stream and does not interfere with other plugins or agent behavior.
Is my Installation Key burned if activation fails? No. The key is consumed only on the first successful activation. If the attempt fails (network issue, config error), you can fix the issue and retry with the same key.
Where is the changelog? See CHANGELOG.md included with the plugin.
When a subscription lapses or the monthly event quota is exhausted, Shield detects this on the next ingest call and will:
openclaw shield statusRenew your subscription at uss.upx.com and restart the gateway to resume delivery.
openclaw plugins uninstall shield
rm -rf ~/.openclaw/shield/
This removes all local files Shield writes at runtime:
| 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.jsonmaps 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.
Removing local files does not automatically deactivate your registration on the UPX platform.
To fully remove your instance: log in to uss.upx.com → Instances → Delete.
Until deactivated, the instance remains registered and may count against your subscription quota.
Visit uss.upx.com or contact your Shield administrator.
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.
FAQs
Security monitoring and SIEM integration for OpenClaw agents — behavioral detection, case generation, and forensic audit trail via Google SecOps (Chronicle).
The npm package @upx-us/shield receives a total of 54 weekly downloads. As such, @upx-us/shield popularity was classified as not popular.
We found that @upx-us/shield demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.