superbrowser-sdk 2.14.0

Super Browser is an agent-first, security-gated, anti-detection browser SDK built on top of existing automation engines. It wraps Patchright, Playwright, Selenium, or raw CDP behind one async facade with stealth defaults, multi-backend support, structured errors, budget governance, an MCP server with permissioned write tools, and an adversarial detection test suite that measures stealth honestly.

Stealth evidence: The adversarial suite shows Super-Browser at 16/25 clean vs raw Playwright's 14/25 on controlled server + scanner targets, with navigator.webdriver and Sannysoft resolved and 0 regressions. See docs/stealth-evidence.md for the full comparison table and known limitations.

Installation

Package naming: The distribution name is superbrowser-sdk. The Python import name is super_browser.

pip install superbrowser-sdk

import super_browser

# Default — Patchright (full stealth)
pip install superbrowser-sdk[patchright]
python -m patchright install chromium

# Alternative backends
pip install superbrowser-sdk[playwright]      # Standard Playwright
pip install superbrowser-sdk[selenium]        # Enterprise CI

# Or everything
pip install superbrowser-sdk[all]

For the MCP server (stdio, for Claude Desktop / Cursor integration):

pip install superbrowser-sdk[mcp,patchright]

See docs/mcp.md for the 13-tool surface and client configuration.

For specific LLM providers:

pip install superbrowser-sdk[patchright,anthropic]   # Anthropic Claude
pip install superbrowser-sdk[patchright,openai]       # OpenAI GPT

Quickstart

import asyncio
from super_browser import SuperBrowser, Config, create_llm

async def main():
    # 1. Build an LLM client (provider auto-detected from env)
    llm = create_llm()                          # uses SB_LLM_API_KEY

    # 2. Configure the browser
    cfg = Config.from_dict({
        "agent": {"llm_provider": "anthropic", "llm_api_key": "your-key"},
        "budget": {"daily_cap_usd": 5.0},
    })

    # 3. Create the facade and run
    async with SuperBrowser(config=cfg, llm_client=llm) as sb:
        page = await sb.navigate("https://example.com")
        heading = await sb.extract("the page heading", selector="h1")
        print(f"Heading: {heading.data.extracted}")

        # Self-healing click — retries if selector breaks
        await sb.click("a", description="First link")

        # Fill form fields
        await sb.fill("#email", "user@example.com")

asyncio.run(main())

Tip: For quick testing without a real LLM, use MockLLMClient:

from super_browser.testing import MockLLMClient
sb = SuperBrowser(llm_client=MockLLMClient())

Headless Mode

By default, Super Browser launches a visible browser window. This is intentional — headless mode is a detectable signal for anti-bot systems.

For testing, CI, and scripting where you don't need stealth, switch to headless:

from super_browser import Config
from super_browser.browser.config import SessionConfig

cfg = Config(browser=SessionConfig(headless=True))

Or via environment variable:

SB_HEADLESS=true python your_script.py

Streaming

For real-time visibility into agent execution, use act_stream() instead of act(). It yields StreamEvent objects for each lifecycle event:

from super_browser import StreamEvent

async for event in sb.act_stream("Fill the registration form"):
    if event.type == "step_complete":
        print(f"  Step done: {event.data.get('action', '?')}")
    elif event.type == "token":
        # Token deltas (when LLM client supports streaming)
        print(event.data.get("delta", ""), end="", flush=True)
    elif event.type == "done":
        print(f"\nFinished in {event.data['total_steps']} steps")

StreamEvent is a frozen dataclass with type (a StepEvent enum) and data (a dict). The data dict is mutable but should be treated as read-only by callers.

Security Guardrails

Super Browser enforces a security perimeter on all side-effecting facade methods. When a SecurityManager is configured (via SecurityConfig), each gated method is checked before its side effect executes. Blocked actions return an ActionResult with ErrorCategory.SECURITY — they never reach the browser.

Redaction propagation: Security-checked methods use mutable params dicts, allowing SecurityManager to redact sensitive values (URLs, file paths, input values) in-place before they reach the browser.

Direct facade vs AgentLoop: Direct facade calls (sb.navigate(), sb.click()) enforce security on the facade. AgentLoop-dispatched actions enforce security at the dispatch point — _navigate_impl() is used for the built-in navigate tool to avoid double-checking.

Default Agent Tooling

When the browser starts, SuperBrowser auto-registers 10 built-in tools that the LLM can invoke through the agent loop:

Controller tools use late-binding wrappers that dereference self._controller at call time. This ensures that after open_tab() or switch_tab() replaces the controller, tools automatically route to the new controller — no stale page actions.

Custom tools registered via register_tool() are not overwritten by the built-in registration.

Architecture

Super Browser is built on a three-tier action cascade:

1. LLM Tier — The agent interprets natural-language intent and decides which tool to invoke. Falls through if the LLM is unavailable or the task is trivial.
2. Skills Tier — Built-in, deterministic skills (navigation, extraction, form-filling, scrolling, screenshots) execute without LLM overhead.
3. Raw Browser Tier — Direct Playwright/Patchright calls when nothing else matches.

