Defense-in-depth security for OpenClaw agents.
Protects against session corruption, prompt injection, data exfiltration, and unauthorized actions — without sacrificing agent functionality. 9 defense layers, enforced at the gateway level, outside the agent's control.
Version: 0.6.0 · Author: @yassinebkr · License: MIT
OpenClaw gives your AI agent access to tools, files, messages, and shell commands. A single prompt injection hidden in a web page, email, or document can hijack your agent into:
- 🔓 Exfiltrating API keys, credentials, or private data
- 💻 Running arbitrary commands on your machine
- 📨 Sending messages on your behalf
- 🧠 Modifying its own system prompt to stay compromised
ProteClaw blocks these attacks at the gateway — the agent can't override it.
# Install
openclaw plugins install github:yassinebkr/proteclaw
# Restart gateway
openclaw gateway restart
# Verify
# Type /proteclaw in any chat sessionManual installation
git clone https://github.com/yassinebkr/proteclaw.git ~/.openclaw/extensions/proteclawAdd to ~/.openclaw/openclaw.json:
{
"plugins": {
"entries": {
"proteclaw": { "enabled": true }
}
}
}Restart: openclaw gateway restart
Gateway Start
├─ L0 Session Integrity ───── Validate & repair all session files
└─ L5 Bootstrap Integrity ─── Snapshot protected file hashes
User Message
├─ L4 Signal Detection ────── Scan inbound for injection patterns
└─ LC Threat Clear ────────── Reset restrictions on new user message
Before Agent Turn
├─ L0 Session Repair ──────── Fix corrupted messages (orphaned tool_results)
├─ L1 Context Tagging ─────── Tag trust level & source
└─ 🐤 Canary Token ────────── Inject exfiltration tripwire
Agent Calls Tool
├─ LC Privilege Separation ── BLOCK dangerous tools if threat detected
└─ LF File Write Guard ───── BLOCK writes to critical files (SOUL.md, etc.)
Tool Returns Result
├─ L4+ External Scanner ───── Scan result for indirect injection
├─ 🐤 Canary Check ────────── Detect system prompt leaks
└─ L1 Provenance Tag ─────── Tag source & trust metadata
| Layer | Name | What It Does |
|---|---|---|
| L0 | Session Integrity | Validates JSONL sessions. Detects/repairs orphaned tool_result messages and error-terminated tool calls. Repairs persisted to disk with backup. |
| L1 | Content Tagging | Tags every tool result with provenance: [proteclaw:source=web_fetch,trust=verified,t=...]. Full audit trail. |
| L4 | Signal Detection | 50+ patterns for injection, exfiltration, encoding, and roleplay attacks in inbound messages. |
| L4+ | External Scanner | 16 specialized patterns + instruction density heuristic for indirect injection in tool results (web pages, search results, fetched documents). |
| LC | Privilege Separation | Blocks dangerous tools (exec, write, edit, message, gateway) when a confirmed threat is detected. Enforced at gateway level. |
| LF | File Write Guard | Blocks writes to critical files (SOUL.md, AGENTS.md, openclaw.json). The agent cannot modify its own identity. |
| 🐤 | Canary Token | Random secret injected into context. If it appears in any tool result → confirmed exfiltration attack. |
| Layer | Name | Description |
|---|---|---|
| L2 | Capability Control | Manifest-based tool permissions |
| L3 | Runtime Security | Behavioral anomaly detection |
| L5 | Trust Registry | Cryptographic hash pinning for file integrity |
This is the core defense. The key insight: the gateway enforces policy, not the agent.
Agent reads web page
→ L4+ scans result: 3 injection patterns detected
→ Session enters restricted mode
→ Agent tries exec("curl ...") → ❌ BLOCKED at gateway
→ Agent tries write("~/.ssh/...") → ❌ BLOCKED at gateway
→ User sends new message → ✅ Restriction lifted
Layer C reduces false positives with a smart threshold:
| Condition | Action |
|---|---|
| 3+ distinct signals (confidence ≥ 0.8) | 🔴 Confirmed attack → tools blocked |
| 1 signal at ≥ 0.95 confidence | 🔴 Unambiguous attack → tools blocked |
| 1-2 signals below 0.95 | 🟡 Advisory logged, tools remain available |
This prevents lockouts when the agent reads content that discusses injection (security docs, its own memory) vs. content that is injection.
| Blocked (during threat) | Always allowed |
|---|---|
exec, write, edit, message, gateway, sessions_send |
read, web_search, web_fetch, browser, image, session_status, process |
| Pattern | Confidence | Catches |
|---|---|---|
hidden_instruction_tag |
0.90 | [hidden instruction], [hidden prompt] |
important_instruction_for_ai |
0.90 | "IMPORTANT INSTRUCTION FOR THE AI" |
hide_from_user |
0.90 | "do not tell/show/reveal the user" |
css_hidden_injection |
0.90 | CSS-hidden text with instructions |
indirect_override |
0.85 | "AI, please ignore/disregard/forget..." |
html_comment_injection |
0.85 | <!-- system, <!-- instruction |
secret_action |
0.85 | "secretly/silently/without telling" |
claim_reprogrammed |
0.85 | "you have been reprogrammed" |
new_objective |
0.85 | "new objective:", "new directive:" |
exfil_to_endpoint |
0.85 | "send/post/upload to https://..." |
execute_command |
0.80 | "execute this command:" |
exfil_via_response |
0.80 | "append the contents of... to response" |
redefine_goal |
0.80 | "from now on, your primary task..." |
code_execution_call |
0.75 | run(", exec(", eval(" |
zero_width_chars |
0.70 | Invisible zero-width character sequences |
| instruction_density | 0.50–0.95 | Heuristic: many imperative verbs in short text |
Plus 50+ standard L4 patterns for direct injection, exfiltration, encoding abuse, and roleplay attacks.
All active layers are enabled by default. Configure in ~/.openclaw/openclaw.json:
{
"plugins": {
"entries": {
"proteclaw": {
"enabled": true,
"config": {
"layers": {
"integrity": true,
"tagging": true,
"signals": true,
"privilegeSeparation": true
},
"signals": {
"minConfidence": 0.5,
"suppressCategories": [],
"alertOnHighSeverity": true
},
"logLevel": "info"
}
}
}
}
}| Command | Description |
|---|---|
/proteclaw |
Full security dashboard |
/proteclaw-scan |
Manual session integrity scan |
/proteclaw-signals |
Signal detection stats |
/proteclaw-integrity |
Bootstrap file integrity report |
| Tier | Files | On Write Attempt |
|---|---|---|
| 🚨 Critical | SOUL.md, AGENTS.md |
Blocked + alert + hash verification |
USER.md, IDENTITY.md, MEMORY.md, TOOLS.md |
Warning + hash tracking | |
| ℹ️ Tracked | BOOTSTRAP.md |
Logged |
- ✅ Session file corruption (orphaned tool_results, error-terminated calls)
- ✅ Direct prompt injection in user messages
- ✅ Indirect prompt injection in web pages, search results, documents
- ✅ System prompt exfiltration (canary tripwire)
- ✅ Unauthorized modification of identity/config files
- ✅ Dangerous tool execution after external content ingestion
⚠️ Novel injection techniques — pattern matching catches known patterns, not zero-days⚠️ Subtle reasoning influence — injection may influence the agent's thinking without triggering detection⚠️ Agent self-verification is unreliable — a compromised agent will report "all clean"
Never trust the agent to verify its own integrity after exposure to untrusted content.
Layer C addresses this by making the gateway — not the agent — the enforcement point. Even a fully compromised agent cannot execute blocked tools. But for complete verification, always check independently:
- File hashes via SSH
- Raw JSONL session logs for unexpected tool calls
- Network connections independently
Recommended OpenClaw settings to prevent runaway API costs
These aren't part of ProteClaw itself — they're OpenClaw gateway settings. But without them, a heavy session can burn $100+ in hours.
Add to agents.defaults in openclaw.json:
{
"contextPruning": {
"mode": "cache-ttl",
"ttl": "5m",
"keepLastAssistants": 3,
"softTrimRatio": 0.3,
"hardClearRatio": 0.5,
"minPrunableToolChars": 50000,
"softTrim": { "maxChars": 4000, "headChars": 1500, "tailChars": 1500 },
"hardClear": { "enabled": true, "placeholder": "[Old tool result cleared]" }
},
"compaction": {
"mode": "default",
"reserveTokensFloor": 200000,
"memoryFlush": { "enabled": true, "softThresholdTokens": 50000 }
}
}| Setting | Effect |
|---|---|
contextPruning: cache-ttl |
Trims old tool results after Anthropic cache expires (5min) |
compaction.reserveTokensFloor: 200000 |
Triggers compaction at ~800k instead of ~984k |
memoryFlush |
Writes important context to disk before compaction |
~/.openclaw/extensions/proteclaw/
├── index.ts # Plugin source (~2700 lines)
├── openclaw.plugin.json # Manifest & config schema
└── README.md
Standalone library: 492 tests across 21 files. Plugin stress tests: 89 tests, 222k messages/sec.
Safe testing protocol — never read injection test content in the main session:
- Write test file from main session
- Spawn isolated sub-agent to read it
- Check gateway logs for detection events
- Delete the test file
| Hook | Layers | Purpose |
|---|---|---|
gateway_start |
L0, L5 | Startup scan + registry init |
message_received |
L4, LC | Inbound scan + threat clear |
before_agent_start |
L0, L1, L4, 🐤 | Session validation + context injection |
tool_result_persist |
L1, L4+, 🐤 | Tagging + external scan + canary check |
before_tool_call |
LC, LF | Privilege separation + file guard |
- Renamed from ClawOS to ProteClaw
- LC: Multi-signal threshold — requires 3+ signals OR 1 at ≥0.95 to block tools. Eliminates false lockouts.
- Removed
memory_searchfrom external scanning — own memory is trusted, not an attack surface. - Tuned overly broad patterns —
system_prompt_inject0.85→0.6,redefine_behavior0.7→0.5. - Advisory logging — sub-threshold signals logged without disruption.
- Token & cost management guide.
- L0: Disk persistence for session repairs (prevents repair loops on restart).
- LF: File Write Guard — blocks writes to critical files.
- L4+ External Content Scanner (16 patterns + density heuristic).
- Layer C: Privilege Separation.
- Canary Token System.
- Full 6-layer plugin integration. L0 session scanning. L4 signal detection (50+ patterns). Bootstrap file protection.
- L0 + L1: Session integrity + content tagging.
- Proof of concept — standalone L4 scanner.
MIT — see LICENSE.