agentic-stealth-browser 2.3.0__tar.gz → 2.4.0__tar.gz

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.4.0] — Attach-Mode Hardening (2026-06-01)
+
+### Fixed
+- **#438** `stealth_attach_over_cdp` loopback gate reused `is_url_safe` — DNS rebinding / hostname→private-IP bypass closed. Replaces string match with full RFC-1918 + link-local + cloud-metadata check. The gate is now a two-layer check: `is_loopback_host` first, then `is_url_safe` only when `allow_remote=true` (so even explicitly-allowed remote hosts can't be RFC-1918 or link-local).
+- **#441** Link-local IPv6 (`fe80::/10`) added to `_BLOCKED_NETWORKS`. Side-effect of #438's refactor — `is_url_safe` now rejects IPv6 link-local the same way it rejects IPv4 `169.254.0.0/16`.
+- **#440** `add_init_script` install failure now surfaces in the return payload as `stealth_applied: false` + `stealth_error: "<ExceptionType>: <message>"`. Previously silent. New `stealth_requested` field distinguishes caller intent from actual install result.
+- **#439** `AgentBrowser.close()` teardown logic now uses a typed `TeardownMode` enum (`LAUNCHED | POOLED | ATTACHED_OWNED_CTX | ATTACHED_ADOPTED_CTX`) instead of 3 scattered `getattr` flag checks. Each branch owns exactly one teardown. Easier to reason about, easier to extend.
+
+### Added
+- **`is_loopback_host(url: str) -> bool`** helper in `production/mcp_server.py` — literal/IP/DNS loopback check. Used by the attach loopback gate.
+- **6 new tests in `tests/test_mcp_url_safety.py`** covering loopback literal, `localhost`, bare `host:port` normalization, RFC-1918 rejection, link-local IPv6 rejection.
+- **4 new tests in `tests/test_attach_over_cdp.py`** covering the two-layer gate (RFC-1918, link-local IPv6, with/without `allow_remote=true`).
+- **4 new tests in `tests/test_attach_over_cdp.py`** for `TeardownMode` enum and stealth-failure surface (monkeypatched `add_init_script` rejection).
+
+### Changed
+- `production/mcp_server.py`: new `is_loopback_host` helper. `_BLOCKED_NETWORKS` extended with `fe80::/10`. `_tool_stealth_attach_over_cdp` rewritten as a two-layer gate.
+- `core/agent_browser.py`: new `TeardownMode` enum. `close()` branches on the enum. `attach_over_cdp` return dict now includes `stealth_requested` and `stealth_error` fields.
+- `pyproject.toml`: `version` bumped 2.3.0 → 2.4.0.
+
+### Test coverage
+- 22/22 pass in `tests/test_attach_over_cdp.py` + `tests/test_mcp_url_safety.py`
+- No new regressions in the unit-test suite (3 pre-existing failures on master — `test_human_behavior_fuzz` MockPage signature mismatch + `test_phase7_fixes` merge conflict — both unrelated to this release)
+
+### Closes
+- #438, #439, #440, #441
+
+---
+
+## [Unreleased]
+
+### Added
+- **`AgentBrowser.attach_over_cdp(cdp_url, ...)`**: connect to an already-running
+  browser exposed via Chrome DevTools Protocol (e.g. Chrome launched with
+  `--remote-debugging-port=9222`) instead of spawning a new Chromium. Complements
+  the existing `debug_cdp=True` launch flag — that one *exposes* an endpoint, this
+  one *consumes* one. Primary use case: drive a real desktop browser from a
+  different host (WSL → Windows, container → host, dev box → remote display).
+  Runtime stealth init scripts (navigator/canvas/WebGL/audio patches) are still
+  injected on the chosen context; launch-time stealth (TLS/JA3, regional preset,
+  user-data-dir) is unavailable in attach mode and listed in the return payload's
+  `degradation` field. `close()` disconnects without terminating the external
+  browser. (#attach-cdp)
+- **MCP tool `stealth_attach_over_cdp`**: surfaces `attach_over_cdp` through the
+  MCP server. Defaults to loopback-only; non-loopback hosts require explicit
+  `allow_remote=true` and raise `MCP_REMOTE_CDP_BLOCKED` otherwise. (#attach-cdp)
+
 ## [2.3.0] — Show HN & Community Launch (2026-05-28)
 
 ### Added

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-stealth-browser
-Version: 2.3.0
+Version: 2.4.0
 Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
 Author-email: Shane W <shanewas@users.noreply.github.com>
 License-Expression: MIT
@@ -45,7 +45,8 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/agentic-stealth-browser.svg)](https://pypi.org/project/agentic-stealth-browser/)
-[![Tests](https://img.shields.io/badge/tests-880%2B%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-890%2B%20passing-brightgreen)](tests/)
+[![GitHub Stars](https://img.shields.io/github/stars/shanewas/agentic-stealth-browser?style=flat&logo=github)](https://github.com/shanewas/agentic-stealth-browser)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/shanewas)
 
 <p align="center">
@@ -129,6 +130,25 @@ async with AgentBrowser(
 
 Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_close`.
 
+### Attach to an existing browser (WSL → Windows, container → host)
+
+Instead of launching a new Chromium, you can attach to a Chrome you already
+have running with `--remote-debugging-port=9222`:
+
+```python
+async with AgentBrowser(session_name="attached") as browser:
+    await browser.attach_over_cdp(
+        "http://127.0.0.1:9222",   # or the Windows host IP from WSL
+        new_context=True,           # don't disturb the user's tabs
+    )
+    await browser.safe_goto("https://bot.sannysoft.com")
+    # close() will NOT terminate the external browser
+```
+
+See [docs/ATTACH_OVER_CDP.md](docs/ATTACH_OVER_CDP.md) for the WSL→Windows
+walkthrough, the MCP `stealth_attach_over_cdp` tool, and the stealth
+degradation matrix (init-script stealth still applies; TLS/JA3 does not).
+
 ---
 
 ## Key Features
@@ -150,18 +170,28 @@ Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_
 
 ---
 
+## New in v2.3.0
+
+- **Show HN launch** — README overhaul, demo GIF, streamlined community onboarding
+- **Buy Me A Coffee** — sponsor the project directly
+- **PID tracking** — `AgentBrowser._browser_process` for external process monitoring
+- **PyPI publish automation** — OIDC trusted publishing on every release tag
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## Full Documentation
 
-- **Workflow System** — record real browser actions via CDP, replay as YAML (13 step types)
-- **Operator Dashboard** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
-- **Orchestrator** — queue, schedule, chain workflows with domain-aware concurrency
-- **Security** — input validation, session isolation, policy engine, approval gates
-- **SDK** — `StealthClient` async API without MCP
-- **Plugins** — lifecycle hooks for custom behavior
-- **VPS Deployment** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
-- **Migration v1 → v2** — deprecation shims, migration guide, script
+- **[Operator Dashboard](production/hermes_dashboard.py)** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
+- **[Workflow Orchestrator](production/workflow_orchestrator.py)** — queue, schedule, chain workflows with domain-aware concurrency
+- **[Security](production/)** — input validation, session isolation, policy engine, approval gates
+- **[SDK](production/sdk/)** — `StealthClient` async API without MCP
+- **[Plugins](plugins/)** — lifecycle hooks for custom behavior
+- **[VPS Deployment](scripts/setup_rbb.sh)** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
+- **[Migration v1 → v2](scripts/migrate_v1_to_v2.py)** — deprecation shims, migration guide, script
 
-See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG.md).
+Additional references: [CHANGELOG.md](CHANGELOG.md) · [Workflow Library](workflows/library/) · [Migration Guide](scripts/migrate_v1_to_v2.py)
 
 ---
 
@@ -176,7 +206,7 @@ See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG
 ├── production/     MCP server, SDK, orchestrator, security, profiler
 ├── plugins/        Plugin system with template
 ├── scripts/        Migration, evaluation, benchmarking
-└── tests/          880+ contract + integration tests
+└── tests/          890+ contract + integration tests
 ```
 
 ## License

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/README.md

@@ -6,7 +6,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/agentic-stealth-browser.svg)](https://pypi.org/project/agentic-stealth-browser/)
-[![Tests](https://img.shields.io/badge/tests-880%2B%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-890%2B%20passing-brightgreen)](tests/)
+[![GitHub Stars](https://img.shields.io/github/stars/shanewas/agentic-stealth-browser?style=flat&logo=github)](https://github.com/shanewas/agentic-stealth-browser)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/shanewas)
 
 <p align="center">
@@ -90,6 +91,25 @@ async with AgentBrowser(
 
 Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_close`.
 
+### Attach to an existing browser (WSL → Windows, container → host)
+
+Instead of launching a new Chromium, you can attach to a Chrome you already
+have running with `--remote-debugging-port=9222`:
+
+```python
+async with AgentBrowser(session_name="attached") as browser:
+    await browser.attach_over_cdp(
+        "http://127.0.0.1:9222",   # or the Windows host IP from WSL
+        new_context=True,           # don't disturb the user's tabs
+    )
+    await browser.safe_goto("https://bot.sannysoft.com")
+    # close() will NOT terminate the external browser
+```
+
+See [docs/ATTACH_OVER_CDP.md](docs/ATTACH_OVER_CDP.md) for the WSL→Windows
+walkthrough, the MCP `stealth_attach_over_cdp` tool, and the stealth
+degradation matrix (init-script stealth still applies; TLS/JA3 does not).
+
 ---
 
 ## Key Features
@@ -111,18 +131,28 @@ Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_
 
 ---
 
+## New in v2.3.0
+
+- **Show HN launch** — README overhaul, demo GIF, streamlined community onboarding
+- **Buy Me A Coffee** — sponsor the project directly
+- **PID tracking** — `AgentBrowser._browser_process` for external process monitoring
+- **PyPI publish automation** — OIDC trusted publishing on every release tag
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## Full Documentation
 
-- **Workflow System** — record real browser actions via CDP, replay as YAML (13 step types)
-- **Operator Dashboard** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
-- **Orchestrator** — queue, schedule, chain workflows with domain-aware concurrency
-- **Security** — input validation, session isolation, policy engine, approval gates
-- **SDK** — `StealthClient` async API without MCP
-- **Plugins** — lifecycle hooks for custom behavior
-- **VPS Deployment** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
-- **Migration v1 → v2** — deprecation shims, migration guide, script
+- **[Operator Dashboard](production/hermes_dashboard.py)** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
+- **[Workflow Orchestrator](production/workflow_orchestrator.py)** — queue, schedule, chain workflows with domain-aware concurrency
+- **[Security](production/)** — input validation, session isolation, policy engine, approval gates
+- **[SDK](production/sdk/)** — `StealthClient` async API without MCP
+- **[Plugins](plugins/)** — lifecycle hooks for custom behavior
+- **[VPS Deployment](scripts/setup_rbb.sh)** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
+- **[Migration v1 → v2](scripts/migrate_v1_to_v2.py)** — deprecation shims, migration guide, script
 
-See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG.md).
+Additional references: [CHANGELOG.md](CHANGELOG.md) · [Workflow Library](workflows/library/) · [Migration Guide](scripts/migrate_v1_to_v2.py)
 
 ---
 
@@ -137,7 +167,7 @@ See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG
 ├── production/     MCP server, SDK, orchestrator, security, profiler
 ├── plugins/        Plugin system with template
 ├── scripts/        Migration, evaluation, benchmarking
-└── tests/          880+ contract + integration tests
+└── tests/          890+ contract + integration tests
 ```
 
 ## License

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/agentic_stealth_browser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-stealth-browser
-Version: 2.3.0
+Version: 2.4.0
 Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
 Author-email: Shane W <shanewas@users.noreply.github.com>
 License-Expression: MIT
@@ -45,7 +45,8 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/agentic-stealth-browser.svg)](https://pypi.org/project/agentic-stealth-browser/)
-[![Tests](https://img.shields.io/badge/tests-880%2B%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-890%2B%20passing-brightgreen)](tests/)
+[![GitHub Stars](https://img.shields.io/github/stars/shanewas/agentic-stealth-browser?style=flat&logo=github)](https://github.com/shanewas/agentic-stealth-browser)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/shanewas)
 
 <p align="center">
@@ -129,6 +130,25 @@ async with AgentBrowser(
 
 Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_close`.
 
+### Attach to an existing browser (WSL → Windows, container → host)
+
+Instead of launching a new Chromium, you can attach to a Chrome you already
+have running with `--remote-debugging-port=9222`:
+
+```python
+async with AgentBrowser(session_name="attached") as browser:
+    await browser.attach_over_cdp(
+        "http://127.0.0.1:9222",   # or the Windows host IP from WSL
+        new_context=True,           # don't disturb the user's tabs
+    )
+    await browser.safe_goto("https://bot.sannysoft.com")
+    # close() will NOT terminate the external browser
+```
+
+See [docs/ATTACH_OVER_CDP.md](docs/ATTACH_OVER_CDP.md) for the WSL→Windows
+walkthrough, the MCP `stealth_attach_over_cdp` tool, and the stealth
+degradation matrix (init-script stealth still applies; TLS/JA3 does not).
+
 ---
 
 ## Key Features
@@ -150,18 +170,28 @@ Then: `stealth_launch` → `stealth_navigate` → `stealth_scrape` → `stealth_
 
 ---
 
+## New in v2.3.0
+
+- **Show HN launch** — README overhaul, demo GIF, streamlined community onboarding
+- **Buy Me A Coffee** — sponsor the project directly
+- **PID tracking** — `AgentBrowser._browser_process` for external process monitoring
+- **PyPI publish automation** — OIDC trusted publishing on every release tag
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+---
+
 ## Full Documentation
 
-- **Workflow System** — record real browser actions via CDP, replay as YAML (13 step types)
-- **Operator Dashboard** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
-- **Orchestrator** — queue, schedule, chain workflows with domain-aware concurrency
-- **Security** — input validation, session isolation, policy engine, approval gates
-- **SDK** — `StealthClient` async API without MCP
-- **Plugins** — lifecycle hooks for custom behavior
-- **VPS Deployment** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
-- **Migration v1 → v2** — deprecation shims, migration guide, script
+- **[Operator Dashboard](production/hermes_dashboard.py)** — Grok/X-inspired dark UI, live browser view, CAPTCHA solving, workflow recording
+- **[Workflow Orchestrator](production/workflow_orchestrator.py)** — queue, schedule, chain workflows with domain-aware concurrency
+- **[Security](production/)** — input validation, session isolation, policy engine, approval gates
+- **[SDK](production/sdk/)** — `StealthClient` async API without MCP
+- **[Plugins](plugins/)** — lifecycle hooks for custom behavior
+- **[VPS Deployment](scripts/setup_rbb.sh)** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
+- **[Migration v1 → v2](scripts/migrate_v1_to_v2.py)** — deprecation shims, migration guide, script
 
-See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG.md).
+Additional references: [CHANGELOG.md](CHANGELOG.md) · [Workflow Library](workflows/library/) · [Migration Guide](scripts/migrate_v1_to_v2.py)
 
 ---
 
@@ -176,7 +206,7 @@ See sections below for each topic. For release history: [CHANGELOG.md](CHANGELOG
 ├── production/     MCP server, SDK, orchestrator, security, profiler
 ├── plugins/        Plugin system with template
 ├── scripts/        Migration, evaluation, benchmarking
-└── tests/          880+ contract + integration tests
+└── tests/          890+ contract + integration tests
 ```
 
 ## License

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/agentic_stealth_browser.egg-info/SOURCES.txt

@@ -79,6 +79,7 @@ tests/run_detection_tests.py
 tests/test_account_health.py
 tests/test_account_warming.py
 tests/test_adaptive_tuner.py
+tests/test_attach_over_cdp.py
 tests/test_basic.py
 tests/test_cdp_snapshots.py
 tests/test_connection_pool.py
@@ -97,6 +98,7 @@ tests/test_linkedin_actions.py
 tests/test_mcp_contract.py
 tests/test_mcp_server_runtime.py
 tests/test_mcp_stealth_workflows.py
+tests/test_mcp_url_safety.py
 tests/test_metrics_collector_unit.py
 tests/test_mutation_stealth.py
 tests/test_persona_rotator.py

{agentic_stealth_browser-2.3.0 → agentic_stealth_browser-2.4.0}/audit/logger.py

@@ -215,12 +215,6 @@ class AuditLogger:
         Redaction is mandatory by default (opt-in to disable via AGENTIC_STEALTH_NO_REDACT
         env var, intended ONLY for local debugging).
         """
-        if os.getenv("AGENTIC_STEALTH_NO_REDACT", "").strip().lower() in (
-            "1",
-            "true",
-            "yes",
-        ):
-            return details if isinstance(details, dict) else details
         SENSITIVE_KEYS = frozenset(
             [
                 "password",