Additional subsystems:

Full API documentation lives in docs/.

What's New (Unreleased)

MCP Server, Adversarial Suite, Stealth Evidence

• MCP Server — Permissioned stdio server with 13 tools (6 read-only + 7 write). Write tools route through MCPSessionPolicy → SecurityManager → audit before reaching the browser. Default is read-only advertisement; writes opt-in via build_server(policy=MCPSessionPolicy(allow_writes=True)). See docs/mcp.md.
• Adversarial Detection Suite — 25-vector assessment harness across 6 tiers (fingerprint, automation, ejecta, behavioral, network, controlled) plus external scanners. Honest stub semantics (JSUnsupportedError → INCONCLUSIVE, never fabricated). See tests/adversarial_v3/.
• Stealth Evidence — Published comparison: Super-Browser 16/25 clean vs raw Playwright 14/25 on controlled server + scanner targets. navigator.webdriver and Sannysoft resolved; 0 regressions. See docs/stealth-evidence.md.
• Behavioral Telemetry — Mouse/keystroke/scroll analysis vectors replace permanent SKIPPED with real telemetry-driven verdicts when --record-behavior is enabled.
• Streaming API — act_stream() yields StreamEvent for real-time agent progress. Provider token streaming for OpenAI and Anthropic.
• Default Tooling — 10 built-in tools auto-registered on startup (7 controller + 3 facade). Agents work out-of-box.
• Security Perimeter — All 12 side-effecting facade methods enforce SecurityManager before reaching the browser.
• Controller Rebinding — Tools late-bind to current controller after tab switches.

What's New in v1.9

Platform Abstraction + Distribution — One API, Any Browser

v1.9.0 makes Super Browser browser-agnostic. Agents call click, fill, navigate through a protocol — the engine underneath is a deployment detail. Four backends are available.

from super_browser import SuperBrowser
from super_browser.config import Config
from super_browser.browser.config import SessionConfig

# Auto-detect best backend (Patchright → Playwright → Selenium → CDP)
browser = SuperBrowser()

# Or explicit backend via the composition root
browser = SuperBrowser(Config(browser=SessionConfig(backend="playwright")))

# Or connect to a remote CDP endpoint
browser = SuperBrowser(Config(browser=SessionConfig(backend="cdp", endpoint="ws://chromium:9222")))

Backend matrix:

Key changes:

• BrowserEngine / EnginePage / StealthBridge protocols in browser/engine.py
• PatchrightBackend, PlaywrightBackend, SeleniumBackend, CDPDirectBackend
• Controller refactored: 0 raw_page calls (all via EnginePage)
• Stealth stack uses StealthBridge protocol (not direct CDPBridge)
• StealthInjector implementations: CDPInjector (before), PageScriptInjector (after), BiDiInjector (future)
• CI: GitHub Actions 3-OS matrix + tag-triggered PyPI publish

What's New in v1.7

Agent UX & Reliability — Structured Results, Recovery, Redaction

Structured result categories, automatic stale-ref recovery, and a production-grade secret redaction pipeline.

from super_browser.results import (
    ActionResult, SuccessCategory, FailureCategory,
    NextAction, PageChangeSummary, PageFingerprint,
    compute_page_change,
)

# Structured categories — no more parsing prose
result = await browser.click("@e5")
if result.result_category == "success":
    print(result.success_category)  # SuccessCategory.NAVIGATION
    print(result.page_change_summary.change_type)  # "navigation"

# Stale ref recovery — auto-retry with fresh snapshot
# Controller detects 10 error signatures, retries once automatically
# On failure: FailureCategory.STALE_REF + 3 NextAction hints

# Secret redaction — credentials never leak
from super_browser.security import configure_redaction
from super_browser.security.types import SecurityConfig
configure_redaction(SecurityConfig())
result = await browser.fill("#password", "s3cret")
print(result.to_dict())  # password is [REDACTED:password]

What's New in v1.6

Anti-Detection Hardening — 12 Fingerprint Surfaces

Deterministic noise injection via the Ejecta Framework (stealth/ejecta/):

from super_browser.stealth.ejecta.config import EjectorConfig
from super_browser.stealth.ejecta.registry import build_ejector_payloads

config = EjectorConfig(seed="my-session-seed")
payloads = build_ejector_payloads(config)
# 5 JS payloads: canvas, audio, webrtc, timing, browser_apis
# Each deterministic — same seed → same noise

Validation suite expanded from 8 → 12 checks (CHK-009 through CHK-012).

What's New in v1.5

Fingerprint Consistency Engine

Deterministic fingerprint derivation from a single (profile, seed) pair:

from super_browser.stealth.profiles import load_profile
from super_browser.stealth.consistency.derive import derive_matrix

