v3.0.0 — Enterprise Hardening, Part 2

Large enterprise-readiness pass. One breaking change; everything else additive or behavior-preserving. Full detail in CHANGELOG.md.

⚠️ Breaking

• MCP approval gate is now fail-closed by default. Sensitive actions (execute_js, stealth_launch, navigate to unknown domains, run_workflow, stealth_replay) return MCP_APPROVAL_REQUIRED until approved. Set STEALTH_APPROVAL_MODE=permissive to restore the previous auto-approve behavior.

Highlights

• Auditability: success audit records, HMAC-keyed tamper-evidence chain (verify_audit_chain), log rotation/retention, recursive + token redaction.
• Dashboard RBAC: per-user viewer/operator roles, attributable operator audit log, boot refuses the default password, /metrics + /api/usage.
• Supply chain: hash-pinned universal lockfile, blocking pip-audit + bandit + gitleaks, SBOM + build-provenance attestation, SHA-pinned Actions, py.typed.
• CI is now a real gate: blocking mypy, coverage 55%, Python 3.10–3.13 + cross-OS matrix.
• Reliability: launch driver-leak fix, opt-in respect_robots, per-session request budget.
• Architecture: inverted layering resolved, dashboard HTML + MCP handlers extracted, stable from core import AgentBrowser facade.
• Governance/compliance: acceptable-use, governance, DCO, incident-response, key-management, data-handling, backup/DR docs.

CI green on master (Python 3.10–3.13 + ubuntu/windows/macOS, blocking mypy + pip-audit + bandit) before release.

v2.7.0 — Enterprise Hardening

Auditability, supply-chain, and business-facing hardening from a full enterprise audit. No breaking changes; no runtime behavior change on existing flows.

Added

• Acceptable Use Policy (ACCEPTABLE_USE.md) + README Legal & Acceptable Use section — authorized-use scope, prohibited uses (ToS/robots/CFAA/GDPR-CCPA), operator responsibility. Procurement-ready for an anti-bot tool.
• Compliance docs: docs/INCIDENT_RESPONSE.md, docs/KEY_MANAGEMENT.md, docs/DATA_HANDLING.md.
• Navigation metrics: safe_goto now emits requests_success/requests_failed + record_error("navigation", …), so MetricsCollector.success_rate reflects real traffic (was permanently 100%).

Changed / Security

• Dependency lower bounds pinned to CVE-safe floors (aiohttp>=3.10.11, cryptography>=43.0.1, jinja2>=3.1.5, …); no upper caps, existing installs unaffected.
• twine check --strict gate added to the publish workflow before upload.
• SECURITY.md supported-versions corrected (0.8.x → 2.7.x); README claims hedged to a point-in-time canary snapshot.
• 5 live-Chromium attach tests marked @pytest.mark.e2e so the default CI run stays deterministic.

Full detail in CHANGELOG.md. CI green on master before release.

v2.6.0 — Stealth & MCP Hardening

Stealth & MCP hardening release. Reliability + security focus.

Added

• Stealth patch isolation — each fingerprint patch is now try/catch-isolated; one API mismatch degrades only that signal instead of aborting every later patch.
• attach_mode for attach_over_cdp — skips navigator.platform / WebGL vendor-renderer / screen-DPR overrides when attaching to a real browser, so the injected fingerprint no longer contradicts the real OS/GPU/display.
• MCP policy + approval gates — PolicyEngine (step-type/domain allow-lists) and ApprovalGate wired into the tools/call dispatch path and workflow replay. Fail-open by default (no policy files = allow all); operators opt into enforcement via STEALTH_MCP_POLICY or an approval callback.
• AdapterToolError — MCP tool results with isError: true are now surfaced instead of silently treated as success.

Fixed

• WebRTC ICE leak — per-instance onicecandidate rebind (no prototype-global leak) and addEventListener('icecandidate') is now filtered too; createDataChannel restored to real passthrough.
• playwright-mcp adapter — pinned @playwright/mcp@0.0.78 with corrected browser_navigate/browser_click/browser_type schema (element/target/text); prior CSS-selector args were rejected by the real server.
• CDP bridge — launch(profile) accepts a raw ws/wss/http(s) endpoint or a profile name resolved via CDP_ENDPOINT_<PROFILE>/CDP_ENDPOINT, aligning it with the BackendAdapter protocol.
• Recovery — rotation failure now propagates (returns False for ROTATE_*) and records _update_recovery_history(success=False); unique per-attempt session/proxy names avoid collisions.

Changed

• Adapter status() gains a canonical connected field (running kept as back-compat alias).
• SessionEnforcer documented as defined-but-inert until a multi-client transport supplies per-context tokens.

Full detail in CHANGELOG.md. Tests: 976 passing on CI.

