Security middleware for OpenClaw agents. Defends against prompt injection attacks across text, images, PDFs, and audio. Shares threat intel on-chain via Base Sepolia.

Built for a hackathon demo. Parts are production-grade (detection pipeline, migrations, CSP, Prometheus, admin-auth on audit + metrics); parts are explicitly scaffolds (adversarial learning loop, ZK proof generation). See Project Honesty for the exact state of each subsystem.

Inbound Content → Extraction → Detection Pipeline → Verdict
                      |              |
              OCR / PDF / Whisper    Rules → Classifier → LLM Judge
              HTML / Email parse          |
                                    On-chain threat cache (instant block)
                                          |
                                    Base Sepolia registry (shared intel)

Detection pipeline short-circuits: if regex rules are confident (severity ≥ 0.9), we block without calling the classifier or LLM judge. The ML classifier (protectai/deberta-v3-base-prompt-injection-v2, see detector/classifier.py) handles cases rules miss. The LLM judge (Claude Haiku, see skill/detectors/judge.py) resolves ambiguous cases only, and fails closed — a transient API error yields a sanitize verdict, not a silent pass.

cd clawguard

# 1. Install dependencies
make setup

# 2. Configure secrets (see docs/SECRETS.md for the full list)
cp .env.example .env
# Fill in ANTHROPIC_API_KEY at minimum. For admin endpoints, also set
# ADMIN_API_TOKEN (protects /api/audit and /metrics).

# 3. Generate attack fixtures
make fixtures

# 4. Run database migrations
make migrate

# 5. Run the demo
make demo

# Terminal 1: API server
make api

# Terminal 2: Dashboard
make dashboard

# Terminal 3: Run demo agent
make demo

# Open http://localhost:5175

Key ones (see docs/SECRETS.md for the authoritative list):

• GET /api/health — liveness: process is up, cheap snapshot of chain config and cached-threat count (does not start chain polling).
• GET /api/ready — readiness: PRAGMA quick_check + Alembic at head; returns 503 until the database is migrated and intact. Use this for load balancers and orchestrators; keep /api/health for simple process probes.

The demo runs without on-chain, without Slack, and without the admin token (flip REQUIRE_ADMIN_TOKEN=false for local dev). Every optional integration degrades gracefully.

curl -L https://foundry.paradigm.xyz | bash && foundryup
make contracts
# Copy the deployed address to .env as CLAWGUARD_REGISTRY_ADDRESS

Three attack fixtures in demo/attacks/:

1. bloomberg_email.eml — Fake Bloomberg earnings alert with injection in an HTML comment and a display:none div. Both tell the agent to sell all positions.
2. chart_injection.png — Stock chart with white-on-white text ("SELL ALL AAPL") nearly invisible to human readers but caught by inverted OCR and vision model.
3. earnings_report.pdf — Earnings report PDF with a hidden text layer (white text, 1pt font) and injection in PDF metadata fields.

30 regex rules in skill/detectors/rules.py across categories:

• Instruction override ("ignore previous", "new instructions")
• Role manipulation ("you are now", "act as", DAN/jailbreak)
• System prompt markers (<system>, [INST], prompt boundaries)
• Obfuscation (base64 blobs, hex/unicode escapes)
• Steganographic (zero-width chars, homoglyph mixed scripts)
• Markup injection (HTML comments, hidden divs, script tags)
• Financial-specific ("sell all positions", urgency+trade combos)
• Context manipulation (fake errors, fake user messages, separators)
• Delimiter abuse (backtick system tags, XML tag injection)
• Exfiltration (markdown image data exfil)

• Short-circuit pipeline. Rules are fast and free. Classifier needs a ~700MB model download but runs locally. LLM judge costs API calls — only invoked when uncertain.
• Fail-closed judge. If Claude errors mid-call we return sanitize with low confidence instead of letting the attack through.
• Multipass OCR. Standard OCR misses white-on-white text. Inverted and edge-detect passes catch adversarial text at the cost of some false positives in normal images (acceptable for security).
• Hash-first cache check. Before running any detection we SHA-256 the extracted text and check against the local SQLite cache of on-chain threats. Known attacks block in microseconds.
• Graceful degradation. Every heavy component (Whisper, Tesseract, transformers, web3, Alpaca) is optional. The skill works with just anthropic installed.
• Admin auth. /api/audit requires X-Admin-Token; /metrics requires Authorization: Bearer ... (or X-Metrics-Token). Both fall back to ADMIN_API_TOKEN when no dedicated token is set.
• SQLite with WAL. journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000ms. Good enough for demo throughput. Cursor pagination on detections/threats/audit (see X-Next-Cursor response header).

What this repo is and isn't, per subsystem:

clawguard/
  skill/                  # OpenClaw entrypoints + FastAPI app + detection pipeline
    api.py                # FastAPI server (admin auth, CSP, WS, /metrics)
    handler.py            # intercept() — the OpenClaw hook entrypoint
    detectors/            # rules.py, judge.py, pipeline.py
    extractors/           # thin wrappers that delegate to extractor/
    chain/                # ChainClient (threat registry — canonical)
    observability/        # metrics, tracing, alerts, JSON logging
    config/               # settings (non-secret knobs) + secrets (SecretsManager)
    migrations/           # Alembic (001 init, 002 audit_log, 003 indexes)
  extractor/              # Multimodal text extraction (text/html/pdf/image/audio)
  detector/               # ML classifier + on-chain tx anomaly detection
  blockchain/             # async_client, mempool_monitor, preemptive_strike, defense_agent
  learning/               # Red/Blue loop scaffold, rule_extractor, publisher
  network/                # poller + applier for cross-node defense sync
  zk/                     # RISC Zero host (currently mock) + guests
  store/                  # SQLite + Redis Streams helpers
  api/                    # Vercel serverless entrypoint (re-exports skill.api:app)
  contracts/              # Foundry: ThreatRegistry, DefenseProtocol, Consensus
  demo/ dashboard/        # Demo trading agent + React UI
  docs/                   # SECRETS.md, OBSERVABILITY.md, MIGRATIONS.md