🛡️ PolicyShield

AI agents can rm -rf /, leak your database, and run up a $10k API bill — all in one session.

PolicyShield is a runtime firewall that sits between the LLM and the tools it calls. Write rules in YAML — PolicyShield enforces them before any tool executes.

   LLM → exec("rm -rf /")          → BLOCKED ✅  tool never runs
   LLM → send("SSN: 123-45-6789")  → REDACTED ✅ send("SSN: [SSN]")
   LLM → deploy("prod")            → APPROVE ✅  human reviews first

⚡ Quick Start (30 seconds)

pip install policyshield

Create rules.yaml:

rules:
  - id: no-delete
    when: { tool: delete_file }
    then: block
    message: "File deletion is not allowed."

  - id: redact-pii
    when: { tool: send_message }
    then: redact
    message: "PII redacted before sending."

Use it:

from policyshield.shield.engine import ShieldEngine

engine = ShieldEngine(rules="rules.yaml")

result = engine.check("delete_file", {"path": "/data"})
# → Verdict.BLOCK — "File deletion is not allowed."

result = engine.check("send_message", {"text": "Email john@corp.com"})
# → Verdict.REDACT — modified_args: {"text": "Email [EMAIL]"}

That's it. No agent rewrites. Works with any framework.

🔌 OpenClaw Integration (Step-by-Step)

PolicyShield plugs into OpenClaw as a native plugin. Every tool call the AI agent makes goes through PolicyShield first — BLOCK, REDACT, APPROVE, or ALLOW. You also get /policyshield commands in Telegram/Discord/Slack.

1. Start the PolicyShield server

pip install policyshield
policyshield server --rules rules.yaml --port 8100

The server runs on http://localhost:8100 and exposes the REST API that the OpenClaw plugin calls.

2. Install the plugin into OpenClaw

From the PolicyShield repo:

cd plugins/openclaw
npm install && npm run build

Or install from npm:

openclaw plugins install @policyshield/openclaw-plugin

3. Configure openclaw.json

Add the plugin path and config to your OpenClaw config file:

{
  // your existing config...
  "plugins": {
    "enabled": true,
    "load": {
      // point to the built plugin directory
      "paths": ["/path/to/PolicyShield/plugins/openclaw"]
    },
    "entries": {
      "policyshield": {
        "enabled": true,
        "config": {
          "url": "http://localhost:8100",  // PolicyShield server
          "mode": "enforce",               // "enforce" or "disabled"
          "fail_open": true,               // allow calls if server is down
          "timeout_ms": 5000               // per-check timeout
        }
      }
    }
  }
}

4. Start the OpenClaw gateway

OPENAI_API_KEY="sk-..." openclaw gateway

Look for these lines in the output:

[gateway] ✓ Connected to PolicyShield server
[gateway] agent model: openai/gpt-4o
[telegram] starting provider (@yourbot)

How it works

  User → OpenClaw Agent → LLM wants to call tool("exec", {command: "rm -rf /"})
                              │
                              ▼
                    ┌─────────────────────────┐
                    │ PolicyShield Plugin (TS)│─ before_tool_call → POST /api/v1/check
                    │                         │← verdict: BLOCK ──  PolicyShield Server
                    └─────────────────────────┘
                              │
                              ▼
                    Tool call BLOCKED — agent tells user it can't do that.

/policyshield commands (Telegram / Discord / Slack)

These work directly in chat — no CLI needed:

/policyshield status                → server health + rules count
/policyshield rules                 → view active rules
/policyshield kill                  → 🔴 emergency stop — blocks ALL tool calls
/policyshield resume                → 🟢 resume normal operation
/policyshield reload                → hot-reload rules from disk
/policyshield compile <description> → preview YAML from natural language
/policyshield apply <description>   → compile + save + reload in one step

Live demo

You:    /policyshield kill
Bot:    🛡️ PolicyShield: 🔴 KILLED — all tool calls blocked

You:    Create a file test.txt
Bot:    I can't do that — all operations are blocked by PolicyShield.

You:    /policyshield resume
Bot:    🛡️ PolicyShield: 🟢 Resumed — normal operation

Plugin config reference

Full plugin README · Integration docs

🤖 Telegram Bot

Manage PolicyShield directly from Telegram — compile rules from natural language, deploy with one tap, and control the kill switch from your phone.

Setup

pip install "policyshield[server]"
export TELEGRAM_BOT_TOKEN="your-bot-token"
export OPENAI_API_KEY="your-api-key"

policyshield bot --rules rules.yaml --server-url http://localhost:8100

Natural Language → Live Rules

Send a plain-text policy description and the bot compiles it to validated YAML, shows a preview, and deploys on confirmation:

You:  Block all exec calls containing 'rm' and redact PII in send_message

Bot:  📜 Generated YAML:
      - id: block-rm-commands
        when:
          tool: exec
          args_match:
            command: { contains: rm }
        then: block
        ...
      [✅ Deploy] [❌ Cancel]

Tap Deploy — the bot atomically writes rules, merges by ID (no duplicates), backs up the old file, and hot-reloads the engine.

Management Commands

