botmask 0.1.0__tar.gz

botmask-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: botmask
+Version: 0.1.0
+Summary: Containerized human-behavior browser automation toolkit (Brave + Patchright)
+Requires-Python: >=3.10
+Requires-Dist: patchright
+Requires-Dist: python-dotenv
+Requires-Dist: browserforge
+Requires-Dist: PyAutoGUI
+Provides-Extra: dev

botmask-0.1.0/README.md

@@ -0,0 +1,86 @@
+# botmask
+
+> Containerized human-behavior browser automation toolkit. Installable as a plugin in other projects that need browser automation while evading anti-bot systems.
+
+## What is this?
+
+A reusable, containerized browser-automation kit that simulates realistic human behavior
+(Bezier-curve mouse movement, inertia scrolling, natural delays, typo typing, warm-up
+sessions, reading simulation, auth-barrier detection) on top of **Brave Browser + Patchright**.
+
+Extracted from the `career-ops` pipeline (`~/Proyectos/ai/jobs`) into an isolated, installable
+package so it can be dropped into any project that needs stealthy browser interaction.
+
+## Stack
+
+| Layer | Tool |
+| --- | --- |
+| Runtime | Docker / Docker Compose |
+| Browser | **Brave** (Chromium; ad-blocking, anti-fingerprinting) |
+| Automation | **Patchright** (undetectable Playwright fork, CDP) |
+| Human behavior | `human_behavior` module (this project) |
+| Config | `config` module, env-driven (inherited from `jobs`) |
+| Hardening | BrowserForge headers (planned), OS-level input fallback (planned) |
+
+**Decision (Phase 0, `docs/decision.md`): Brave only.** Firefox engines (camoufox,
+invisible_playwright) were evaluated and discarded. Hard targets are handled with
+OS-level input (Xvfb + xdotool/PyAutoGUI) + graceful challenge detection.
+
+## How the AI knows where to click
+
+See **`docs/interaction-model.md`**. Short version: the AI picks elements from a numbered
+accessibility tree (never pixel coordinates); the script resolves element → bounding box →
+humanized mouse path. OS-level input maps viewport → screen coords via a one-time window
+offset calibration.
+
+## Container usage
+
+### Local (real display, like `jobs`) — `develop` target
+
+Shares the host display into the container (Wayland socket + X11). `compose.yaml`
+builds the `develop` stage (no virtual display stack).
+
+```bash
+cp .env.example .env   # adjust DISPLAY, WAYLAND_DISPLAY for your host
+docker compose up -d --build
+```
+
+Volumes: `.:/app`, `/tmp/.X11-unix`, `/run/user/<UID>/wayland-0`. CDP exposed at `:9222`.
+
+### Server (no monitor) — Xvfb + noVNC — `deploy` target
+
+The server override lives in **`.gitlab/compose.yaml`**; a future GitLab CI step copies it
+to `compose.override.yaml` (which Docker Compose auto-loads), then:
+
+```bash
+docker compose up -d --build   # target=deploy via the override
+```
+
+Runs Brave headful on an Xvfb virtual display; watch it at `http://<host>:6080` (noVNC) or
+VNC at `:5900`. Same element→box→input logic — only the display source differs.
+
+`start.sh` auto-detects the mode from the environment: with `DISPLAY`/`WAYLAND_DISPLAY`
+present it runs the browser directly; with none (or `VIRTUAL_DISPLAY=true`) it boots the
+Xvfb stack first. On every start it also provisions Python packages + browser binaries at
+runtime (`pip install .` + `patchright install chromium`), cached in the `cache` volume
+(`/root/.cache` — pip wheels + browsers) so the image itself stays small.
+
+## Status
+
+- **Phase 0 — Evaluation: COMPLETE** → `docs/decision.md`
+- **Phase 1 — Package extraction & container scaffold: IN PROGRESS**
+  - `config.py` migrated ✅ · Dockerfile (develop/deploy) + compose + start.sh scaffolded ✅
+  - Fitts + overshoot mouse port ⏳ · `human_behavior.py` migration ⏳ (see `TODO.md`)
+
+## Docker targets (multistage)
+
+| Target | For | Display | Build |
+| --- | --- | --- | --- |
+| `develop` (default via compose.yaml) | local dev on host Wayland/X11 | host display | `docker build --target develop -t botmask:develop .` |
+| `deploy` (default target of plain `docker build`) | headless machine / CI | Xvfb + noVNC | `docker build --target deploy -t botmask:deploy .` |
+
+Base image is Debian `python:slim` — Brave requires glibc and cannot run on Alpine/musl.
+
+## Migrating from `jobs`
+
+What can and cannot be reused from the `jobs` project: `docs/migration-from-jobs.md`.

botmask-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "botmask"
+version = "0.1.0"
+description = "Containerized human-behavior browser automation toolkit (Brave + Patchright)"
+requires-python = ">=3.10"
+dependencies = [
+    "patchright",
+    "python-dotenv",
+    "browserforge",
+    "PyAutoGUI",
+]
+
+[project.optional-dependencies]
+dev = []
+
+[tool.setuptools.packages.find]
+where = ["src"]

botmask-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

botmask-0.1.0/src/botmask/__init__.py

@@ -0,0 +1 @@
+"""botmask — containerized human-behavior browser automation toolkit."""

