Browser Context & Fingerprinting
Relevant source files
The following files were used as context for generating this wiki page:
The Browser Context and Fingerprinting system is responsible for creating realistic, anti-detect browser environments for automation tasks. By combining unique digital fingerprints, proxy configurations, and session persistence, the system allows the bot to mimic human-like browsing behavior on platforms like Instagram.
The primary goal of this module is to mitigate detection by generating a complete browser "persona" using a fingerprint seed and OS-specific parameters. This context is then injected into a browser instance (typically Camoufox/Firefox) to ensure that automated requests appear legitimate to target platform security measures.
Digital Fingerprinting
The project utilizes browserforge to generate detailed browser fingerprints. These fingerprints cover various hardware and software attributes, including screen resolution, hardware concurrency, and WebGL information. Fingerprints are generated specifically for Firefox, as the underlying automation driver is Firefox-based.
Sources: python/browser/fingerprint.py:7-55, python/browser/fingerprint.py:122-125
Fingerprint Components
Each generated fingerprint includes several sub-structures that define the browser's identity:
| Component | Description | Example Data |
|---|---|---|
| Screen | Physical and available display dimensions. | width: 1920, height: 1080, colorDepth: 24 |
| Navigator | Browser identity and hardware specs. | userAgent, platform, hardwareConcurrency |
| VideoCard | GPU vendor and renderer details for WebGL. | vendor, renderer |
| Network | WebRTC behavior and headers. | mockWebRTC: True, accept-language |
Sources: python/browser/fingerprint.py:61-110
Generation Logic
The generate_fingerprint function maps simplified OS names to target platforms and applies screen constraints (min width 1280px, max 1920px). It also enables WebRTC mocking to prevent IP leaks that could bypass proxy settings.
Sources: python/browser/fingerprint.py:16-55
Browser Context Lifecycle
The automation runner manages the browser lifecycle through specific workflow activities. The start_browser activity initializes the context using stored profile data, including the fingerprint seed and proxy string.
Sources: python/runners/workflow/activity_dispatch.py:86-105
Context Initialization Flow
When a workflow starts, or when a browser activity is reached without an active page, the system ensures a context exists.
Session Management
Browser sessions are persisted via cookies. The cookies_json field stores authentication tokens like sessionid and csrftoken. These are injected into the browser context upon startup or used directly in fetch calls within the browser environment.
Sources: python/runners/workflow/scrape_script.py:7-22, tests/convex/http.test.ts:46-56
Profile Configuration
The system stores browser environments as "Profiles." Each profile maintains its own network settings and digital identity parameters.
Network and Proxy Settings
Profiles can use direct connections or proxies. Supported proxy types include HTTP and SOCKS5. Users can toggle "IP Check" to verify the proxy's location before starting automation tasks.
Sources: frontend/src/features/profiles/components/ProfileDetails.tsx:90-105, tests/convex/http.test.ts:68-80
Fingerprint Settings in UI
The frontend allows users to configure the fingerprint_seed and fingerprint_os. Modifying these settings is flagged as a high-risk action, as it may trigger re-authentication or verification on target platforms due to the change in digital identity.
Sources: frontend/src/features/profiles/components/ProfileDetails.tsx:112-135, tests/convex/http.test.ts:98-104
Execution Environment
Once the browser context is established, JavaScript-based "scrape scripts" are injected. These scripts inherit the browser's context, including the spoofed headers and cookies.
Script Injection Logic
The RELATIONSHIP_CHUNK_SCRIPT utilizes the browser's document.cookie to extract CSRF tokens and performs authenticated fetch requests to Instagram's internal APIs.
| Header | Source/Value |
|---|---|
x-ig-app-id | 936619743392459 |
x-csrftoken | Extracted from csrftoken cookie |
referer | Dynamic based on target username and kind |
Sources: python/runners/workflow/scrape_script.py:1-20, python/runners/workflow/scrape_script.py:120-123
Browser State Persistence
The runner maintains a browser_state dictionary which tracks the active page, context, and the underlying context manager (_ctx_mgr). This allows for clean resource disposal during the close_browser activity.
Sources: python/runners/workflow/activity_dispatch.py:108-115
Summary
The Browser Context & Fingerprinting system provides the foundation for stealthy automation. By abstracting complex fingerprinting logic through browserforge and managing the lifecycle of browser contexts via Profile metadata, the system ensures that each bot instance operates within a unique, persistent, and platform-compliant environment. Proper configuration of fingerprint seeds and proxies is critical to maintaining the longevity of automated accounts.
Sources: python/browser/fingerprint.py:1-15, frontend/src/features/profiles/components/ProfileDetails.tsx:150-160