ClawGuard 🛡️

Security middleware for OpenClaw skills. Provides permission manifests, runtime enforcement, and audit logging.

The problem: Skills are code from the internet. Like npm packages, they can do anything once installed. ClawGuard adds a permission layer so skills must declare what they need, and you can enforce those limits.

Quick Start

# Install
npm install -g clawguard

# Initialize permissions for a skill
clawguard init ./my-skill

# Validate a skill's permissions
clawguard validate ./my-skill

# Check status
clawguard status

How It Works

1. Skills include a permissions.json declaring what they need
2. ClawGuard validates the manifest at install time
3. At runtime, ClawGuard checks actions against declared permissions
4. Violations are blocked (or warned/logged, depending on mode)

Permission Manifest

Create permissions.json in your skill directory:

{
  "version": "1.0",
  "skill": {
    "name": "my-cool-skill",
    "version": "1.0.0",
    "description": "Does cool things"
  },
  "permissions": {
    "filesystem": {
      "read": ["./data/**", "${WORKSPACE}/config.json"],
      "write": ["./output/**"],
      "delete": []
    },
    "network": {
      "outbound": ["api.example.com", "*.github.com"],
      "inbound": false,
      "ports": []
    },
    "exec": {
      "allowed": true,
      "commands": ["git", "npm run"],
      "shell": false
    },
    "env": {
      "read": ["HOME", "PATH", "API_KEY"],
      "write": []
    },
    "openclaw": {
      "sessions": false,
      "cron": false,
      "messages": true,
      "browser": false,
      "nodes": false
    }
  },
  "rationale": {
    "filesystem": "Reads config, writes results to output/",
    "network": "Calls example.com API, fetches from GitHub",
    "exec": "Uses git for version control"
  }
}

Enforcement Modes

ClawGuard supports four modes, configurable globally or per-skill:

Mode	Behavior
enforce	Block disallowed actions (default)
warn	Log warning, allow action
audit	Silent logging only
disabled	ClawGuard is completely off

# Set global mode
clawguard mode warn

# Set mode for specific skill
clawguard skill-mode untrusted-skill enforce

# Trust a skill (bypasses all checks)
clawguard trust my-trusted-skill

Environment Variables

# Override mode
CLAWGUARD_MODE=warn

# Disable entirely
CLAWGUARD_DISABLED=true

# Emergency: block ALL skill actions
CLAWGUARD_KILL_SWITCH=true

Kill Switch

If something goes wrong, enable the kill switch to block ALL skill actions immediately:

clawguard kill-switch on   # Block everything
clawguard kill-switch off  # Resume normal operation

Audit Logging

Every permission check is logged to ~/.config/clawguard/audit.log:

# View recent logs
clawguard audit --tail 100

# Verify log integrity (tamper detection)
clawguard audit --verify

Logs are append-only with hash chaining for tamper evidence.

Programmatic Usage

import { Guard, getConfig } from 'clawguard';

// Create guard for a skill
const guard = new Guard('./path/to/skill');

// Check permissions (throws ClawGuardError if blocked)
guard.guardFileRead('/some/path');
guard.guardNetworkOutbound('https://api.example.com');
guard.guardExec('git status');
guard.guardOpenClaw('messages');

// Check without throwing
const result = guard.checkFileWrite('/some/path');
if (!result.allowed) {
  console.log('Denied:', result.reason);
}

// Config management
const config = getConfig();
config.setMode('warn');
config.trustSkill('known-good-skill');
config.enableKillSwitch();  // Emergency stop

Permission Categories

Filesystem

• read: Glob patterns for readable paths
• write: Glob patterns for writable paths
• delete: Glob patterns for deletable paths (high risk)

Variables: ${WORKSPACE}, ${HOME}

Network

• outbound: Allowed hosts (api.example.com, *.github.com, *)
• inbound: Whether the skill can listen on ports
• ports: Specific ports allowed for inbound

Exec

• allowed: Whether process spawning is permitted
• commands: Allowed command prefixes (git, npm run)
• shell: Whether shell operators (|, &&, ;) are allowed

Env

• read: Environment variables the skill can read
• write: Environment variables the skill can modify

OpenClaw

• sessions: Interact with other sessions
• cron: Create/modify cron jobs
• messages: Send messages to channels
• browser: Use browser automation
• nodes: Interact with paired nodes

Security Considerations

ClawGuard is defense-in-depth, not a sandbox. A malicious skill could potentially bypass checks if it's sophisticated enough. Use ClawGuard as one layer of protection, not your only one.

Audit your skills. The permission manifest tells you what a skill claims to need. Review the actual code too.

Start with enforce mode. Only relax to warn or audit for debugging, then switch back.

Treat shell: true as dangerous. Shell execution allows arbitrary command chaining.

CLI Reference

clawguard validate <skill-dir>        Validate permissions.json
clawguard init <skill-dir>            Create template permissions.json
clawguard audit [--tail N]            View audit logs
clawguard audit --verify              Verify log integrity
clawguard config                      Show configuration
clawguard config --reset              Reset to defaults
clawguard trust <skill>               Bypass checks for skill
clawguard untrust <skill>             Remove from trusted
clawguard mode <mode>                 Set global mode
clawguard skill-mode <skill> <mode>   Set skill-specific mode
clawguard kill-switch [on|off]        Emergency stop
clawguard status                      Show current status

Contributing

Issues and PRs welcome at https://github.com/newtro/ClawGuard

License

MIT