predicate-secure 0.2.0

Drop-in security wrapper for AI agents - adds authorization, verification, and audit to any agent framework

predicate-secure

Drop-in security wrapper for AI agents. Adds authorization, verification, and audit to any agent framework in 3 lines of code.

Features

• Pre-action authorization - Policy engine gates every action before execution
• Post-execution verification - Deterministic predicate checks (no LLM-as-a-judge)
• Cryptographic audit - WORM-ready receipts linking intent to outcome
• Zero refactoring - Wrap your existing agent, keep your framework

Installation

pip install predicate-secure

With framework-specific extras:

pip install predicate-secure[browser-use]
pip install predicate-secure[langchain]
pip install predicate-secure[playwright]
pip install predicate-secure[all]

Quick Start

from predicate_secure import SecureAgent
from browser_use import Agent

# 1. Your existing agent (unchanged)
agent = Agent(task="Buy headphones on Amazon", llm=my_model)

# 2. Wrap with SecureAgent
secure_agent = SecureAgent(
    agent=agent,
    policy="policies/shopping.yaml",
    mode="strict",
)

# 3. Run with full authorization + verification
secure_agent.run()

Modes

Mode	Behavior
strict	Fail-closed: deny action if policy check fails
permissive	Log but don't block unauthorized actions
debug	Human-readable trace output for debugging
audit	Record decisions without enforcement

Supported Frameworks

Framework	Status
browser-use	Supported
LangChain	Supported
Playwright	Supported
PydanticAI	Supported
OpenClaw	Supported

Architecture

predicate-secure is a thin orchestration layer that combines:

• predicate-runtime - Snapshot engine, DOM pruning, verification predicates
• predicate-authority - Policy engine, mandate signing, audit logging

SecureAgent
    ├── AgentRuntime (snapshot, assertions)
    ├── AuthorityClient (policy, mandates)
    └── RuntimeAgent (orchestration, pre-action hook)

Sidecar Prerequisite (Optional)

The Predicate Authority Sidecar is only required if you need pre-action authorization—real-time policy evaluation that blocks unauthorized actions before they execute.

Feature	Sidecar Required?
Pre-action authorization (strict/permissive modes)	Yes
Debug tracing (debug mode)	No
Audit logging (audit mode)	No
Policy development & testing	No

If you only need debug tracing or audit logging, you can skip the sidecar entirely.

Starting the Sidecar

Docker (Recommended):

docker run -d -p 8787:8787 ghcr.io/predicatesystems/predicate-authorityd:latest

Or download binary:

# macOS (Apple Silicon)
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz
./predicate-authorityd --port 8787

# Linux x64
curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-x64.tar.gz | tar -xz
./predicate-authorityd --port 8787

Verify:

curl http://localhost:8787/health
# {"status":"ok"}

The sidecar handles policy evaluation in <25ms with zero egress—no data leaves your infrastructure.

Flexible Verification

Use pre-execution authorization and post-execution verification independently or together:

Pattern	Use Case	Sidecar?
Pre-execution only	Block unauthorized actions	Yes
Post-execution only	Verify outcomes after completion	No
Both (full loop)	Block + verify for max safety	Yes

Pre-execution only (policy without require_verification):

rules:
  - action: "browser.*"
    resource: "https://amazon.com/*"
    effect: allow

Post-execution only (debug mode, no sidecar):

secure_agent = SecureAgent(agent=agent, mode="debug")
secure_agent.run()
secure_agent.trace_verification("cart_not_empty", passed=True)

Both (policy with require_verification):

rules:
  - action: "browser.click"
    resource: "*checkout*"
    effect: allow
    require_verification:
      - element_exists: "#order-confirmation"

Debug Mode

Debug mode provides human-readable trace output for troubleshooting:

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="debug",
    trace_format="console",  # or "json"
    trace_file="trace.jsonl",  # optional file output
)

Console output shows:

• Session start/end with framework and policy info
• Each step with action and resource
• Policy decisions (ALLOWED/DENIED) with reason codes
• Snapshot diffs (before/after state changes)
• Verification results (PASS/FAIL)

For JSON trace output (machine-parseable):

secure_agent = SecureAgent(
    agent=agent,
    mode="debug",
    trace_format="json",
    trace_file="trace.jsonl",
)

Policy Reference

Basic Structure

# policies/example.yaml
rules:
  - action: "<action_pattern>"
    resource: "<resource_pattern>"
    effect: allow | deny
    require_verification:  # optional
      - <predicate>

Action Patterns

Pattern	Description	Example
browser.*	All browser actions	click, type, navigate
browser.click	Specific action	Only click events
api.call	API tool calls	HTTP requests
*	Wildcard (all actions)	Catch-all rules

Resource Patterns

Pattern	Description	Example
https://example.com/*	URL prefix match	All pages on domain
*checkout*	Contains match	Any checkout-related URL
button#submit	CSS selector	Specific element
*	Wildcard (all resources)	Catch-all

Verification Predicates

require_verification:
  # URL checks
  - url_contains: "/checkout"
  - url_matches: "^https://.*\\.amazon\\.com/.*"

  # DOM state checks
  - element_exists: "#cart-items"
  - element_text_contains:
      selector: ".total"
      text: "$"

  # Custom predicates
  - predicate: "cart_not_empty"

Policy Example

# policies/shopping.yaml
rules:
  # Allow browsing Amazon
  - action: "browser.*"
    resource: "https://amazon.com/*"
    effect: allow

  # Allow checkout with verification
  - action: "browser.click"
    resource: "*checkout*"
    effect: allow
    require_verification:
      - url_contains: "/checkout"
      - element_exists: "#cart-items"

  # Block external links
  - action: "browser.navigate"
    resource: "https://external.com/*"
    effect: deny

  # Default deny
  - action: "*"
    resource: "*"
    effect: deny

Development

# Install dev dependencies
make dev-install

# Install pre-commit hooks
make hooks

# Run tests
make test

# Run linters
make lint

License

Dual-licensed under MIT or Apache-2.0. See LICENSE.