Skip to content

Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.

11.5 KB
Raw Blame
"""Platform-specific utility functions for browser automation."""

import ctypes
import os
import platform
import shutil
import sys
from typing import List, Optional

BROWSER_EXECUTABLE_ENV = "STEALTH_BROWSER_EXECUTABLE"
DISABLE_FEATURES_PREFIX = "--disable-features="
NODRIVER_DISABLED_FEATURES = ("IsolateOrigins", "site-per-process")
MACOS_DISABLED_FEATURES = ("MacAppCodeSignClone",)


def is_running_as_root() -> bool:
    """
    Check if the current process is running with elevated privileges.
    
    Returns:
        bool: True if running as root (Linux/macOS) or administrator (Windows)
    """
    system = platform.system().lower()
    
    if system in ('linux', 'darwin'):  # Linux or macOS
        try:
            return os.getuid() == 0
        except AttributeError:
            return False
    elif system == 'windows':
        try:
            return ctypes.windll.shell32.IsUserAnAdmin() != 0
        except (AttributeError, OSError):
            return False
    else:
        return False


def is_running_in_container() -> bool:
    """
    Check if the process is running inside a container (Docker, etc.).
    
    Returns:
        bool: True if likely running in a container
    """
    def _check_cgroup_for_docker() -> bool:
        """
        Check /proc/1/cgroup for docker indicators.

        Returns:
            bool: True if docker indicator found in cgroup file.
        """
        try:
            if not os.path.exists('/proc/1/cgroup'):
                return False
            with open('/proc/1/cgroup', 'r') as f:
                return 'docker' in f.read()
        except (OSError, PermissionError):
            return False

    container_indicators = [
        os.path.exists('/.dockerenv'),
        _check_cgroup_for_docker(),
        os.environ.get('container') is not None,
        os.environ.get('KUBERNETES_SERVICE_HOST') is not None,
    ]

    return any(container_indicators)


def sandbox_must_be_disabled() -> bool:
    """
    Check whether Chrome can only start without its sandbox here.

    Only Linux needs this, when running as root or inside a container.
    Chrome on Windows runs sandboxed under an administrator account, and
    every extra sandbox flag shows an "unsupported command-line flag" bar
    in headed windows, so other platforms keep the sandbox.

    Returns:
        bool: True on Linux as root or in a container
    """
    if platform.system().lower() != 'linux':
        return False
    return is_running_as_root() or is_running_in_container()


def get_required_sandbox_args() -> List[str]:
    """
    Get the browser arguments the current environment requires.

    Only --no-sandbox is added, and only where Chrome cannot start otherwise.
    Flags such as --disable-setuid-sandbox, --single-process, and
    --disable-gpu are left out: they show warning bars, crash tabs, or remove
    WebGL, which makes the browser easier to fingerprint.

    Returns:
        List[str]: List of browser arguments needed for current environment
    """
    return ['--no-sandbox'] if sandbox_must_be_disabled() else []


def get_required_disabled_features() -> List[str]:
    """
    Get Chrome features that must be turned off on the current platform.

    On macOS, Chrome copies its whole app bundle into a code_sign_clone
    directory at every launch and only deletes it on a clean exit, so crashed
    or killed automation instances leave a copy behind each time. Turning off
    MacAppCodeSignClone stops the copies, as Chrome for Testing already does.

    Returns:
        List[str]: Feature names to pass to --disable-features.
    """
    return list(MACOS_DISABLED_FEATURES) if platform.system() == "Darwin" else []


def merge_disabled_features(args: List[str], features: List[str]) -> List[str]:
    """
    Fold every --disable-features value and the given features into one switch.

    nodriver always passes its own --disable-features before ours, so the
    merged switch repeats its defaults. The result is the same whether Chrome
    keeps the last switch or combines them.

    Args:
        args (List[str]): Browser arguments.
        features (List[str]): Feature names that must be disabled.

    Returns:
        List[str]: Arguments with a single combined --disable-features switch,
        or the original arguments when there is nothing to add.
    """
    if not features:
        return list(args)
    names = list(NODRIVER_DISABLED_FEATURES)
    remaining = []
    for arg in args:
        if arg.startswith(DISABLE_FEATURES_PREFIX):
            names.extend(name.strip() for name in arg[len(DISABLE_FEATURES_PREFIX):].split(","))
        else:
            remaining.append(arg)
    names.extend(features)
    unique = [name for name in dict.fromkeys(names) if name]
    return remaining + [DISABLE_FEATURES_PREFIX + ",".join(unique)]


def merge_browser_args(user_args: Optional[List[str]] = None) -> List[str]:
    """
    Merge user-provided browser arguments with platform-specific required arguments.

    Args:
        user_args: User-provided browser arguments

    Returns:
        List[str]: Combined list of browser arguments
    """
    user_args = user_args or []
    required_args = get_required_sandbox_args()

    combined_args = list(user_args)

    for arg in required_args:
        if arg not in combined_args:
            combined_args.append(arg)

    return merge_disabled_features(combined_args, get_required_disabled_features())


