Skip to content

Commit a676b56

Browse files
rcholicrcholic
committed
optionality for pre- and post-
1 parent 15c8f2f commit a676b56

2 files changed

Lines changed: 215 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,86 @@ SecureAgent
8080
└── RuntimeAgent (orchestration, pre-action hook)
8181
```
8282

83+
## Sidecar Prerequisite (Optional)
84+
85+
The [Predicate Authority Sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) is **only required if you need pre-action authorization**—real-time policy evaluation that blocks unauthorized actions before they execute.
86+
87+
| Feature | Sidecar Required? |
88+
|---------|-------------------|
89+
| Pre-action authorization (`strict`/`permissive` modes) | **Yes** |
90+
| Debug tracing (`debug` mode) | No |
91+
| Audit logging (`audit` mode) | No |
92+
| Policy development & testing | No |
93+
94+
If you only need debug tracing or audit logging, you can skip the sidecar entirely.
95+
96+
### Starting the Sidecar
97+
98+
**Docker (Recommended):**
99+
100+
```bash
101+
docker run -d -p 8787:8787 ghcr.io/predicatesystems/predicate-authorityd:latest
102+
```
103+
104+
**Or download binary:**
105+
106+
```bash
107+
# macOS (Apple Silicon)
108+
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz
109+
./predicate-authorityd --port 8787
110+
111+
# Linux x64
112+
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-x64.tar.gz | tar -xz
113+
./predicate-authorityd --port 8787
114+
```
115+
116+
**Verify:**
117+
118+
```bash
119+
curl http://localhost:8787/health
120+
# {"status":"ok"}
121+
```
122+
123+
The sidecar handles policy evaluation in <25ms with zero egress—no data leaves your infrastructure.
124+
125+
## Flexible Verification
126+
127+
Use pre-execution authorization and post-execution verification **independently or together**:
128+
129+
| Pattern | Use Case | Sidecar? |
130+
|---------|----------|----------|
131+
| Pre-execution only | Block unauthorized actions | Yes |
132+
| Post-execution only | Verify outcomes after completion | No |
133+
| Both (full loop) | Block + verify for max safety | Yes |
134+
135+
**Pre-execution only** (policy without `require_verification`):
136+
137+
```yaml
138+
rules:
139+
- action: "browser.*"
140+
resource: "https://amazon.com/*"
141+
effect: allow
142+
```
143+
144+
**Post-execution only** (debug mode, no sidecar):
145+
146+
```python
147+
secure_agent = SecureAgent(agent=agent, mode="debug")
148+
secure_agent.run()
149+
secure_agent.trace_verification("cart_not_empty", passed=True)
150+
```
151+
152+
**Both** (policy with `require_verification`):
153+
154+
```yaml
155+
rules:
156+
- action: "browser.click"
157+
resource: "*checkout*"
158+
effect: allow
159+
require_verification:
160+
- element_exists: "#order-confirmation"
161+
```
162+
83163
## Debug Mode
84164
85165
Debug mode provides human-readable trace output for troubleshooting:

‎docs/user-manual.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,141 @@ A comprehensive guide to securing your AI agents with predicate-secure.
3131
- **Cryptographic audit** - All decisions are logged with tamper-proof receipts
3232
- **Zero refactoring** - Works with your existing agent code
3333

34+
### Sidecar Prerequisite (Optional)
35+
36+
The [Predicate Authority Sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) is **only required if you need pre-action authorization**—real-time policy evaluation that blocks unauthorized actions before they execute.
37+
38+
| Feature | Sidecar Required? |
39+
|---------|-------------------|
40+
| Pre-action authorization (`strict`/`permissive` modes) | **Yes** |
41+
| Debug tracing (`debug` mode) | No |
42+
| Audit logging (`audit` mode) | No |
43+
| Policy development & testing | No |
44+
45+
**If you only need debug tracing, audit logging, or policy development, you can skip the sidecar entirely.**
46+
47+
#### Starting the Sidecar
48+
49+
| Resource | Link |
50+
|----------|------|
51+
| Sidecar Repository | [predicate-authority-sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) |
52+
| Download Binaries | [Latest Releases](https://github.com/PredicateSystems/predicate-authority-sidecar/releases) |
53+
54+
**Option A: Docker (Recommended)**
55+
56+
```bash
57+
docker run -d -p 8787:8787 ghcr.io/predicatesystems/predicate-authorityd:latest
58+
```
59+
60+
**Option B: Download Binary**
61+
62+
```bash
63+
# macOS (Apple Silicon)
64+
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz
65+
chmod +x predicate-authorityd
66+
./predicate-authorityd --port 8787
67+
68+
# Linux x64
69+
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-x64.tar.gz | tar -xz
70+
chmod +x predicate-authorityd
71+
./predicate-authorityd --port 8787
72+
```
73+
74+
See [all platform binaries](https://github.com/PredicateSystems/predicate-authority-sidecar/releases) for Linux ARM64, macOS Intel, and Windows.
75+
76+
**Verify it's running:**
77+
78+
```bash
79+
curl http://localhost:8787/health
80+
# {"status":"ok"}
81+
```
82+
83+
The sidecar handles policy evaluation in <25ms with zero egress—no data leaves your infrastructure.
84+
85+
### Flexible Verification Options
86+
87+
You can use pre-execution authorization and post-execution verification **independently or together**:
88+
89+
| Usage Pattern | Description | Sidecar Required? |
90+
|---------------|-------------|-------------------|
91+
| Pre-execution only | Block unauthorized actions before they run | Yes |
92+
| Post-execution only | Verify outcomes after actions complete | No |
93+
| Both (full loop) | Block + verify for maximum safety | Yes |
94+
95+
#### Pre-Execution Authorization Only
96+
97+
Use `strict` or `permissive` mode with a policy that has no `require_verification` predicates:
98+
99+
```python
100+
secure_agent = SecureAgent(
101+
agent=agent,
102+
policy="policy.yaml",
103+
mode="strict", # Requires sidecar
104+
)
105+
```
106+
107+
```yaml
108+
# policy.yaml - authorization only, no verification
109+
rules:
110+
- action: "browser.*"
111+
resource: "https://amazon.com/*"
112+
effect: allow
113+
114+
- action: "*"
115+
resource: "*"
116+
effect: deny
117+
```
118+
119+
#### Post-Execution Verification Only
120+
121+
Use `debug` or `audit` mode and manually verify outcomes—no sidecar needed:
122+
123+
```python
124+
secure_agent = SecureAgent(
125+
agent=agent,
126+
mode="debug", # No sidecar required
127+
)
128+
129+
# Run agent
130+
result = secure_agent.run()
131+
132+
# Verify outcomes after execution
133+
secure_agent.trace_verification(
134+
predicate="cart_not_empty",
135+
passed=check_cart_has_items(),
136+
message="Verified cart contains expected items",
137+
)
138+
139+
secure_agent.trace_verification(
140+
predicate="order_confirmed",
141+
passed=check_order_confirmation(),
142+
message="Order confirmation page displayed",
143+
)
144+
```
145+
146+
#### Both: Full Closed-Loop Verification
147+
148+
Use `strict` mode with `require_verification` predicates for maximum safety:
149+
150+
```python
151+
secure_agent = SecureAgent(
152+
agent=agent,
153+
policy="policy.yaml",
154+
mode="strict", # Requires sidecar
155+
)
156+
```
157+
158+
```yaml
159+
# policy.yaml - authorization + verification
160+
rules:
161+
- action: "browser.click"
162+
resource: "*checkout*"
163+
effect: allow
164+
require_verification: # Post-execution check
165+
- url_contains: "/order-confirmation"
166+
- element_exists: "#order-number"
167+
```
168+
34169
### How it works
35170

36171
```

0 commit comments

Comments
 (0)