ghost-driver 0.1.0__py3-none-any.whl

ghost_driver/__init__.py

@@ -0,0 +1,5 @@
+from .browser import launch
+from .logging_utils import enable_logging
+
+__all__ = ["launch", "enable_logging"]
+__version__ = "0.1.0"

ghost_driver/browser.py

@@ -0,0 +1,49 @@
+import asyncio
+from typing import Sequence
+
+import nodriver as uc
+
+DEFAULT_BROWSER_ARGS = [
+    "--use-gl=swiftshader",
+    "--use-angle=swiftshader",
+]
+
+
+async def launch(
+    *,
+    headless: bool = False,
+    sandbox: bool = False,
+    browser_args: Sequence[str] | None = None,
+    max_attempts: int = 5,
+    retry_delay_s: float = 2.0,
+    **kwargs,
+) -> uc.Browser:
+    """Thin wrapper around nodriver.start() with this library's defaults
+    applied, plus a retry loop around the browser PROCESS launch itself
+    (Chrome under load -- containers, cold cache -- can fail to start
+    transiently; this is separate from nodriver's own CDP-handshake
+    connection-wait retry, which ghost_driver.patches extends).
+
+    --use-gl=swiftshader --use-angle=swiftshader default ON: under Xvfb,
+    WebGL was found completely ABSENT without these (getContext("webgl")
+    returned null outright -- not just a suspicious vendor/renderer
+    string, something no real consumer browser ever does).
+
+    Defaults to headless=False: ghost_driver.input.x11's real-X11-input
+    drag mechanism (this library's whole reason to exist) requires a real
+    mapped window, which --headless=new never creates. Pass a real
+    (virtual is fine, e.g. Xvfb) DISPLAY and a window manager alongside
+    it if you're running this outside an existing desktop session.
+    """
+    args = list(DEFAULT_BROWSER_ARGS)
+    if browser_args:
+        args.extend(browser_args)
+    last_error: Exception | None = None
+    for attempt in range(max_attempts):
+        try:
+            return await uc.start(headless=headless, sandbox=sandbox, browser_args=args, **kwargs)
+        except Exception as e:
+            last_error = e
+            if attempt + 1 < max_attempts:
+                await asyncio.sleep(retry_delay_s)
+    raise RuntimeError(f"could not launch browser after {max_attempts} attempts") from last_error

ghost_driver/cookies.py

@@ -0,0 +1,40 @@
+import time
+from datetime import datetime, timezone
+
+from nodriver import cdp
+
+
+def describe(cookies: list) -> list[str]:
+    """One human-readable line per cookie -- name, a truncated value,
+    domain, and remaining lifetime -- for a quick print() after a solve.
+    Takes the same list `Network.get_cookies()` (or NavigateResult.cookies)
+    returns."""
+    now = time.time()
+    lines = []
+    for c in cookies:
+        if c.session or c.expires is None or c.expires < 0:
+            lifetime = "SESSION (dies when browser closes)"
+        else:
+            remaining_h = (c.expires - now) / 3600.0
+            expires_iso = datetime.fromtimestamp(c.expires, tz=timezone.utc).isoformat()
+            lifetime = f"expires {expires_iso} (~{remaining_h:.1f}h from now)"
+        lines.append(f"{c.name}={c.value[:24]}... domain={c.domain} -- {lifetime}")
+    return lines
+
+
+def to_cookie_param(cookie: "cdp.network.Cookie") -> "cdp.network.CookieParam":
+    """Converts a cdp.network.Cookie (from Network.get_cookies()) into a
+    cdp.network.CookieParam (for Network.set_cookies()) -- these are
+    DIFFERENT types despite the overlapping fields. In particular
+    Cookie.expires is a plain float; CookieParam.expires needs it wrapped
+    in TimeSinceEpoch, which has the to_json() the CDP serializer calls --
+    a bare float doesn't, and fails with an unhelpful AttributeError deep
+    in serialization if passed straight through.
+    """
+    expires = cdp.network.TimeSinceEpoch(cookie.expires) if cookie.expires is not None else None
+    return cdp.network.CookieParam(
+        name=cookie.name, value=cookie.value, domain=cookie.domain, path=cookie.path,
+        secure=cookie.secure, http_only=cookie.http_only, same_site=cookie.same_site,
+        expires=expires, priority=cookie.priority, source_scheme=cookie.source_scheme,
+        source_port=cookie.source_port,
+    )

