repository·main·Indexed 42 days ago
https://github.com/cloverlabsai/camoufoxAn open-source, stealth-optimized Firefox fork designed for AI agents and LLM-driven automation. It focuses on being undetectable and efficient for web scraping and agentic workflows, featuring a Python package for browser management and a build tester to validate binaries against antibot-detection checks.
Camoufox provides several layers of stealth and optimization:
Accept-Languages, User-Agent) match navigator properties.window.__playwright__binding__ or frame execution context leaks.navigator.webdriver and Firefox headless detection. Uses human-like cursor movement.addons property (list of paths). Includes uBlock Origin with custom privacy filters.Per-context patches control what JavaScript APIs report, but they cannot change how the underlying OS renders content. Because certain detection vectors operate below the browser layer, they will leak the real OS identity.
Key detection vectors that cannot be spoofed include:
canvas.measureText() and toDataURL() hashes.offsetWidth) and visual appearance between macOS overlay scrollbars and Windows/Linux scrollbars.prefers-color-scheme, AccentColor, and system colors.getShaderPrecisionFormat() returns driver-specific values tied to the OS + GPU combination.Best Practice: To avoid detection by advanced services (reCAPTCHA, hCaptcha, Kasada, etc.), always run Camoufox on the OS that matches the fingerprint profile. Use macOS fingerprints on macOS workers and Linux fingerprints on Linux workers. Per-context patches are intended to make each context look like a different person on the same OS, not to impersonate a different OS.
Camoufox uses a thread-safe C++ key-value store called RoverfoxStorageManager to manage fingerprinting overrides. Storage is keyed by userContextId, which is derived from Firefox's container identity system. This ensures that fingerprinting values (like timezone or canvas noise) are isolated to specific Playwright contexts.
When window.setXxx() is called on a page:
userContextId is resolved from the window's BrowsingContext.nsTHashMap cache.roverfox.s. prefix.audio, canvas, navigator, timezone, webgl) also store values under ucid=0 as a global fallback for workers that cannot resolve a specific userContextId.To ensure high performance and availability across processes, reads follow this hierarchy:
nsTHashMap (fastest).SendRoverfoxStorageGet) is made to the parent process. This only runs on the main thread.Camoufox utilizes specific patch files to modify Playwright's behavior. These patches are applied to the Firefox engine to enable Camoufox's specialized fingerprinting and anti-detection capabilities.
0-playwright.patch: Contains the upstream patches from Playwright. This file is intended to stay synchronized with the official Playwright Firefox bootstrap patches. If the upstream version diverges significantly, Camoufox may branch off.0-leak-fixes.patch: This patch is applied after the upstream patches to undo specific modifications from 0-playwright.patch that might cause fingerprinting leaks or undesirable side effects.JSONvv provides advanced logic for complex validation:
|): Allows a value to match one of several types. Example: "str | nil" (optional string) or "@traveling | @other" (choice between two custom type definitions).-): Excludes certain types or patterns from a definition. Example: "array[str] - str[/sudo/]`` (an array of strings that must not match the 'sudo' regex) or "str - str[Traveling]`# Union type
"theme": "str[light, dark] | nil"
# Subtracting a pattern from an array of strings
"allowed_commands": "array[str[/^//] - str[/sudo/]]"
# Subtracting a type from a string
"name": "str - str[Traveling]"The Camoufox Python library generates fingerprints through two main paths. The source of the fingerprint depends on which class you instantiate.
| Path | Default Source | Opt-in Alternative |
|---|---|---|
NewBrowser (launch_options()) | BrowserForge synthetic | fingerprint_preset=True or a preset dict |
NewContext (generate_context_fingerprint()) | BrowserForge synthetic | preset=dict explicitly |
webgl_data.db using OS-weighted probability. BrowserForge does not generate WebGL; both paths call sample_webgl() if values are missing._generate_random_font_subset() (30-78% of OS fonts, including essential/marker fonts)._generate_random_voice_subset() (40-80% of OS voices; macOS includes ~184, Windows includes all, Linux is empty).Intl.DateTimeFormat fallback.window.setWebRTCIPv4().You can define reusable type definitions using the @ symbol. This helps reduce duplication in complex validators.
"@typeName": "type_definition""key": "@typeName"validator = {
"@positiveInt": "int[>0]",
"userId": "@positiveInt",
"score": "@positiveInt"
}The Build Tester runs 8 profiles in two distinct phases to ensure fingerprint integrity:
addInitScript. This tests that fingerprints are unique and do not leak between contexts.CAMOU_CONFIG environment variable for fingerprint configuration. This tests browser-level fingerprint injection.Each profile is scored across several categories, including Automation Detection, JS Engine signals, Lie Detection (inconsistent property overrides), CSS/Canvas/WebGL/Audio fingerprinting, and WebRTC IP spoofing.
Camoufox bundles OS-specific fontconfig configurations and font files to ensure consistent font rendering and detection across different host systems. This prevents host OS leakage (e.g., a Linux font appearing in a macOS profile).
Helvetica, Menlo, PingFang, etc.Arimo, Cousine, Tinos, etc.Arial, Consolas, Segoe UI, etc.sans-serif, serif, monospace, etc., to OS-appropriate defaults.createRuntimeFontconfig() rewrites font directory paths to absolute paths pointing to the correct OS-specific subdirectory.When launching Camoufox on Linux, the FONTCONFIG_PATH environment variable must be set to point to the correct OS-specific fontconfig directory (e.g., camoufox/fontconfig/macos/).
To prevent fingerprinting scripts from detecting that overrides have been applied, every window.setXxx() function employs a dual self-destruct mechanism:
JS_DeleteProperty: Immediately removes the function from the current window object after it is called.DisableFunction: Marks the function as disabled in storage, ensuring it does not reappear on future pages within the same context.This ensures that once a value is set, the setter function itself becomes invisible to the environment.
Camoufox uses a patch-based system to inject fingerprint spoofing and Playwright support into Firefox.
All patches reside in the patches/ directory:
0-playwright.patch and 1-leak-fixes.patch.webrtc-ip-spoofing.patch or anti-font-fingerprinting.patch.Note: As of Firefox 146, per-user-context support is built directly into the base patches. There are no longer separate .context.patch files.
FontSpacingSeedManager and WebRTCIPManager that handle specific spoofing logic.