fleet-framework 0.1.1__tar.gz → 0.1.2__tar.gz

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleet-framework
-Version: 0.1.1
+Version: 0.1.2
 Summary: generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)
 Author: Sarper Avci
 License: MIT
@@ -23,6 +23,9 @@ Requires-Dist: DrissionPage>=4.1.0; extra == "browser"
 Requires-Dist: cryptography>=42.0.0; extra == "browser"
 Provides-Extra: cloudflare
 Requires-Dist: fleet-framework[browser]; extra == "cloudflare"
+Provides-Extra: cloak
+Requires-Dist: fleet-framework[browser]; extra == "cloak"
+Requires-Dist: cloakbrowser>=0.3; extra == "cloak"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
@@ -31,7 +34,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Provides-Extra: all
-Requires-Dist: fleet-framework[browser,cloudflare,otel]; extra == "all"
+Requires-Dist: fleet-framework[browser,cloak,cloudflare,otel]; extra == "all"
 Dynamic: license-file
 
 # Fleet

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/fleet_browser/browser.py

@@ -13,6 +13,12 @@ from typing import Optional
 import psutil
 from DrissionPage import ChromiumOptions, ChromiumPage
 
+from fleet_browser.cloak import (
+    CLOAK_IGNORE_DEFAULT_ARGS,
+    cloak_stealth_args,
+    ensure_cloak_binary,
+    resolve_engine,
+)
 from fleet_browser.proxy_extension import build_proxy_auth_extension, parse_proxy_url
 from fleet_browser.stealth import Stealth
 
@@ -120,6 +126,39 @@ class BrowserConfig:
 
     extra_args: tuple[str, ...] = ()
 
+    engine: str = "auto"
+    """Which Chromium build to launch. `"auto"` picks `"cloak"` when the
+    cloakbrowser package is installed, else falls back to `"chrome"`.
+    Set explicitly to override:
+      - `"chrome"`: use the system Chromium / Brave / Thorium auto-detect path
+      - `"cloak"`: use the CloakBrowser patched binary (downloads on first
+        use, raises if `cloakbrowser` isn't installed)
+    Cloak applies source-level canvas/WebGL/audio/font/WebRTC patches that
+    JS-level stealth can't reach. Stack FingerprintStealth on top to add
+    per-launch UA/version diversity from the uaforge corpus."""
+
+    cloak_cache_dir: Optional[str] = None
+    """Override the cloak binary cache dir (default ~/.cloakbrowser/)."""
+
+    cloak_fingerprint_seed: Optional[int] = None
+    """Force a specific cloak --fingerprint=N seed. Default: random per
+    launch. Pin a seed for reproducible tests."""
+
+    cloak_platform: str = "windows"
+    """`--fingerprint-platform` flag for cloak's binary. Must match the
+    OS family FingerprintStealth's UA claims (uaforge default is Windows).
+    Set 'macos' if you switch uaforge to a Mac corpus."""
+
+    cloak_timezone: Optional[str] = None
+    """IANA timezone for cloak's `--fingerprint-timezone` flag. Set when
+    using residential proxies so the spoofed timezone matches the egress
+    geo (otherwise CF flags the mismatch). Falls back to system tz."""
+
+    cloak_webrtc_ip: Optional[str] = None
+    """Public IP cloak should advertise via WebRTC. Set to the proxy's exit
+    IP when using residential — otherwise WebRTC leaks your real LAN IP
+    and CF correlates the mismatch."""
+
 
 class ChromiumWorker:
 
@@ -133,9 +172,16 @@ class ChromiumWorker:
         if self.page is not None:
             return self.page
 
-        binary = self.config.browser_binary or _find_browser_binary(
-            prefer=self.config.prefer_browser,
-        )
+        engine = resolve_engine(self.config.engine)
+        if engine == "cloak":
+            # Caller may still pin browser_binary explicitly — honor it.
+            binary = self.config.browser_binary or ensure_cloak_binary(
+                self.config.cloak_cache_dir
+            )
+        else:
+            binary = self.config.browser_binary or _find_browser_binary(
+                prefer=self.config.prefer_browser,
+            )
 
         self._user_data_dir = Path(tempfile.mkdtemp(prefix="chromium-worker-"))
         self._owns_user_data_dir = True
@@ -147,6 +193,23 @@ class ChromiumWorker:
         opts.set_user_data_path(str(self._user_data_dir))
         opts.set_argument(f"--window-size={self.config.window_size[0]},{self.config.window_size[1]}")
 