ghost_driver/diagnostics.py

@@ -0,0 +1,50 @@
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+
+def save_html(findings_dir: Path | str, label: str, html: str | None) -> str:
+    findings_dir = Path(findings_dir)
+    findings_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d_%H%M%S")
+    path = findings_dir / f"{ts}_{label}.html"
+    path.write_text(html or "", encoding="utf-8")
+    return str(path)
+
+
+def save_json(findings_dir: Path | str, label: str, payload: dict) -> str:
+    findings_dir = Path(findings_dir)
+    findings_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d_%H%M%S")
+    path = findings_dir / f"{ts}_{label}.json"
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return str(path)
+
+
+def short_url(url: str) -> str:
+    """Path + query KEYS only, values dropped -- some sites' flows carry
+    large opaque behavioral-telemetry blobs in query values (thousands of
+    chars each); printing full URLs to a live console makes every run
+    unreadable. Keep the full URL in saved JSON diagnostics (save_json)
+    for later analysis; use this only for human-readable log lines."""
+    parsed = urlparse(url)
+    keys = ",".join(parse_qs(parsed.query).keys())
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path}?{keys}" if keys else url
+
+
+async def dump(page, findings_dir: Path | str, label: str, extra: dict | None = None) -> str:
+    """Saves the live page's HTML plus whatever extra diagnostic payload
+    you pass, both timestamped consistently under one label so they're
+    easy to correlate on disk. Call this at every meaningful exit point of
+    an attempt, not just failures -- a "passed" that later turns out wrong
+    has nothing to inspect after the fact otherwise."""
+    try:
+        html = await page.evaluate("document.documentElement.outerHTML")
+    except Exception:
+        html = None
+    saved_html = save_html(findings_dir, f"{label}_html", html)
+    payload = {"label": label, "saved_html": saved_html}
+    if extra:
+        payload.update(extra)
+    return save_json(findings_dir, label, payload)

ghost_driver/examples/e_disclosure_rotate_captcha/recorded_trajectories/1787906284_passed_pct007p6_round2.json