/status          # Server health, rules count, mode
/rules           # View active rules summary
/kill [reason]   # Emergency kill switch — blocks ALL tool calls
/resume          # Resume normal operation
/reload          # Hot-reload rules from disk
/compile <desc>  # Preview YAML from natural language
/apply <desc>    # Compile + save + reload in one step

/apply is the most powerful command — it generates rules via LLM, replaces conflicting rules for the same tool, and reloads the engine in one step.

OpenClaw + Telegram

With the OpenClaw plugin installed, use /policyshield commands directly in your OpenClaw Telegram chat:

/policyshield status
/policyshield apply "Block file deletions and limit web_fetch to 30 per session"

🔥 Core Features

🧱 YAML Rules — No Code Changes

Regex, glob, exact match, session conditions, chains — all in declarative YAML. The LLM never touches your rules.

- id: block-shell-injection
  when:
    tool: exec
    args_match:
      command: { regex: "rm\\s+-rf|curl.*\\|\\s*bash" }
  then: block
  severity: critical

🔍 Built-in PII Detection + Redaction

EMAIL, PHONE, CREDIT_CARD, SSN, IBAN, IP, PASSPORT, DOB — detected and redacted automatically. Add custom patterns in 2 lines.

🚨 Kill Switch

One command blocks every tool call instantly. Resume when you're ready.

policyshield kill --reason "Incident response"
policyshield resume

🔗 Chain Rules — Catch Multi-Step Attacks

Detect temporal patterns like data exfiltration: read_database → send_email within 2 minutes.

- id: anti-exfiltration
  when:
    tool: send_email
    chain:
      - tool: read_database
        within_seconds: 120
  then: block
  severity: critical

🕐 Conditional Rules

Block based on time, day, user role, or any custom context:

- id: no-deploy-weekends
  when:
    tool: deploy
    context:
      day_of_week: "!Mon-Fri"
  then: block
  message: "No deploys on weekends"

🧠 LLM Guard + NL Policy Compiler

LLM Guard — optional async threat detection middleware. Catches what regex can't.

NL Compiler — write policies in English, get validated YAML:

policyshield compile "Block file deletions and redact PII" -o rules.yaml

🖥️ Web Dashboard

Built-in web UI — no extra dependencies. Monitor verdicts, search traces, manage rules, and hit the kill switch from your browser.

policyshield server --rules rules.yaml --port 8100
# Open http://localhost:8100/dashboard

Overview — verdict breakdown, block rate, cost savings, top tools, PII heatmap, live WebSocket feed.
Rules — browse active rules with expandable YAML detail.
Traces — full-text search with filters (tool, verdict, session, date range).
Controls — 🔴 Kill Switch, 🟢 Resume, ♻️ Reload Rules, approve/deny pending requests.

Standalone analytics mode (no server required): policyshield trace dashboard --port 8000

🔌 Works With Everything

pip install "policyshield[server]"
policyshield server --rules ./rules.yaml --port 8100

from policyshield.sdk.client import PolicyShieldClient

with PolicyShieldClient("http://localhost:8100") as client:
    result = client.check("exec_command", {"cmd": "rm -rf /"})
    print(result.verdict)  # BLOCK

    client.kill("Incident response")
    client.resume()
    client.reload()

from policyshield.sdk.client import AsyncPolicyShieldClient

async with AsyncPolicyShieldClient("http://localhost:8100") as client:
    result = await client.check("send_email", {"to": "admin@corp.com"})

from policyshield.decorators import shield

@shield(engine, tool_name="delete_file")
def delete_file(path: str):
    os.remove(path)  # only runs if PolicyShield allows

# Setup & Init
policyshield quickstart                    # Interactive setup wizard
policyshield init --preset secure          # Initialize with preset rules
policyshield doctor                        # 10-check health scan (A-F grading)

# Rules
policyshield validate ./policies/          # Validate rules
policyshield lint ./policies/rules.yaml    # Static analysis (7 checks)
policyshield test ./policies/              # Run YAML test cases

# Dry-run check
policyshield check --tool exec --rules rules.yaml

# Server
policyshield server --rules ./rules.yaml --port 8100 --mode enforce

# Telegram Bot
policyshield bot --rules rules.yaml --server-url http://localhost:8100

# Traces
policyshield trace show ./traces/trace.jsonl
policyshield trace violations ./traces/trace.jsonl
policyshield trace stats --dir ./traces/ --format json
policyshield trace dashboard --port 8000

# Replay & Simulation
policyshield replay ./trace.jsonl --rules new-rules.yaml --changed-only
policyshield simulate --rule rule.yaml --tool exec --args '{"cmd":"ls"}'

# Rule Generation
policyshield generate "Block all file deletions"       # AI-powered
policyshield generate-rules --from-openclaw             # Auto from OpenClaw
policyshield compile "Block deletions, redact PII"      # NL → YAML

# Reports & Ops
policyshield report --traces ./traces/ --format html
policyshield kill --reason "Incident response"
policyshield resume

# OpenClaw
policyshield openclaw setup                # Install + configure plugin
policyshield openclaw teardown             # Remove plugin

📖 Documentation · 📝 Changelog · 🗺 Roadmap · MIT License