Metadata-Version: 2.4
Name: predicate-secure
Version: 0.1.0
Summary: Drop-in security wrapper for AI agents - adds authorization, verification, and audit to any agent framework
Author: Predicate Systems Contributors
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/anthropics/predicate-secure
Project-URL: Documentation, https://docs.predicate.systems/secure
Project-URL: Repository, https://github.com/anthropics/predicate-secure
Project-URL: Issues, https://github.com/anthropics/predicate-secure/issues
Keywords: ai,agents,security,authorization,verification,browser-use,langchain,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Requires-Dist: predicate-authority>=0.1.0
Requires-Dist: predicate>=0.1.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: browser-use
Requires-Dist: browser-use>=0.1.0; extra == "browser-use"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: playwright
Requires-Dist: playwright>=1.40; extra == "playwright"
Provides-Extra: all
Requires-Dist: predicate-secure[browser-use,langchain,playwright]; extra == "all"
Dynamic: license-file

# predicate-secure

[![License](https://img.shields.io/badge/License-MIT%2FApache--2.0-blue.svg)](LICENSE)
[![PyPI - predicate-secure](https://img.shields.io/pypi/v/predicate-secure.svg)](https://pypi.org/project/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

```bash
pip install predicate-secure
```

With framework-specific extras:

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

## Quick Start

```python
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 | Planned |

## Architecture

`predicate-secure` is a thin orchestration layer that combines:

- **[predicate-runtime](https://github.com/PredicateSystems/sdk-python)** - Snapshot engine, DOM pruning, verification predicates
- **[predicate-authority](https://github.com/PredicateSystems/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](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.

| 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):**

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

**Or download binary:**

```bash
# 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:**

```bash
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`):

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

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

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

**Both** (policy with `require_verification`):

```yaml
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:

```python
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):

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

## Policy Reference

### Basic Structure

```yaml
# 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

```yaml
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

```yaml
# 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

```bash
# 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](./LICENSE).