botmask-0.1.0/src/botmask/_boot.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+botmask bootstrap — launch Brave with CDP exposed, hold until killed.
+
+Called by start.sh after deps are installed. Does NOT run pip install
+itself — that belongs in start.sh or the Dockerfile.
+"""
+import json
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+# Ensure package is importable when run directly
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "src"))
+
+
+def main():
+    from botmask.config import get_browser_config, get_browser_args
+
+    cfg = get_browser_config()
+    args = get_browser_args()
+
+    # Ensure user data dir exists
+    data_dir = Path(cfg["user_data_dir"])
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    # Remove stale lock files from previous unclean shutdowns
+    for lock in ("SingletonLock", "SingletonCookie", "SingletonSocket"):
+        (data_dir / lock).unlink(missing_ok=True)
+
+    # Disable P3A telemetry in the profile's Local State
+    local_state = data_dir / "Local State"
+    if local_state.exists():
+        try:
+            state = json.loads(local_state.read_text())
+        except (json.JSONDecodeError, OSError):
+            state = {}
+    else:
+        state = {}
+    state.setdefault("brave", {})
+    state["brave"].setdefault("p3a", {})["enabled"] = False
+    state["brave"].setdefault("stats", {})["reporting_enabled"] = False
+    local_state.write_text(json.dumps(state))
+
+    cdp_port = os.getenv("BROWSER_CDP_PORT", "9222")
+    cdp_host = os.getenv("BROWSER_CDP_HOST", "0.0.0.0")
+
+    cmd = [cfg["executable_path"]] + args + [
+        f"--remote-debugging-port={cdp_port}",
+        f"--remote-debugging-address={cdp_host}",
+        f"--user-data-dir={cfg['user_data_dir']}",
+    ]
+
+    proc = subprocess.Popen(cmd)
+    print(f"[botmask] Brave launched (pid={proc.pid}), CDP on {cdp_host}:{cdp_port}",
+          flush=True)
+
+    # Forward signals to Brave so docker stop works cleanly
+    signal.signal(signal.SIGTERM, lambda *_: proc.terminate())
+    signal.signal(signal.SIGINT, lambda *_: proc.terminate())
+
+    try:
+        sys.exit(proc.wait())
+    except KeyboardInterrupt:
+        proc.terminate()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

botmask-0.1.0/src/botmask/a11y.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Accessibility Snapshot Module — numbered interactive elements for AI targeting.
+
+The AI never computes pixel coordinates. It picks an element by index from a
+numbered snapshot; this module resolves index -> locator -> bounding_box.
+
+Usage:
+    from botmask.a11y import snapshot_interactives, get_locator
+
+    items = snapshot_interactives(page)   # [{"index": 0, "tag": "a", ...}, ...]
+    locator = get_locator(page, 42)       # -> page.locator(...).nth(42)
+"""
+
+from typing import Dict, List, Optional
+
+from patchright.sync_api import Locator, Page
+
+# Must match the JS in snapshot_interactives so index -> locator is stable.
+INTERACTIVE_SELECTOR = (
+    "a, button, input, select, textarea, summary, "
+    "[role=button], [role=link], [role=tab], [role=menuitem], "
+    "[contenteditable=true], [onclick], [data-testid]"
+)
+
+MAX_ITEMS = 300
+
+
+def snapshot_interactives(page: Page, limit: int = MAX_ITEMS) -> List[Dict]:
+    """Collect interactive elements in document order, numbered from 0.
+
+    Indices are positions in the full (unfiltered) INTERACTIVE_SELECTOR list,
+    so ``get_locator(page, index)`` always resolves to the same element even
+    after the page changes. Hidden elements are marked ``visible: false`` and
+    kept in the list only to preserve stable numbering.
+
+    Args:
+        page: The Playwright page.
+        limit: Maximum number of entries to return.
+
+    Returns:
+        List of dicts with index, tag, role, type, name, href, visible, box.
+    """
+    items = page.evaluate(
+        """(arg) => {
+            const sel = arg.sel;
+            const maxItems = arg.maxItems;
+            const els = Array.from(document.querySelectorAll(sel));
+            const isVisible = (el) => {
+                const r = el.getBoundingClientRect();
+                if (!r.width && !r.height) return false;
+                const s = getComputedStyle(el);
+                if (s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0') return false;
+                return true;
+            };
+            const name = (el) => {
+                let t = (el.getAttribute('aria-label')
+                    || el.value
+                    || el.placeholder
+                    || el.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 80);
+                return t;
+            };
+            const box = (el) => {
+                const r = el.getBoundingClientRect();
+                return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) };
+            };
+            const out = [];
+            for (let i = 0; i < els.length; i++) {
+                const el = els[i];
+                const b = box(el);
+                if (out.length >= maxItems) break;
+                out.push({
+                    index: i,
+                    tag: el.tagName.toLowerCase(),
+                    role: el.getAttribute('role') || '',
+                    type: el.getAttribute('type') || '',
+                    name: name(el),
+                    href: el.getAttribute('href') || '',
+                    visible: isVisible(el),
+                    box: b,
+                });
+            }
+            return out;
+        }""",
+        {"sel": INTERACTIVE_SELECTOR, "maxItems": limit},
+    )
+    return items
+
+
+def get_locator(page: Page, index: int) -> Locator:
+    """Resolve a snapshot index to a locator on the same INTERACTIVE_SELECTOR list."""
+    return page.locator(INTERACTIVE_SELECTOR).nth(index)
+
+
+def resolve_target(page: Page, index: int, require_visible: bool = True) -> Optional[Dict]:
+    """Resolve index to (locator, box). Returns None when the element is gone/hidden.
+
+    Args:
+        page: The Playwright page.
+        index: Snapshot index.
+        require_visible: Reject hidden elements (no bounding box).
+
+    Returns:
+        dict with "locator", "box" and "center", or None.
+    """
+    locator = get_locator(page, index)
+    box = locator.bounding_box()
+    if not box or (require_visible and (box["width"] == 0 or box["height"] == 0)):
+        return None
+    return {
+        "locator": locator,
+        "box": box,
+        "center": (box["x"] + box["width"] / 2, box["y"] + box["height"] / 2),
+    }