Skip to content

Commit 0ca73e0

Browse files
rcholicrcholic
authored
Merge pull request #6 from PredicateSystems/demo
demo with updated readme
2 parents 8179d63 + 3d604bb commit 0ca73e0

9 files changed

Lines changed: 761 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ Result: ActionDeniedError — SSH key never read
2323

2424
---
2525

26+
## Runtime Authorization for AI Agents
27+
28+
<video src="https://github.com/user-attachments/assets/0fdf1ebb-6044-4288-9613-cd46f98cc284" autoplay loop muted playsinline></video>
29+
30+
*Prompt injection, data exfiltration, credential theft — blocked in under 15ms.*
31+
32+
---
33+
2634
## The Problem
2735

2836
AI agents are powerful. They can read files, run commands, make HTTP requests.
@@ -104,11 +112,27 @@ await provider.authorize({
104112
const content = await fs.readFile(path); // Only runs if authorized
105113
```
106114

107-
### 3. See it in action
115+
### 3. Run the demo
116+
117+
**Option A: Docker (Recommended)**
118+
119+
Run the full end-to-end demo safely in Docker. This is the safest way to see the attack scenarios — nothing touches your real filesystem.
108120

109121
```bash
110122
git clone https://github.com/PredicateSystems/predicate-claw
111-
cd predicate-claw
123+
cd predicate-claw/examples/demo
124+
./start-demo.sh
125+
```
126+
127+
The demo shows 4 scenarios with a real sidecar:
128+
- SSH key exfiltration → **BLOCKED**
129+
- Shell command injection → **BLOCKED**
130+
- Data exfiltration → **BLOCKED**
131+
- Legitimate file read → **ALLOWED**
132+
133+
**Option B: Unit test (mocked sidecar)**
134+
135+
```bash
112136
npm install
113137
npm run test:demo
114138
```

‎examples/demo/Dockerfile.demo‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Demo application container
2+
FROM node:22-slim
3+
4+
WORKDIR /app
5+
6+
# Install TypeScript and tsx for running demo
7+
RUN npm install -g tsx
8+
9+
# Copy package files and install dependencies
10+
COPY package*.json ./
11+
RUN npm install
12+
13+
# Copy demo files
14+
COPY examples/demo/demo.ts ./demo.ts
15+
COPY examples/demo/policy.demo.json ./policy.demo.json
16+
17+
# Wait for sidecar to be ready, then run demo
18+
CMD ["tsx", "demo.ts"]

‎examples/demo/Dockerfile.sidecar‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Pre-built sidecar container for fast startup
2+
FROM node:22-slim
3+
4+
# Install curl for downloading binary
5+
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
6+
7+
WORKDIR /app
8+
9+
# Detect architecture and download appropriate binary
10+
ARG TARGETARCH
11+
RUN ARCH=$(echo ${TARGETARCH:-$(uname -m)} | sed 's/amd64/x64/' | sed 's/x86_64/x64/' | sed 's/aarch64/arm64/') && \
12+
echo "Detected architecture: $ARCH" && \
13+
curl -fsSL -o /tmp/sidecar.tar.gz \
14+
"https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-${ARCH}.tar.gz" && \
15+
tar -xzf /tmp/sidecar.tar.gz -C /usr/local/bin && \
16+
chmod +x /usr/local/bin/predicate-authorityd && \
17+
rm /tmp/sidecar.tar.gz
18+
19+
# Copy policy file
20+
COPY examples/demo/policy.demo.json /app/policy.json
21+
22+
EXPOSE 8787
23+
24+
# Run sidecar
25+
CMD ["predicate-authorityd", "--host", "0.0.0.0", "--port", "8787", "--mode", "local_only", "--policy-file", "/app/policy.json", "--log-level", "info", "run"]

‎examples/demo/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Predicate Authority Demo: Hack vs Fix
2+
3+
**See how Predicate Authority blocks prompt injection attacks in real-time.**
4+
5+
This demo shows an AI agent attempting to:
6+
1. Read SSH private keys (blocked)
7+
2. Run `curl | bash` commands (blocked)
8+
3. Exfiltrate data to webhook.site (blocked)
9+
4. Read legitimate project files (allowed)
10+
11+
## Quick Start
12+
13+
```bash
14+
git clone https://github.com/PredicateSystems/openclaw-predicate-provider
15+
cd openclaw-predicate-provider/examples/demo
16+
./start-demo.sh
17+
```
18+
19+
That's it. Docker handles everything.
20+
21+
## What You'll See
22+
23+
```
24+
┌───────────────────────────────────────────────────────────────┐
25+
│ PREDICATE AUTHORITY DEMO: Hack vs Fix │
26+
├───────────────────────────────────────────────────────────────┤
27+
│ │
28+
│ [1/3] UNGUARDED: SSH Key Exfiltration │
29+
│ Action: fs.read │
30+
│ Resource: ~/.ssh/id_rsa │
31+
│ Source: untrusted_dm │
32+
│ │
33+
│ RESULT: SUCCESS (THIS IS BAD) │
34+
│ Output: "-----BEGIN OPENSSH PRIVATE KEY-----..." │
35+
│ │
36+
│ [1/3] GUARDED: SSH Key Exfiltration │
37+
│ Action: fs.read │
38+
│ Resource: ~/.ssh/id_rsa │
39+
│ Source: untrusted_dm │
40+
│ │
41+
│ DECISION: DENY (12ms) │
42+
│ Reason: deny_sensitive_read_from_untrusted_context │
43+
│ │
44+
│ Attack blocked. Sensitive data protected. │
45+
│ │
46+
└───────────────────────────────────────────────────────────────┘
47+
```
48+
49+
## How It Works
50+
51+
```
52+
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
53+
│ Agent │───▶│ Predicate │───▶│ Sidecar │
54+
│ │ │ Provider │ │ (policy) │
55+
│ fs.read │ │ │ │ │
56+
│ ~/.ssh/... │ │ action:fs.read │ DENY │
57+
└─────────────┘ │ source:untrusted └─────────────┘
58+
└──────────────┘
59+
│
60+
▼
61+
ActionDeniedError
62+
```
63+
64+
1. Agent receives tool call request
65+
2. Provider intercepts and builds authorization request
66+
3. Sidecar evaluates policy rules
67+
4. Decision returned in <25ms
68+
5. DENY = throw error, ALLOW = execute
69+
70+
## Key Properties
71+
72+
| Property | Value |
73+
|----------|-------|
74+
| **Deterministic** | Policy-based rules, not probabilistic filtering |
75+
| **Fast** | p50 < 25ms authorization latency |
76+
| **Auditable** | Every decision logged with mandate ID |
77+
| **Fail-closed** | Sidecar errors block execution |
78+
79+
## Customize the Policy
80+
81+
Edit `policy.demo.json` to add your own rules:
82+
83+
```json
84+
{
85+
"rules": [
86+
{
87+
"id": "deny_my_secrets",
88+
"effect": "deny",
89+
"action": "fs.*",
90+
"resource": ["**/secrets/*", "**/.env"],
91+
"reason": "deny_secrets_access"
92+
}
93+
]
94+
}
95+
```
96+
97+
Then re-run `./start-demo.sh`.
98+
99+
## Requirements
100+
101+
- Docker (with Docker Compose)
102+
103+
No other dependencies. Everything runs in containers.
104+
105+
## Install in Your Project
106+
107+
```bash
108+
npm install predicate-claw @predicatesystems/authorityd
109+
```
110+
111+
```typescript
112+
import { GuardedProvider, ToolAdapter } from "predicate-claw";
113+
114+
const provider = new GuardedProvider({
115+
principal: "agent:my-agent",
116+
});
117+
118+
const adapter = new ToolAdapter(provider);
119+
120+
// This will throw ActionDeniedError if policy denies
121+
await adapter.readFile({
122+
args: { path: "~/.ssh/id_rsa" },
123+
context: { source: "untrusted_dm" },
124+
execute: async (args) => fs.readFile(args.path),
125+
});
126+
```
127+
128+
## Links
129+
130+
- [GitHub: openclaw-predicate-provider](https://github.com/PredicateSystems/openclaw-predicate-provider)
131+
- [npm: predicate-claw](https://www.npmjs.com/package/predicate-claw)
132+
- [npm: @predicatesystems/authorityd](https://www.npmjs.com/package/@predicatesystems/authorityd)
133+
134+
## License
135+
136+
MIT / Apache 2.0

0 commit comments

Comments
 (0)