def get_platform_info() -> dict:
    """
    Get comprehensive platform information for debugging.
    
    Returns:
        dict: Platform information including OS, architecture, privileges, etc.
    """
    return {
        'system': platform.system(),
        'release': platform.release(),
        'version': platform.version(),
        'machine': platform.machine(),
        'processor': platform.processor(),
        'architecture': platform.architecture(),
        'python_version': sys.version,
        'is_root': is_running_as_root(),
        'is_container': is_running_in_container(),
        'required_sandbox_args': get_required_sandbox_args(),
        'user_id': getattr(os, 'getuid', lambda: 'N/A')(),
        'effective_user_id': getattr(os, 'geteuid', lambda: 'N/A')(),
        'environment_vars': {
            'DISPLAY': os.environ.get('DISPLAY'),
            'container': os.environ.get('container'),
            'KUBERNETES_SERVICE_HOST': os.environ.get('KUBERNETES_SERVICE_HOST'),
            'USER': os.environ.get('USER'),
            'USERNAME': os.environ.get('USERNAME'),
        }
    }


def check_browser_executable() -> Optional[str]:
    """
    Find a compatible browser executable on the system.
    Uses STEALTH_BROWSER_EXECUTABLE when set, otherwise searches for Chrome,
    Chromium, and Microsoft Edge in order of preference.

    Returns:
        Optional[str]: Path to browser executable or None if not found
    """
    override = os.environ.get(BROWSER_EXECUTABLE_ENV, "").strip()
    if override:
        if os.path.isfile(override) and os.access(override, os.X_OK):
            return override
        return None

    system = platform.system().lower()

    if system == 'windows':
        possible_paths = [
            # Chrome paths
            r'C:\Program Files\Google\Chrome\Application\chrome.exe',
            r'C:\Program Files (x86)\Google\Chrome\Application\chrome.exe',
            r'C:\Users\{}\AppData\Local\Google\Chrome\Application\chrome.exe'.format(os.environ.get('USERNAME', '')),
            # Chromium paths
            r'C:\Program Files\Chromium\Application\chromium.exe',
            # Microsoft Edge paths
            r'C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe',
            r'C:\Program Files\Microsoft\Edge\Application\msedge.exe',
            r'C:\Users\{}\AppData\Local\Microsoft\Edge\Application\msedge.exe'.format(os.environ.get('USERNAME', '')),
        ]
    elif system == 'darwin':
        possible_paths = [
            # Chrome paths
            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
            # Chromium paths
            '/Applications/Chromium.app/Contents/MacOS/Chromium',
            # Microsoft Edge paths
            '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
        ]
    else:
        possible_paths = [
            # Chrome paths
            '/usr/bin/google-chrome',
            '/usr/bin/google-chrome-stable',
            # Chromium paths
            '/usr/bin/chromium',
            '/usr/bin/chromium-browser',
            '/snap/bin/chromium',
            '/usr/local/bin/chrome',
            # Microsoft Edge paths
            '/usr/bin/microsoft-edge-stable',
            '/usr/bin/microsoft-edge',
            '/usr/bin/microsoft-edge-beta',
            '/usr/bin/microsoft-edge-dev',
            '/snap/bin/microsoft-edge',
            '/opt/microsoft/msedge/msedge',
        ]
    
    # First check static paths
    for path in possible_paths:
        try:
            if os.path.isfile(path) and os.access(path, os.X_OK):
                return path
        except (OSError, PermissionError):
            # Handle potential permission issues on certain systems
            continue
    
    # Fallback: search using 'which' command
    browser_names = [
        'google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome',
        'microsoft-edge-stable', 'microsoft-edge', 'msedge'
    ]
    for name in browser_names:
        try:
            found_path = shutil.which(name)
            if found_path and os.path.isfile(found_path) and os.access(found_path, os.X_OK):
                return found_path
        except Exception:
            continue
    
    return None


def validate_browser_environment() -> dict:
    """
    Validate the browser environment and return status information.
    Checks for Chrome, Chromium, and Microsoft Edge availability.
    
    Returns:
        dict: Environment validation results
    """
    browser_path = check_browser_executable()
    platform_info = get_platform_info()
    
    issues = []
    warnings = []
    recommendations = []
    
    if not browser_path:
        issues.append("Compatible browser executable not found (Chrome, Chromium, or Microsoft Edge)")
        recommendations.append("Install a compatible browser (Chrome, Chromium, or Microsoft Edge)")
    else:
        # Identify which browser was found
        browser_type = "Unknown"
        if 'chrome' in browser_path.lower():
            browser_type = "Google Chrome"
        elif 'chromium' in browser_path.lower():
            browser_type = "Chromium"
        elif 'edge' in browser_path.lower() or 'msedge' in browser_path.lower():
            browser_type = "Microsoft Edge"
            
        # Add Edge-specific warnings if applicable
        if browser_type == "Microsoft Edge" and platform_info['system'] == 'Linux':
            warnings.append("Microsoft Edge on Linux detected - ensure all dependencies are installed")
    
    if platform_info['is_root']:
        warnings.append("Running as root/administrator - sandbox will be disabled")
    
    if platform_info['is_container']:
        warnings.append("Running in container - additional arguments will be added")
    
    if platform_info['system'] not in ['Windows', 'Linux', 'Darwin']:
        warnings.append(f"Untested platform: {platform_info['system']}")
    
    return {
        'browser_executable': browser_path,
        'browser_type': browser_type if browser_path else None,
        'platform_info': platform_info,
        'issues': issues,
        'warnings': warnings,
        'recommendations': recommendations,
        'is_ready': len(issues) == 0,
        'recommended_args': get_required_sandbox_args(),
    }