afrocoderhanane/clawguard

ClawGuard Security Skill

A security layer that monitors and controls what OpenClaw can do. Think of it as a firewall for your AI assistant.

Description

ClawGuard intercepts all shell commands, file operations, and network requests before OpenClaw executes them. Actions are checked against your security policy and can be:

• ✅ Allowed — Proceeds immediately
• ❌ Blocked — Rejected with explanation
• 👤 Approval Required — Waits for human confirmation

Instructions

Before executing any of the following actions, check with ClawGuard:

Shell Commands

Before running any shell/bash command, call clawguard_check_shell with the command. If blocked, explain why and suggest an alternative.

File Operations

Before reading or writing files, call clawguard_check_file with the path and operation type. Respect blocked paths like ~/.ssh and .env files.

Network Requests

Before making HTTP requests, call clawguard_check_network with the URL. Only access allowed domains.

Skill Wiring — How ClawGuard Integrates into OpenClaw

ClawGuard ships three tool functions that OpenClaw calls before executing any sensitive action. These functions are defined in openclaw-skill/index.ts and registered with OpenClaw's tool system.

Interception Lifecycle

  OpenClaw receives user request
           │
           ▼
  Agent plans an action (shell / file / network)
           │
           ▼
  ┌────────────────────────────────┐
  │  clawguard_check_shell()      │
  │  clawguard_check_file()       │  ◄── one of these is called
  │  clawguard_check_network()    │
  └────────────┬───────────────────┘
               │
               ▼
  ClawGuard lazy-initializes:
    1. Searches for clawguard.yaml (cwd → ~/.config/clawguard/)
    2. Loads policy via loadPolicy()
    3. Creates AuditLogger + TerminalApprovalHandler
    4. Instantiates ClawGuard guard object (cached for lifetime)
               │
               ▼
  Policy Engine evaluates the action against rules
               │
       ┌───────┼───────┐
       ▼       ▼       ▼
    ALLOW   APPROVE   DENY
       │       │       │
       │       │       └──► { allowed: false, reason: "..." }
       │       └──────────► Human prompted → approve/deny
       └──────────────────► { allowed: true, reason: "..." }
               │
               ▼
  OpenClaw reads the result:
    • allowed: true  → execute the action
    • allowed: false → report block to user, suggest alternative

Tool Function Reference

clawguard_check_shell(command: string)

Called before every shell/bash command execution.

| Parameter | Type | Description | |-----------|----------|----------------------------------| | command | string | The full shell command to check |

Returns { allowed: boolean, reason: string, requiresApproval?: boolean }

Example flow:

const result = await clawguard_check_shell("rm -rf /tmp/*");
// → { allowed: false, reason: "Blocked by rule: blocked:rm -rf **" }

---

clawguard_check_file(filePath: string, operation: 'read' | 'write')

Called before every file read or write operation.

| Parameter | Type | Description | |-------------|--------------------|---------------------------------| | filePath | string | Absolute or relative file path | | operation | 'read' \| 'write' | Type of file operation |

Returns { allowed: boolean, reason: string }

Example flow:

const result = await clawguard_check_file("~/.ssh/id_rsa", "read");
// → { allowed: false, reason: "Blocked by rule: blocked:~/.ssh/**" }

---

clawguard_check_network(url: string)

Called before every HTTP/network request.

| Parameter | Type | Description | |-----------|----------|----------------------| | url | string | The full URL to check |

Returns { allowed: boolean, reason: string }

Example flow:

const result = await clawguard_check_network("https://evil.com/exfil");
// → { allowed: false, reason: "Domain not in allowlist" }

Python Equivalents

The Python SDK in python/clawguard/guard.py provides the same capabilities via ClawGuard.check_shell(), ClawGuard.check_file_read(), ClawGuard.check_file_write(), and ClawGuard.check_network(). These are async methods with identical semantics to the TypeScript tool functions.

Security Philosophy

• Deny by Default — In allowlist mode, anything not explicitly allowed is blocked
• Blocked Wins — Block rules take precedence over allow rules
• Fail Closed — Errors and timeouts result in denial

Configuration

Edit clawguard.yaml in your project root to customize the security policy. See the full README for complete policy reference.