v2.5.0 — Real Dashboard Backend Adapters (#444)

v2.5.0 — Real Dashboard Backend Adapters (#444)

Closes #444. Replaces the three thin dashboard backend aliases with genuinely distinct adapter implementations (M0–M4), and fixes the v2.4.1 status subcommand crash on a fresh install (the subparser was missing --headless/--session).

What ships

• BackendAdapter Protocol + Capability enum (production/adapters/base.py:84): runtime-checkable protocol surface; new AdapterLaunchError / AdapterCapabilityError exception types; register_adapter enforces non-empty string names. M0.
• CDPBridgeAdapter (production/adapters/cdp_bridge.py): Playwright connect_over_cdp over WebSocket for adopted-context / WSL-host workflows. M1.
• PlaywrightMCPAdapter (production/adapters/playwright_mcp.py): stdio subprocess + MCP JSON-RPC. Env allowlist (PATH, HOME), 16 MB frame cap, stderr drain. M2.
• AgenticStealthMCPAdapter (production/adapters/agentic_stealth_mcp.py): stdio subprocess + MCP JSON-RPC round-tripping the bundled MCP server. Same env/frame/stderr guarantees. M3.
• Dashboard backend wiring (M4): BrowserRuntimeManager resolves through the adapter registry, records an audit event on backend switch, surfaces negotiated capabilities in status, rejects unsupported actions with a backend-specific error. production/dashboard_adapter_bridge.py is now a thin shim.

Pre-release review fixes (#444 M0 review)

• S1 capability gating: M2/M3 actions now call self.supports() and raise AdapterCapabilityError if the capability isn't declared. Enforces the base.py:84 contract.
• S2 stderr drain: M2/M3 stderr=PIPE is drained by a background task started right after spawn and cancelled in close(). A noisy child no longer fills the ~64 KB kernel pipe buffer and hangs the handshake.
• F1 stale state on retry: after MCP handshake failure, terminate_subprocess() is called and self._proc / self._client are cleared.
• F2 frame cap: _jsonrpc_stdio.readline() enforces MAX_FRAME_BYTES = 16 MB and raises ConnectionError on overflow. A misbehaving server emitting a multi-GB line no longer OOMs the client.
• F3 env allowlist: both stdio adapters pass an explicit env={PATH, HOME} instead of inheriting the operator's full environment (OPENAI_API_KEY, AWS_*, DATABASE_URL, ...).
• A3 dead tautology: cdp_bridge.screenshot() defensive branch removed; M0 contract is the only contract that matters.
• M0 code-quality review (17abc50): exception types narrowed, isinstance coverage tightened, defensive tautology branches removed, transport teardown symmetric with launch.

Packaging & docs

• MANIFEST.in ships assets/*.{gif,png,jpg,svg} (demo GIF), docs/, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md.
• README: "What is this / When to use / When NOT to use" block, honest comparison table (region client-hello profiles, not full uTLS), install-from-source section, full doc index. Dropped unverified test-count badge and Buy Me A Coffee. 177 → 238 lines.
• New docs/README.md operator/reference/planning index. Examples rewritten for honesty and reproducibility (01_cloudflare_bypass.py, 02_linkedin_search.py, 03_amazon_product.py).

Tests

• tests/test_backend_adapter_contract.py — M0 contract (Protocol surface, Capability enum, register_adapter enforcement).
• tests/test_adapter_cdp_bridge.py, tests/test_adapter_playwright_mcp.py, tests/test_adapter_agentic_stealth_mcp.py — per-adapter launch/capability/stderr-drain/env-allowlist/close tests.
• tests/test_dashboard_protocol_bridge.py — M4 audit event + capability surface + unsupported-action rejection.
• 1025 collected, 1023 passed, 2 e2e skipped, 0 failed.
• ruff check + ruff format --check clean across 159 Python files.
• M+2.5 wheel smoke test on a fresh venv: every CLI subcommand --help works, real status invocation completes with the v2.4.0 Namespace.headless regression confirmed fixed.

Install

pip install --upgrade agentic-stealth-browser==2.5.0

Known non-blocking diagnostics

On a real status run, one HEALTH ERROR: 'str' object has no attribute 'get' line may be logged. Caught and surfaced; status report completes successfully with exit 0. Tracked as a follow-up.

Closes #444.

v2.4.0 — Attach-Mode Hardening

v2.4.0 — Attach-Mode Hardening

Closes the 4 Clawpatch findings from the PR #437 review: #438, #439, #440, #441.

What's new

• Two-layer host safety gate in stealth_attach_over_cdp — is_loopback_host (literal/IP/DNS) + is_url_safe (RFC-1918 / link-local / cloud-metadata). Closes DNS-rebinding / hostname→private-IP bypass.
• fe80::/10 (link-local IPv6) added to _BLOCKED_NETWORKS. Side-effect of the gate refactor.
• add_init_script install failure now surfaces in the return payload as stealth_applied: false + stealth_error: "<Type>: <message>". New stealth_requested field distinguishes caller intent from actual install result.
• TeardownMode enum replaces the 3 scattered getattr flag checks in close(). Each branch owns exactly one teardown (LAUNCHED | POOLED | ATTACHED_OWNED_CTX | ATTACHED_ADOPTED_CTX).

New helper

is_loopback_host(url: str) -> bool in production/mcp_server.py — literal/IP/DNS loopback check. Used by the attach loopback gate.

Test coverage

22/22 pass in tests/test_attach_over_cdp.py + tests/test_mcp_url_safety.py. No new regressions.

Install

pip install --upgrade agentic-stealth-browser

Now requires Python 3.10+ (unchanged from 2.3.0).

v2.3.0 — Show HN & Community Launch

What's New

Added

• Show HN preparation: Complete README overhaul with demo GIF, streamlined onboarding, and community-facing tone.
• Buy Me A Coffee badge: Support link in README for community sponsorship.
• _browser_process exposure: External PID tracking via AgentBrowser._browser_process, enabling process-level monitoring and recovery.

Changed

• Full README rewrite for PyPI + HN audience (pip-first install path, Quick Start with CLI + Python SDK + MCP, reduced wall-of-text, more code examples).
• Demo GIF (assets/hn-demo.gif) showing end-to-end stealth browser flow.
• Various lint fixes for demo scripts.

Fixed

• Stray temp files cleaned from repo root.
• Ruff formatting applied across all Python sources.

---

Also in this release (v2.1.1 catch-up)

• PyPI publish workflow with OIDC trusted publishing
• Docs consolidation — all documentation in one README
• Ruff formatting across dashboard

---

Full Changelog: v2.1.1...v2.3.0

v2.1.0 — Hermes Browser Dashboard

Hermes Browser Dashboard

New single-user operator dashboard with live browser control, execution management, and workflow recording/replay.

Added

• Hermes Browser Dashboard (production/hermes_dashboard.py): Single-user operator dashboard with live browser view, execution control, workflow recording/replay, activity timeline, session auth, and CSRF protection. (#434)
• stealth-browser dashboard CLI subcommand: Starts the dashboard server on 127.0.0.1:8443. (#434)
• Dashboard tests: 6 contract tests covering all control plane operations.

Fixed

• CI: setup-python v6, httpx install in stealth workflow, Python 3.11 compatibility, ruff formatting

---

Full Changelog: v2.0.0...v2.1.0

v1.0.0 — Workflow Engine, Recorder, MCP Teach/Replay + Bridge Ops

v1.0.0

Milestone Stack (M0–M5)

Milestone	Description
M0 — Schema + Validator + Variables	YAML workflow schema with typed steps, validator, env variable interpolation
M1 — Workflow Player	Executes workflow YAML against the bridge backend via WorkflowPlayer + ActionInterpreter
M2 — Recorder	Passive CDP event capture → workflow YAML generation
M3 — MCP Teach/Replay Tools	MCP tool interface for teach and replay workflows
M4 — Recovery + Checkpoint	Anti-block recovery orchestration, checkpoint persistence, stealth hardening
M5 — Bridge Ops + Workflow Library	Remote bridge setup scripts, health check, initial workflow library for LinkedIn/Upwork/common patterns

What's New

• Workflow Engine — define browser automation as typed YAML steps (navigate, click, type, screenshot, wait, extract, etc.)
• Teach Mode — record real browser interactions via CDP and convert to reusable workflows
• Replay — execute recorded or authored workflows with checkpoint/recovery support
• MCP Integration — teach_workflow and replay_workflow MCP tools registered automatically
• Operator Setup — scripts/setup_rbb.sh (Linux) and setup_rbb.ps1 (Windows) for remote bridge deployment
• Workflow Library — initial 8 workflows for common automation patterns (LinkedIn connections, Upwork proposals, login flows)
• Health Check — scripts/health_check.py for bridge monitoring

Changelog Highlights

• SERVER_VERSION bumped to 1.0.0
• pyyaml added to project dependencies
• 36 new files, 5,305 lines added
• 126 tests total (across all milestones)
• Full operator docs at docs/OPERATOR_SETUP.md

Migration Notes

If upgrading from v0.9.x:

1. pip install -e . — pyyaml is now a core dependency
2. New workflows/ package is auto-discovered
3. MCP server registers teach_workflow and replay_workflow tools automatically
4. See docs/OPERATOR_SETUP.md for bridge setup instructions

v0.8.0 - Production Ready

Full Changelog: https://github.com/shanewas/agentic-stealth-browser/commits/v0.8.0