+        if engine == "cloak":
+            for arg in cloak_stealth_args(
+                platform=self.config.cloak_platform,
+                timezone=self.config.cloak_timezone,
+                webrtc_ip=self.config.cloak_webrtc_ip,
+                seed=self.config.cloak_fingerprint_seed,
+            ):
+                opts.set_argument(arg)
+            # Suppress Chromium defaults that leak automation signals.
+            # DrissionPage doesn't expose ignore_default_args; pass as
+            # --disable-features-replacement via plain args. The cloak
+            # binary recognises --no-enable-automation as an inversion.
+            for kill in CLOAK_IGNORE_DEFAULT_ARGS:
+                # Chromium accepts --disable-foo as the inverse of --enable-foo.
+                inv = kill.replace("--enable-", "--disable-", 1)
+                opts.set_argument(inv)
+
         # HttpsUpgrades is off so self-signed HTTPS (TokenServer) isn't rewritten.
         # Brave's ad/tracker/sync features both pollute the fingerprint and
         # sometimes break Turnstile's iframe; disable them when running Brave.

fleet_framework-0.1.2/fleet_browser/cloak.py

@@ -0,0 +1,120 @@
+"""Cloak engine integration — uses the CloakBrowser patched Chromium binary.
+
+CloakBrowser is a separately-licensed binary (free for own-business use,
+OEM license required for browser-as-a-service distribution). See:
+  https://github.com/CloakHQ/CloakBrowser
+
+The wrapper Python package is MIT-licensed and pulled in via the optional
+extra: `pip install fleet-framework[cloak]`. The binary is downloaded on
+first use to ~/.cloakbrowser/ (override with CLOAKBROWSER_CACHE_DIR).
+
+Combining cloak (source-level canvas/WebGL/audio/font/WebRTC patches) with
+FingerprintStealth (CDP-level UA + Sec-CH-UA + navigator overrides) gives:
+  - Deep, JS-undetectable spoofing of low-level signals (cloak)
+  - Per-launch diversity of UA versions from the uaforge corpus (FingerprintStealth)
+
+That diversity matters: cloak's binary patches use the latest Chrome only,
+so without the CDP layer every harvest looks like the same Chrome version.
+With CDP override on top, each launch picks a different version from uaforge
+while keeping the renderer-level fingerprint coherent.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import random
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+_CLOAK_AVAILABLE: Optional[bool] = None
+
+
+def cloak_available() -> bool:
+    """Return True if the cloakbrowser wrapper package is importable.
+
+    The binary may still need to be downloaded — that's `ensure_cloak_binary`'s
+    job. This is just the cheap import probe.
+    """
+    global _CLOAK_AVAILABLE
+    if _CLOAK_AVAILABLE is None:
+        try:
+            import cloakbrowser  # noqa: F401
+            _CLOAK_AVAILABLE = True
+        except ImportError:
+            _CLOAK_AVAILABLE = False
+    return _CLOAK_AVAILABLE
+
+
+def resolve_engine(name: str) -> str:
+    """Resolve `engine="auto"` to `"cloak"` if available, else `"chrome"`."""
+    if name != "auto":
+        return name
+    return "cloak" if cloak_available() else "chrome"
+
+
+def ensure_cloak_binary(cache_dir: Optional[str] = None) -> str:
+    """Return path to the patched Chromium binary; download if missing.
+
+    Delegates to cloakbrowser.download.ensure_binary. ~250-400 MB download
+    on first use; cached at ~/.cloakbrowser/ (or `cache_dir`) thereafter.
+    Cloakbrowser checks for updates hourly when launched.
+    """
+    if not cloak_available():
+        raise RuntimeError(
+            "engine='cloak' requires cloakbrowser. "
+            "Install with: pip install fleet-framework[cloak]"
+        )
+    if cache_dir:
+        os.environ.setdefault("CLOAKBROWSER_CACHE_DIR", str(Path(cache_dir).expanduser()))
+    from cloakbrowser.download import ensure_binary
+    path = ensure_binary()
+    return str(path)
+
+
+def cloak_stealth_args(
+    *,
+    platform: str = "windows",
+    timezone: Optional[str] = None,
+    webrtc_ip: Optional[str] = None,
+    seed: Optional[int] = None,
+) -> tuple[str, ...]:
+    """Return Chromium command-line flags that activate cloak's source patches.
+
+    The `seed` drives canvas/WebGL/audio noise variation per-launch. Pass a
+    stable seed if you need reproducibility (e.g. testing). `platform` should
+    match what FingerprintStealth's UA claims — keep them aligned (default
+    'windows' matches uaforge's Windows corpus).
+    """
+    s = seed if seed is not None else random.randint(10000, 99999)
+    args = [
+        f"--fingerprint={s}",
+        f"--fingerprint-platform={platform}",
+    ]
+    if timezone:
+        args.append(f"--fingerprint-timezone={timezone}")
+    if webrtc_ip:
+        args.append(f"--fingerprint-webrtc-ip={webrtc_ip}")
+    return tuple(args)
+
+
+CLOAK_IGNORE_DEFAULT_ARGS: tuple[str, ...] = (
+    "--enable-automation",
+    "--enable-unsafe-swiftshader",
+)
+"""Default args Playwright/DrissionPage pass that leak automation signals.
+
+`--enable-automation` exposes `navigator.webdriver=true`. `--enable-unsafe-
+swiftshader` forces SwiftShader's distinctive WebGL renderer string. We pass
+these to Chromium's launch options so DrissionPage stops setting them."""
+
+
+__all__ = [
+    "CLOAK_IGNORE_DEFAULT_ARGS",
+    "cloak_available",
+    "cloak_stealth_args",
+    "ensure_cloak_binary",
+    "resolve_engine",
+]

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/fleet_browser/fingerprint.py