profile = load_profile("windows-chrome-stable")
matrix = derive_matrix(profile, "my-session-seed")
# Every surface (UA, GPU, screen, fonts, audio, timezone) is consistent

4 real-device profiles, 38 consistency rules, xoshiro256** PRNG, Fetch.fulfillRequest inject delivery.

Biomechanical Behavior v2

Scientifically grounded behavioral synthesis — no more random jitter:

from super_browser.behavioral import synthesize_mouse_trajectory, synthesize_keystrokes

# Bézier mouse path with Fitts's Law timing
traj = synthesize_mouse_trajectory(from_pt=(100,100), to_pt=(800,600),
                                     profile=bp, seed="session-1")

# QWERTY-aware typing with digraph delays + mistake injection
keys = synthesize_keystrokes(text="hello world", profile=bp, seed="session-1")

Cubic Bézier paths, Fitts's Law movement time, autocorrelated jitter, lognormal digraph delays, inertial scroll.

Chromium-Native Networking

Route HTTP requests through the browser's BoringSSL stack:

from super_browser.browser.fetch import BrowserFetch

fetch = BrowserFetch(bridge=cdp)
response = await fetch.fetch("https://api.example.com/data")
# TLS fingerprint matches the browser session — no httpx JA4 mismatch

Fingerprint Validation & Regression Harness

CI gate for stealth consistency:

super-browser stealth-validate --capture-baseline   # Record baseline
super-browser stealth-validate --ci                   # Fail CI on regression

8 cross-surface checks (UA/OS match, GPU vendor, cores, memory cap, fonts, DPR, timezone, webdriver).

What's New in v1.4

Human Behavior Simulation

Make automated interactions appear natural with configurable presets:

from super_browser.stealth.human import HumanBehaviorAdapter
from super_browser.stealth.human_config import HumanConfig

adapter = HumanBehaviorAdapter(config=HumanConfig(preset="careful"), backend="patchright")
await adapter.humanize_click(page, "#submit-btn")
await adapter.humanize_type(page, "#search", "hello world")
await adapter.humanize_scroll(page, "down")

Three presets: default (general), careful (high-security), fast (speed). Works with both CloakBrowser and Patchright backends. See docs/human-behavior.md.

Fingerprint Scoring

Assess your stealth configuration with a weighted composite score:

from super_browser.stealth.fingerprint_scanner import FingerprintScanner

scanner = FingerprintScanner(scanner_config={"offline": True})
score = await scanner.scan()
print(f"Stealth score: {score.overall}/100")  # e.g. 93/100

CLI command for quick checks:

super-browser stealth-check                  # Offline (no browser needed)
super-browser stealth-check --format html     # HTML report
super-browser stealth-check --online          # Live check (requires browser)

See docs/fingerprint-scoring.md.

What's New in v1.3

Plugin & Hook System

Extend Super Browser with custom lifecycle hooks using the @hook() decorator:

from super_browser.plugins import hook

@hook("after_navigate")
def log_page(ctx):
    print(f"Loaded: {ctx['title']}")

Seven lifecycle events: before_navigate, after_navigate, before_action, after_action, on_error, on_loop_detected, on_budget_alert. See docs/plugins.md.

Session Recording

Record, save, and replay browser sessions:

sb.enable_recording()
await sb.navigate("https://example.com")
session = sb.recording.stop()
# Save, replay, or generate HTML audit reports

See docs/recording.md.

CLI Modes

Interactive REPL, YAML script execution, and one-shot agent commands:

super-browser interactive    # Interactive REPL
super-browser script task.yaml  # Execute a script
super-browser act "Find the price" --url https://shop.com  # One-shot agent

Per-Domain Memory

Persist successful action sequences, working selectors, and site preferences:

sb.enable_memory()
# Successful tasks are automatically recorded per domain
# Context is injected into future LLM prompts

See docs/memory.md.

Stealth Backend

Super Browser supports CloakBrowser as an optional stealth backend — a hardened Chromium with 57 C++ anti-detection patches:

pip install superbrowser-sdk[patchright,cloak]

When installed, CloakBrowser is automatically detected and used. No code changes required:

from super_browser import SuperBrowser

async with SuperBrowser() as sb:
    print(sb.stealth_backend)  # "cloak" (or "patchright" if not installed)

Configure via environment variables or Config:

from super_browser import Config

config = Config.from_dict({
    "cloak": {
        "cloak_humanize": True,       # Human-like mouse/keyboard
        "cloak_fingerprint_seed": 42,  # Persistent browser identity
        "cloak_geoip": True,           # Auto-detect timezone from proxy
    }
})

See docs/cloak-integration.md for the complete guide.

Development

git clone https://github.com/Octo-Lex/Super-Browser.git
cd super-browser
pip install -e ".[patchright,anthropic,openai,dev]"
pytest

See CONTRIBUTING.md for the full guide. All work follows the Disk-Verified Large-Wave Execution doctrine.

License

Apache License 2.0 — see LICENSE.