Skip to content

README.md

Latest commit

 

History

History
221 lines (162 loc) · 7.64 KB

README.md

File metadata and controls

221 lines (162 loc) · 7.64 KB

Predicate Secure Browser Automation Demo

This demo showcases the complete agent loop with:

  1. Pre-execution Authorization - Policy-based decisions before any browser action
  2. Browser Automation - Using PredicateBrowser (@predicatesystems/runtime) with Chrome extension
  3. Post-execution Verification - Local LLM (Ollama) or OpenAI for verification planning

Prerequisites

1. Install Dependencies

# From the ts-predicate-secure directory
npm install

# The demo uses @predicatesystems/runtime which includes Playwright
# Playwright browsers are installed automatically

2. Set Up LLM (Choose One)

Option A: Ollama (Local - Recommended)

# Install Ollama (macOS)
brew install ollama

# Start Ollama server
ollama serve

# Pull the Qwen model (in another terminal)
ollama pull qwen2.5:7b

Option B: OpenAI (Cloud)

Set your OpenAI API key in .env:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
LLM_MODEL_NAME=gpt-4o-mini

3. Configure Environment

# Copy example environment file
cp demo/.env.example demo/.env

# Edit as needed

Running the Demo

# From the ts-predicate-secure directory
npx ts-node demo/secure-browser-demo.ts

Or with tsx (faster):

npx tsx demo/secure-browser-demo.ts

What the Demo Does

  1. Initializes Components

    • Local LLM verifier (Ollama or OpenAI)
    • SecureAgent with policy file

  2. Starts Browser

    • Launches Chromium via Playwright
    • Set BROWSER_HEADLESS=true for headless mode

  3. Executes Authorized Actions

    • Navigate to example.com (with authorization check)
    • Take snapshot (verify page loaded)
    • Find and click "More information" link

  4. Verifies Each Action

    • LLM generates verification predicates
    • Predicates are executed against page state
    • Demo fails if verification fails

Demo Output

┌────────────────────────────────────────────────────────────┐
│ Predicate Secure Browser Automation Demo                   │
├────────────────────────────────────────────────────────────┤
│ Task: Navigate to example.com and verify page loads        │
│ Start URL: https://www.example.com                         │
│ Principal: agent:demo-browser                              │
└────────────────────────────────────────────────────────────┘

Initializing Local LLM Verifier...
✓ Verifier initialized

Initializing Secure Agent...
✓ SecureAgent initialized
  Policy: demo/policies/browser_automation.yaml
  Mode: strict (fail-closed)
  Principal: agent:demo-browser

Step 1: Initializing Browser...
✓ Browser started

Step 2: Executing Browser Task...

→ Action: navigate (https://www.example.com)
  Pre-execution: Checking authorization...
✓ Action authorized
  Executing action...
✓ Action executed
  Post-execution: Generating verification plan...
[info] Generated 2 verifications
    Reasoning: Verify navigation to example.com succeeded
  Executing verifications...
    [1] url_contains(example.com)
        ✓ Passed
    [2] snapshot_changed()
        ✓ Passed
✓ All verifications passed

→ Action: snapshot (current_page)
...

✓ Task completed successfully

┌────────────────────────────────────────────────────────────┐
│ Demo completed successfully!                                │
├────────────────────────────────────────────────────────────┤
│ Run ID: abc123-def456-...                                  │
└────────────────────────────────────────────────────────────┘

Policy File

The demo uses policies/browser_automation.yaml which defines:

  • Allowed domains: example.com, google.com, wikipedia.org
  • Allowed actions: navigate, click, snapshot, type
  • Blocked actions: Password fields, credit card inputs
  • Blocked domains: HTTP (non-HTTPS), malicious sites

Verification Predicates

The LLM generates verification plans using these predicates:

Predicate Description
url_contains(substring) Check if URL contains substring
url_changed Check if URL changed after action
snapshot_changed Check if page content changed
element_exists(selector) Check if element exists in DOM
element_visible(selector) Check if element is visible
text_contains(substring) Check if page text contains substring

Troubleshooting

Ollama not available

Error: Ollama not available at http://localhost:11434

Start Ollama: ollama serve

Model not found

Error: model 'qwen2.5:7b' not found

Pull the model: ollama pull qwen2.5:7b

Playwright browsers not installed

Error: Executable doesn't exist

Install browsers: npx playwright install chromium

Architecture

┌─────────────────────────────────────────────────────────┐
│                    SecureBrowserDemo                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌────────────┐ │
│  │ SecureAgent  │    │ Sentience    │    │  Verifier  │ │
│  │  (Policy)    │    │  Browser     │    │  (LLM)     │ │
│  └──────────────┘    └──────────────┘    └────────────┘ │
│         │                   │                   │        │
│         ▼                   ▼                   ▼        │
│  ┌──────────────────────────────────────────────────┐   │
│  │              Authorization Loop                   │   │
│  │  1. Check policy → 2. Execute → 3. Verify       │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└─────────────────────────────────────────────────────────┘

PredicateBrowser

The demo uses PredicateBrowser from @predicatesystems/runtime which:

  • Automatically loads the Sentience Chrome extension
  • Provides snapshot() for semantic element detection
  • Supports both free tier (local extension) and API tier (cloud processing)
  • Includes stealth patches to avoid bot detection

Related