From 588d34ba4ff5a6209b091a2e5c7aae2ce6190b11 Mon Sep 17 00:00:00 2001 From: SentienceDEV Date: Thu, 26 Feb 2026 21:25:40 -0800 Subject: [PATCH] demo readme --- demo/README.md | 177 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 132 insertions(+), 45 deletions(-) diff --git a/demo/README.md b/demo/README.md index ffcc13ded32f..639b09906a5c 100644 --- a/demo/README.md +++ b/demo/README.md @@ -9,54 +9,139 @@ This demo shows how SecureClaw protects against prompt injection attacks that at 3. **Without SecureClaw**: The agent follows the injected instruction and leaks AWS keys 4. **With SecureClaw**: The sensitive file access is blocked before execution -## Running the Demo +--- -### Interactive Script +## Demo Option 1: Simulation Script (No Sidecar Required) + +The quickest way to see the demo - runs a simulated walkthrough with no dependencies. ```bash +cd /Users/guoliangwang/Downloads/openclaw ./demo/hack-vs-fix.sh ``` -This walks through the attack scenario step-by-step with colored output. +This script: +- Creates a fake `~/.aws/credentials` file in a temp directory +- Creates a malicious document with a hidden prompt injection +- Walks through what happens WITHOUT SecureClaw (attack succeeds) +- Walks through what happens WITH SecureClaw (attack blocked) +- Shows the policy rule that blocked the attack + +**No sidecar or SecureClaw installation required** - it's a visualization of the flow. + +--- + +## Demo Option 2: Live Demo with Sidecar -### Live Demo with SecureClaw +For a real end-to-end demo with the actual rust-predicate-authorityd sidecar. -1. Start the Predicate Authority sidecar (rust-predicate-authorityd): +### Prerequisites + +1. Build the rust-predicate-authorityd sidecar: ```bash - # From the rust-predicate-authorityd directory - cargo run -- --policy ../openclaw/policies/default.json --port 8787 + cd /Users/guoliangwang/Code/Sentience/rust-predicate-authorityd + cargo build --release ``` -2. Run SecureClaw: +2. Install SecureClaw dependencies: ```bash - secureclaw + cd /Users/guoliangwang/Downloads/openclaw + pnpm install ``` -3. Try the prompt injection: - ``` - > Summarize the document at ./demo/malicious-doc.txt - ``` +### Running the Live Demo -4. Observe the blocked access in the SecureClaw logs: - ``` - [SecureClaw] BLOCKED: fs.read on ~/.aws/credentials - sensitive_resource_blocked - ``` +**Terminal 1 - Start the Sidecar:** +```bash +cd /Users/guoliangwang/Code/Sentience/rust-predicate-authorityd +cargo run --release -- \ + --policy /Users/guoliangwang/Downloads/openclaw/policies/default.json \ + --port 8787 +``` + +You should see: +``` +[INFO] Predicate Authority Sidecar starting on :8787 +[INFO] Loaded policy with X rules +``` + +**Terminal 2 - Run SecureClaw:** +```bash +cd /Users/guoliangwang/Downloads/openclaw +SECURECLAW_VERBOSE=true pnpm openclaw +``` + +**Terminal 2 - Try the Attack:** +``` +> Summarize the document at ./demo/malicious-doc.txt +``` + +**Expected Output:** +``` +[SecureClaw] Pre-auth: fs.read on ~/.aws/credentials +[SecureClaw] BLOCKED: fs.read - sensitive_resource_blocked +``` + +--- + +## Demo Option 3: Live Demo WITHOUT Sidecar (Fail-Open Mode) + +To test SecureClaw behavior when the sidecar is unavailable: + +```bash +cd /Users/guoliangwang/Downloads/openclaw + +# Fail-open mode (allows actions when sidecar is down) +SECURECLAW_FAIL_OPEN=true SECURECLAW_VERBOSE=true pnpm openclaw + +# Fail-closed mode (blocks all actions when sidecar is down) - DEFAULT +SECURECLAW_VERBOSE=true pnpm openclaw +``` + +In **fail-closed mode** (default), you'll see: +``` +[SecureClaw] Sidecar error (fail-closed): Connection refused +[SecureClaw] Authorization service unavailable (fail-closed mode) +``` + +In **fail-open mode**, actions will be allowed with a warning: +``` +[SecureClaw] Sidecar error (fail-open): Connection refused +``` + +--- ## Key Files -- `hack-vs-fix.sh` - Interactive demo script -- `malicious-doc.txt` - Document with hidden prompt injection -- `../policies/default.json` - Policy that blocks sensitive resource access +| File | Description | +|------|-------------| +| `demo/hack-vs-fix.sh` | Interactive simulation script | +| `demo/malicious-doc.txt` | Document with hidden prompt injection | +| `policies/default.json` | Default policy (blocks sensitive resources) | +| `policies/examples/coding-agent.json` | Policy for coding assistants | +| `policies/examples/browser-agent.json` | Policy for browser automation | + +--- ## How It Works +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐ +│ OpenClaw │────▶│ SecureClaw │────▶│ rust-predicate-authorityd │ +│ (Agent) │ │ (Plugin) │ │ (Sidecar @ :8787) │ +│ │◀────│ predicate-claw │◀────│ Policy Engine │ +└─────────────────┘ └──────────────────┘ └─────────────────────────┘ +``` + 1. **Pre-Authorization**: Every tool call is intercepted by SecureClaw's `before_tool_call` hook -2. **SDK Integration**: Uses `predicate-claw` (GuardedProvider) to communicate with the sidecar -3. **Policy Evaluation**: The Predicate Authority sidecar checks the action against policy rules -4. **Block Decision**: The `deny-aws-credentials` rule matches `*/.aws/*` and returns `allow: false` -5. **Enforcement**: SecureClaw returns `block: true` to OpenClaw, preventing the file read +2. **SDK Integration**: Uses `predicate-claw` SDK (`GuardedProvider`) to communicate with sidecar +3. **Policy Evaluation**: The sidecar checks the action against JSON policy rules +4. **Block Decision**: Matching deny rules return `allow: false` +5. **Enforcement**: SecureClaw returns `block: true` to OpenClaw, preventing execution -## Policy Rule (JSON format for rust-predicate-authorityd) +--- + +## Policy Rule Example ```json { @@ -74,31 +159,33 @@ This walks through the attack scenario step-by-step with colored output. } ``` -## Architecture +--- -``` -┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐ -│ OpenClaw │────▶│ SecureClaw │────▶│ rust-predicate-authorityd │ -│ (Agent) │ │ (Plugin) │ │ (Sidecar @ :8787) │ -│ │◀────│ predicate-claw │◀────│ Policy Engine │ -└─────────────────┘ └──────────────────┘ └─────────────────────────┘ -``` +## Environment Variables -## Recording a Demo Video +| Variable | Default | Description | +|----------|---------|-------------| +| `SECURECLAW_PRINCIPAL` | `agent:secureclaw` | Agent identity | +| `SECURECLAW_POLICY` | `./policies/default.json` | Policy file path | +| `PREDICATE_SIDECAR_URL` | `http://127.0.0.1:8787` | Sidecar endpoint | +| `SECURECLAW_FAIL_OPEN` | `false` | Allow actions when sidecar is down | +| `SECURECLAW_VERBOSE` | `false` | Enable verbose logging | -For HN/social media, record: +--- -1. Terminal split-screen: - - Left: SecureClaw running - - Right: Sidecar logs +## Recording a Demo Video -2. Show: - - Normal operation (reading safe files) - - Prompt injection attempt - - Block message in real-time - - Agent continuing without leaked data +For HN/social media, record using `asciinema`: -Use `asciinema` for terminal recording: ```bash asciinema rec demo.cast -``` \ No newline at end of file +``` + +Recommended split-screen setup: +- **Left terminal**: SecureClaw running with `SECURECLAW_VERBOSE=true` +- **Right terminal**: Sidecar logs + +Show: +1. Normal operation (reading safe files) - ALLOWED +2. Prompt injection attempt (reading ~/.aws/credentials) - BLOCKED +3. Agent continues without leaked data \ No newline at end of file