Clawshield

Name: Clawshield
Rating: 3.5 (1 reviews)
Author: BaeriShapira

By BaeriShapira 👁 134 views ▲ 0 votes

Real-time security enforcement plugin for OpenClaw AI agents

GitHub

Install

npm install openclaw-shield

Configuration Example

{
  "plugins": {
    "openclaw-shield": {
      "enforcement": { "enabled": true },
      "injection":   { "enabled": true, "threshold": 70 },
      "audit":       { "enabled": true },
      "alerting":    { "enabled": true, "console": true },
      "dashboard":   { "enabled": true, "port": 18790 }
    }
  }
}

README

# ClawShield

Real-time security plugin for [OpenClaw](https://openclaw.dev) — prompt injection detection, action enforcement, audit logging, and live monitoring dashboard.

---

## Features

- **Enforcer** — blocks dangerous shell commands before they run (tiered pattern matching)
- **Detector** — scans incoming messages and tool results for prompt injection attempts
- **Recorder** — append-only JSONL audit log with rotation and retention policies
- **Dashboard** — live browser UI with WebSocket feed of security events

---

## Installation

```bash
# In your OpenClaw plugins directory
npm install openclaw-shield
```

Or clone and build locally:

```bash
git clone https://github.com/baerishapira/clawshield openclaw-shield
cd openclaw-shield
npm install
npm run build
```

---

## Quick Start

Add the plugin to your `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "openclaw-shield": {
      "enforcement": { "enabled": true },
      "injection":   { "enabled": true, "threshold": 70 },
      "audit":       { "enabled": true },
      "alerting":    { "enabled": true, "console": true },
      "dashboard":   { "enabled": true, "port": 18790 }
    }
  }
}
```

Set your dashboard token (required):

```bash
export SHIELD_DASHBOARD_TOKEN="your-secret-token"
```

Start OpenClaw — ClawShield loads automatically and prints:

```
[info] ClawShield v0.1.0 loaded — Enforcer, Detector, Recorder, Dashboard active
```

Open the dashboard at **http://127.0.0.1:18790**.

---

## Configuration Reference

All settings are optional; sensible defaults apply.

### Enforcement

```json
"enforcement": {
  "enabled": true,
  "strictMode": false,
  "rules": []
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `enabled` | `true` | Master switch for all blocking |
| `strictMode` | `false` | Block on internal errors (fail-safe) |
| `rules` | `[]` | Custom allow/deny/rate-limit rules |

**Custom rule example:**

```json
{
  "type": "deny_pattern",
  "tool": "bash",
  "pattern": "curl.*internal\\.corp",
  "reason": "No external calls to internal hosts"
}
```

Rule types: `deny_pattern` · `allow_pattern` · `rate_limit`

### Injection Detection

```json
"injection": {
  "enabled": true,
  "threshold": 70,
  "scanToolResults": true,
  "scanToolsFilter": ["web_fetch", "web_search", "read", "memory_get"]
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `enabled` | `true` | Master switch |
| `threshold` | `70` | Score 0–100 above which content is blocked |
| `scanToolResults` | `true` | Also scan tool output |
| `scanToolsFilter` | see above | Only scan these tools' output |

### Audit Logging

```json
"audit": {
  "enabled": true,
  "path": "~/.openclaw/shield-audit.jsonl",
  "maxSizeMb": 100,
  "retentionDays": 30,
  "redactArgValues": true
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `path` | `~/.openclaw/shield-audit.jsonl` | Log file path |
| `maxSizeMb` | `100` | Rotate at this size |
| `retentionDays` | `30` | Delete rotated files older than N days |
| `redactArgValues` | `true` | Log arg keys only, not values |

### Alerting

```json
"alerting": {
  "enabled": true,
  "deduplicationWindowSec": 60,
  "console": true,
  "session": null,
  "webhook": null
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `console` | `true` | Print to stderr |
| `session` | `null` | OpenClaw session target (e.g. `"agent:main:slack:dm:@you"`) |
| `webhook` | `null` | URL for HTTP POST JSON payloads |
| `deduplicationWindowSec` | `60` | Suppress duplicate alerts within this window |

### Dashboard

```json
"dashboard": {
  "enabled": true,
  "port": 18790,
  "host": "127.0.0.1",
  "auth": "${SHIELD_DASHBOARD_TOKEN}"
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `port` | `18790` | Local HTTP port |
| `host` | `127.0.0.1` | Bind address — keep local |
| `auth` | env var | Bearer token for HTTP auth |

---

## Enforcement Tiers

### Tier 1 — Always Blocked

No configuration can override these. Examples:

| Rule ID | What it blocks |
|---------|---------------|
| `DENY_RM_RF` | `rm -rf /` and variants |
| `DENY_DD_WIPE` | Hard drive wipe via `dd` |
| `DENY_CURL_PIPE_BASH` | `curl | bash` — remote code exec |
| `DENY_BASE64_PIPE_BASH` | `base64 -d | bash` — obfuscated exec |
| `DENY_CAT_SSH_KEY` | Reading private SSH keys |
| `DENY_CAT_AWS_CREDS` | Reading AWS credential files |
| `DENY_CAT_SHADOW` | Reading `/etc/shadow` |
| `DENY_MKFS` | Formatting a filesystem |
| `DENY_FORK_BOMB` | Fork bomb (`:() {:|:&};:`) |

### Tier 2 — Blocked by Default, Configurable

High-risk actions that can be allowed via `allow_pattern` rules:

| Rule ID | What it blocks |
|---------|---------------|
| `DENY_EVAL` | `eval $(...)` — dynamic code exec |
| `DENY_SUDO_SHELL` | `sudo bash/sh` — root shell |
| `DENY_CHMOD_777_ROOT` | `chmod 777 /` |
| `DENY_CRONTAB_WRITE` | Writing cron files |
| `DENY_SYSTEMCTL_ENABLE` | Enabling services on boot |
| `DENY_ENV_DUMP_SECRETS` | `env | grep secret` |
| `DENY_IPTABLES_FLUSH` | Flushing all firewall rules |
| `DENY_PASSWD_CHANGE` | `passwd` / `chpasswd` |
| `DENY_USERADD_ROOT` | Adding user to root group |
| `DENY_VISUDO` | Modifying sudoers |

### Tier 3 — Monitor Only

Logged and alerted but not blocked:

`MONITOR_NMAP` · `MONITOR_NETSTAT` · `MONITOR_PS_AUX` · `MONITOR_PYTHON_EXEC` · `MONITOR_NODE_EXEC` · `MONITOR_NC_REVERSE` · `MONITOR_TCPDUMP`

---

## Audit Log Format

Each line is a JSON object:

```json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-06-01T12:34:56.789Z",
  "shieldVersion": "0.1.0",
  "sessionKey": "sess_abc123",
  "channel": "slack:general",
  "authorHash": "sha256:...",
  "eventType": "tool_blocked",
  "toolName": "bash",
  "toolArgKeys": ["command"],
  "toolArgSummary": "command=rm -rf /…",
  "outcome": "blocked",
  "blockReason": "Destructive recursive deletion",
  "ruleId": "DENY_RM_RF",
  "durationMs": 0.4
}
```

Event types: `tool_allowed` · `tool_blocked` · `injection_detected` · `injection_flagged` · `message_scanned` · `alert_sent` · `session_end`

---

## License

MIT

tools