@@ -0,0 +1,542 @@
+[
+  {
+    "t": 3277.9000000059605,
+    "type": "pointermove",
+    "x": 54,
+    "y": 719,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3278.2000000029802,
+    "type": "mousemove",
+    "x": 54,
+    "y": 719,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3285.6000000089407,
+    "type": "pointermove",
+    "x": 53,
+    "y": 711,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3285.800000011921,
+    "type": "mousemove",
+    "x": 53,
+    "y": 711,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3306.2000000029802,
+    "type": "pointermove",
+    "x": 53,
+    "y": 705,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3306.2000000029802,
+    "type": "mousemove",
+    "x": 53,
+    "y": 705,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3459.5,
+    "type": "pointermove",
+    "x": 70,
+    "y": 662,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3459.9000000059605,
+    "type": "mousemove",
+    "x": 70,
+    "y": 662,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3484.6000000089407,
+    "type": "pointermove",
+    "x": 71,
+    "y": 660,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3485.4000000059605,
+    "type": "mousemove",
+    "x": 71,
+    "y": 660,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3492.800000011921,
+    "type": "pointermove",
+    "x": 71,
+    "y": 659,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3493,
+    "type": "mousemove",
+    "x": 71,
+    "y": 659,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3506.800000011921,
+    "type": "pointermove",
+    "x": 71,
+    "y": 657,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3506.9000000059605,
+    "type": "mousemove",
+    "x": 71,
+    "y": 657,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3604.4000000059605,
+    "type": "pointermove",
+    "x": 72,
+    "y": 657,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3604.5,
+    "type": "mousemove",
+    "x": 72,
+    "y": 657,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3607.2000000029802,
+    "type": "pointermove",
+    "x": 72,
+    "y": 656,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3607.2000000029802,
+    "type": "mousemove",
+    "x": 72,
+    "y": 656,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3650.300000011921,
+    "type": "pointermove",
+    "x": 73,
+    "y": 656,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3650.800000011921,
+    "type": "mousemove",
+    "x": 73,
+    "y": 656,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3659.2000000029802,
+    "type": "pointermove",
+    "x": 73,
+    "y": 655,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3659.300000011921,
+    "type": "mousemove",
+    "x": 73,
+    "y": 655,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3679.800000011921,
+    "type": "pointermove",
+    "x": 75,
+    "y": 654,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3679.9000000059605,
+    "type": "mousemove",
+    "x": 75,
+    "y": 654,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3723.7000000029802,
+    "type": "pointermove",
+    "x": 76,
+    "y": 653,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3724,
+    "type": "mousemove",
+    "x": 76,
+    "y": 653,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3740,
+    "type": "pointermove",
+    "x": 77,
+    "y": 652,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3740.1000000089407,
+    "type": "mousemove",
+    "x": 77,
+    "y": 652,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3813.4000000059605,
+    "type": "pointermove",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3813.5,
+    "type": "mousemove",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3882.4000000059605,
+    "type": "pointermove",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3882.6000000089407,
+    "type": "mousemove",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3896.4000000059605,
+    "type": "pointerdown",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 3916.7000000029802,
+    "type": "mousedown",
+    "x": 77,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 4136.20000000298,
+    "type": "pointermove",
+    "x": 78,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0
+  },
+  {
+    "t": 4146.5,
+    "type": "mousemove",
+    "x": 78,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0.4444444444444444
+  },
+  {
+    "t": 4155.300000011921,
+    "type": "pointermove",
+    "x": 80,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 0.4444444444444444
+  },
+  {
+    "t": 4158.20000000298,
+    "type": "mousemove",
+    "x": 80,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 1.3333333333333335
+  },
+  {
+    "t": 4174.800000011921,
+    "type": "pointermove",
+    "x": 82,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 1.3333333333333335
+  },
+  {
+    "t": 4175.4000000059605,
+    "type": "mousemove",
+    "x": 82,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 2.2222222222222223
+  },
+  {
+    "t": 4205.5,
+    "type": "pointermove",
+    "x": 84,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 2.2222222222222223
+  },
+  {
+    "t": 4206.600000008941,
+    "type": "mousemove",
+    "x": 84,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 3.111111111111111
+  },
+  {
+    "t": 4238.300000011921,
+    "type": "pointermove",
+    "x": 86,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 3.111111111111111
+  },
+  {
+    "t": 4239.5,
+    "type": "mousemove",
+    "x": 86,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4
+  },
+  {
+    "t": 4306.300000011921,
+    "type": "pointermove",
+    "x": 87,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4
+  },
+  {
+    "t": 4307,
+    "type": "mousemove",
+    "x": 87,
+    "y": 651,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4.444444444444445
+  },
+  {
+    "t": 4387,
+    "type": "pointermove",
+    "x": 88,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4.444444444444445
+  },
+  {
+    "t": 4387.70000000298,
+    "type": "mousemove",
+    "x": 88,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4.888888888888889
+  },
+  {
+    "t": 4405.70000000298,
+    "type": "pointermove",
+    "x": 90,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 4.888888888888889
+  },
+  {
+    "t": 4406.300000011921,
+    "type": "mousemove",
+    "x": 90,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 5.777777777777778
+  },
+  {
+    "t": 4456.4000000059605,
+    "type": "pointermove",
+    "x": 91,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 5.777777777777778
+  },
+  {
+    "t": 4457.600000008941,
+    "type": "mousemove",
+    "x": 91,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 6.222222222222222
+  },
+  {
+    "t": 4491.20000000298,
+    "type": "pointermove",
+    "x": 92,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 6.222222222222222
+  },
+  {
+    "t": 4492.100000008941,
+    "type": "mousemove",
+    "x": 92,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 6.666666666666667
+  },
+  {
+    "t": 4505.600000008941,
+    "type": "pointermove",
+    "x": 93,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 6.666666666666667
+  },
+  {
+    "t": 4506.4000000059605,
+    "type": "mousemove",
+    "x": 93,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 7.111111111111111
+  },
+  {
+    "t": 4548.5,
+    "type": "pointermove",
+    "x": 94,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 7.111111111111111
+  },
+  {
+    "t": 4548.9000000059605,
+    "type": "mousemove",
+    "x": 94,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 7.555555555555555
+  },
+  {
+    "t": 4610.300000011921,
+    "type": "pointerup",
+    "x": 94,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 7.555555555555555
+  },
+  {
+    "t": 4645.4000000059605,
+    "type": "mouseup",
+    "x": 94,
+    "y": 650,
+    "controlLeft": 52,
+    "controlTop": 631,
+    "percent": 7.555555555555555
+  }
+]