@@ -180,7 +180,12 @@ class FingerprintFactory:
                 "pip install git+https://github.com/sarperavci/uaforge.git"
             )
         if allowed_os is None:
-            allowed_os = (_detect_host_os(),)
+            # Default to Windows regardless of host. The host's actual OS
+            # is irrelevant — what matters is which UA + client-hint corpus
+            # the fleet's fingerprints are drawn from. Windows is the highest-
+            # entropy population (~70% of real browsing traffic) and matches
+            # the cloak engine's `--fingerprint-platform=windows` default.
+            allowed_os = ("windows",)
         self._gen = UserAgentGenerator(seed=seed)
         self._rng = random.Random(seed)
         self._min_chromium = min_chromium_version

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/fleet_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleet-framework
-Version: 0.1.1
+Version: 0.1.2
 Summary: generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)
 Author: Sarper Avci
 License: MIT
@@ -23,6 +23,9 @@ Requires-Dist: DrissionPage>=4.1.0; extra == "browser"
 Requires-Dist: cryptography>=42.0.0; extra == "browser"
 Provides-Extra: cloudflare
 Requires-Dist: fleet-framework[browser]; extra == "cloudflare"
+Provides-Extra: cloak
+Requires-Dist: fleet-framework[browser]; extra == "cloak"
+Requires-Dist: cloakbrowser>=0.3; extra == "cloak"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
@@ -31,7 +34,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Provides-Extra: all
-Requires-Dist: fleet-framework[browser,cloudflare,otel]; extra == "all"
+Requires-Dist: fleet-framework[browser,cloak,cloudflare,otel]; extra == "all"
 Dynamic: license-file
 
 # Fleet

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/fleet_framework.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ fleet/worker/ws_client.py
 fleet_browser/__init__.py
 fleet_browser/browser.py
 fleet_browser/cert.py
+fleet_browser/cloak.py
 fleet_browser/fingerprint.py
 fleet_browser/humanizer.py
 fleet_browser/pool.py

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/fleet_framework.egg-info/requires.txt

@@ -9,12 +9,16 @@ psutil>=5.9.0
 click>=8.1.0
 
 [all]
-fleet-framework[browser,cloudflare,otel]
+fleet-framework[browser,cloak,cloudflare,otel]
 
 [browser]
 DrissionPage>=4.1.0
 cryptography>=42.0.0
 
+[cloak]
+fleet-framework[browser]
+cloakbrowser>=0.3
+
 [cloudflare]
 fleet-framework[browser]
 

{fleet_framework-0.1.1 → fleet_framework-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fleet-framework"
-version = "0.1.1"
+version = "0.1.2"
 description = "generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,10 @@ browser = [
 cloudflare = [
     "fleet-framework[browser]",
 ]
+cloak = [
+    "fleet-framework[browser]",
+    "cloakbrowser>=0.3",
+]
 otel = [
     "opentelemetry-api>=1.27.0",
     "opentelemetry-sdk>=1.27.0",
@@ -40,7 +44,7 @@ test = [
     "pytest-asyncio>=0.23",
 ]
 all = [
-    "fleet-framework[browser,cloudflare,otel]",
+    "fleet-framework[browser,cloudflare,cloak,otel]",
 ]
 
 [project.scripts]