OpenClaw Guardian

A security layer plugin for OpenClaw that intercepts dangerous tool calls (exec, write, edit) through two-tier regex blacklist rules and LLM-based intent ver...

Security Scan

The plugin does what it says — a regex-based gate that consults the user's configured LLM(s) for flagged operations — but it reads local conversation sessions and uses your configured model credentials (so review the implementation and provider trust before enabling).

Purpose & Capability

Name/description match the code and runtime instructions: it intercepts exec/write/edit calls, applies two-tier regex blacklists, and uses LLM-based voting for flagged operations. No unrelated services or credentials are requested.

Instruction Scope

The SKILL.md and code explicitly read recent conversation session files for context and send that context to model providers for intent checks. Reading user messages is necessary for its stated 'did the user ask for this?' function, but it's a sensitive action (conversation contents may include secrets). Audit logging to ~/.openclaw/guardian-audit.jsonl is also performed for blacklist hits.

Install Mechanism

No packaged installer is included (the README suggests cloning a GitHub repo or using openclaw plugins install). The skill bundle contains the source files, so there is no hidden download step in the provided package, but manual installation instructions point to an external GitHub repo (verify source/trust before cloning).

Credentials

The plugin does not declare extra env vars, but it auto-discovers the user's OpenClaw model providers and reads provider.baseUrl and provider.apiKey from OpenClaw config to call LLM endpoints. This is proportionate to the claimed LLM voting feature but means your existing model credentials and conversation context will be used/sent to those providers — review provider trust and config privacy settings.

Persistence & Privilege

It registers a before_tool_call hook (expected for a safety gate), does not set always: true, and does not modify other plugins. It writes an audit log to the user's home directory (normal for an audit trail).

Assessment

This plugin is internally consistent with its purpose, but before installing: (1) verify the plugin source (the README suggests a GitHub repo) and review the included code yourself or from a trusted reviewer; (2) understand that Guardian will read recent conversation session files and send them to whichever model provider is configured in OpenClaw (so ensure you trust that provider and that it’s configured to not leak sensitive data); (3) check and possibly restrict which provider/config entries it can use, and review the audit log location (~/.openclaw/guardian-audit.jsonl); (4) consider lowering automatic trust (trustBudget) or testing in a safe environment before enabling broadly. If you want, I can point out specific lines to review or summarize exactly which files/fields are sent to the LLM calls.

The missing safety layer for AI agents.

Why?

OpenClaw gives agents direct access to shell, files, email, browser, and more. 99% of that is harmless. Guardian catches the 1% that isn't — without slowing down the rest.

How It Works

Tool Call → Blacklist Matcher (regex rules, 0ms)
              ↓
   No match     → Pass instantly (99% of calls)
   Warning hit  → 1 LLM vote ("did the user ask for this?")
   Critical hit → 3 LLM votes (all must confirm user intent)

Two Blacklist Levels

Level	LLM Votes	Latency	Examples
No match	0	~0ms	Reading files, git, normal ops
Warning	1	~1-2s	rm -rf /tmp/cache, chmod 777, sudo apt
Critical	3 (unanimous)	~2-4s	rm -rf ~/, mkfs, dd of=/dev/, shutdown

What Gets Checked

Only three tool types are inspected:

• exec → command string matched against exec blacklist
• write / edit → file path canonicalized and matched against path blacklist
• Everything else passes through instantly

LLM Intent Verification

When a blacklist rule matches, Guardian asks a lightweight LLM: "Did the user explicitly request this?" It reads recent conversation context to prevent false positives.

• Warning: 1 LLM call. Confirmed → proceed.
• Critical: 3 parallel LLM calls. All 3 must confirm. Any "no" → block.

Auto-discovers a cheap/fast model from your existing OpenClaw provider config (prefers Haiku). No separate API key needed.

LLM Fallback

• Critical + LLM down → blocked (fail-safe)
• Warning + LLM down → asks user for manual confirmation

Blacklist Rules

Critical (exec)

• rm -rf on system paths (excludes /tmp/ and workspace)
• mkfs, dd to block devices, redirects to /dev/sd*
• Writes to /etc/passwd, /etc/shadow, /etc/sudoers
• shutdown, reboot, disable SSH
• Bypass: eval, absolute-path rm, interpreter-based (python -c, node -e)
• Pipe attacks: curl | sh, wget | bash, base64 -d | sh
• Chain attacks: download + chmod +x + execute

Warning (exec)

• rm -rf on safe paths, sudo, chmod 777, chown root
• Package install/remove, service management
• Crontab mods, SSH/SCP, Docker ops, kill/killall

Path Rules (write/edit)

• Critical: system auth files, SSH keys, systemd units
• Warning: dotfiles, /etc/ configs, .env files, authorized_keys

Audit Log

Every blacklist hit logged to ~/.openclaw/guardian-audit.jsonl with SHA-256 hash chain — tamper-evident, each entry covers full content + previous hash.

Installation

openclaw plugins install openclaw-guardian

Or manually:

cd ~/.openclaw/workspace
git clone https://github.com/fatcatMaoFei/openclaw-guardian.git

Token Cost

Scenario	% of Ops	Extra Cost
No match	~99%	0
Warning	~0.5-1%	~500 tokens
Critical	<0.5%	~1500 tokens

Prefers cheap models (Haiku, GPT-4o-mini, Gemini Flash).

File Structure

extensions/guardian/
├── index.ts                # Entry — registers before_tool_call hook
├── src/
│   ├── blacklist.ts        # Two-tier regex rules (critical/warning)
│   ├── llm-voter.ts        # LLM intent verification
│   └── audit-log.ts        # SHA-256 hash-chain audit logger
├── test/
│   └── blacklist.test.ts   # Blacklist rule tests
├── openclaw.plugin.json    # Plugin manifest
└── default-policies.json   # Enable/disable toggle

License

MIT