Camoufox Stealth Browser

C++ level anti-bot browser automation using Camoufox (patched Firefox) in isolated containers. Bypasses Cloudflare Turnstile, Datadome, Airbnb, Yelp. Superior to Chrome-based solutions (undetected-chromedriver, puppeteer-stealth) which only patch at JS level. Use when standard Playwright/Selenium gets blocked.

Security Scan

The skill's scripts and instructions generally match a stealth-browser purpose, but there are multiple mismatches and high-risk install actions (downloading an unknown ~700MB browser build via a third‑party package, undeclared environment usage, and command-line handling of proxy credentials) that warrant caution before installing or running it.

Purpose & Capability

The name/description match the included Python scripts (camoufox-fetch, camoufox-session, curl-api) and the declared runtime dependency (distrobox) is consistent with containerized execution. However the skill relies on third‑party Python packages (camoufox, curl_cffi) that are not part of the registry metadata and that will pull a large compiled browser at first run — this is expected for the stated purpose but raises provenance concerns.

Instruction Scope

SKILL.md and scripts instruct the agent to run distrobox-enter with python3.14, pip install packages, run camoufox.install(), and use residential proxies; they also reference environment variables (HTTP_PROXY/HTTPS_PROXY) and recommend embedding proxy credentials (http://user:pass@host:port). The skill's declared requires.env is empty, so the instructions reference env/config and proxy credentials not declared in metadata. The scripts accept proxy credentials on the command line (risk: shell history leakage) and write session/profile data to ~/.stealth-browser — actions that extend beyond a purely ephemeral, read-only skill.

Install Mechanism

There is no registry install spec; instead setup.sh uses pip to install camoufox and curl_cffi inside the pybox container and then calls camoufox.install(), which the documentation says downloads a ~700MB Firefox fork. That is effectively a remote binary download from an external project (origin not declared here). Although execution is intended inside a container (reducing host exposure), downloading and running an opaque compiled browser package is higher-risk and the registry package provides no provenance or release URL to audit.

Credentials

requires.env is empty but the documentation and references recommend setting HTTP_PROXY/HTTPS_PROXY and the scripts accept proxy URLs containing username:password. The skill does not declare or request these credentials in metadata, creating a mismatch between what it asks you to configure and what the registry shows. Also, proxy credentials are passed in CLI strings (and could be recorded in shell history) instead of recommending secure secret management.

Persistence & Privilege

always:false and no special platform privileges are requested. The code does persist user data: it creates ~/.stealth-browser/profiles, stores user_data_dir and cookies (export/import), and sets file permissions. That is reasonable for a session manager, but it does create persistent artifacts in the user's home which may contain cookies or other session data.

What to consider before installing

This skill appears to implement what it claims (a containerized, Firefox-fork based stealth browser) but has several red flags you should consider before installing or running it: 1) provenance: the camoufox package will download a large compiled Firefox fork (~700MB) from external sources — verify the package origin, inspect its install code, and prefer running in an isolated VM if you proceed; 2) undeclared env usage: the README/SKILL.md refer to HTTP_PROXY/HTTPS_PROXY and proxy credentials but the skill metadata doesn't declare these — treat any credentials you pass carefully (avoid putting secrets in command lines or shell history); 3) persistence: the tool stores profiles and cookies under ~/.stealth-browser — review and remove these artifacts if you stop using the skill; 4) legal/ethical: this tool is explicitly designed to bypass anti-bot protections — ensure you have permission to access/automate the target sites; 5) safer testing: if you want to try it, run the setup/install in an ephemeral VM or isolated container, inspect what camoufox.install() downloads, and review the camoufox package source on PyPI/GitHub before trusting the binary. If you need, I can list exact lines in the code that perform the downloads, proxy parsing, cookie saves, and where secrets may leak to help you audit further.

C++ level anti-bot evasion using Camoufox — a custom Firefox fork with stealth patches compiled into the browser itself, not bolted on via JavaScript.

Why Camoufox > Chrome-based Solutions

Approach	Detection Level	Tools
Camoufox (this skill)	C++ compiled patches	Undetectable fingerprints baked into browser
undetected-chromedriver	JS runtime patches	Can be detected by timing analysis
puppeteer-stealth	JS injection	Patches applied after page load = detectable
playwright-stealth	JS injection	Same limitations

Camoufox patches Firefox at the source code level — WebGL, Canvas, AudioContext fingerprints are genuinely spoofed, not masked by JavaScript overrides that anti-bot systems can detect.

Key Advantages

1. C++ Level Stealth — Fingerprint spoofing compiled into the browser, not JS hacks
2. Container Isolation — Runs in distrobox, keeping your host system clean
3. Dual-Tool Approach — Camoufox for browsers, curl_cffi for API-only (no browser overhead)
4. Firefox-Based — Less fingerprinted than Chrome (everyone uses Chrome for bots)

When to Use

• Standard Playwright/Selenium gets blocked
• Site shows Cloudflare challenge or "checking your browser"
• Need to scrape Airbnb, Yelp, or similar protected sites
• puppeteer-stealth or undetected-chromedriver stopped working
• You need actual stealth, not JS band-aids

Tool Selection

Tool	Level	Best For
Camoufox	C++ patches	All protected sites - Cloudflare, Datadome, Yelp, Airbnb
curl_cffi	TLS spoofing	API endpoints only - no JS needed, very fast

Quick Start

All scripts run in pybox distrobox for isolation.

⚠️ Use python3.14 explicitly - pybox may have multiple Python versions with different packages installed.

1. Setup (First Time)

# Install tools in pybox (use python3.14)
distrobox-enter pybox -- python3.14 -m pip install camoufox curl_cffi

# Camoufox browser downloads automatically on first run (~700MB Firefox fork)

2. Fetch a Protected Page

Browser (Camoufox):

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py "https://example.com" --headless

API only (curl_cffi):

distrobox-enter pybox -- python3.14 scripts/curl-api.py "https://api.example.com/endpoint"

Architecture

┌─────────────────────────────────────────────────────────┐
│                     OpenClaw Agent                       │
├─────────────────────────────────────────────────────────┤
│  distrobox-enter pybox -- python3.14 scripts/xxx.py         │
├─────────────────────────────────────────────────────────┤
│                      pybox Container                     │
│         ┌─────────────┐  ┌─────────────┐               │
│         │  Camoufox   │  │  curl_cffi  │               │
│         │  (Firefox)  │  │  (TLS spoof)│               │
│         └─────────────┘  └─────────────┘               │
└─────────────────────────────────────────────────────────┘

Tool Details

Camoufox

• What: Custom Firefox build with C++ level stealth patches
• Pros: Best fingerprint evasion, passes Turnstile automatically
• Cons: ~700MB download, Firefox-based
• Best for: All protected sites - Cloudflare, Datadome, Yelp, Airbnb

curl_cffi

• What: Python HTTP client with browser TLS fingerprint spoofing
• Pros: No browser overhead, very fast
• Cons: No JS execution, API endpoints only
• Best for: Known API endpoints, mobile app reverse engineering

Critical: Proxy Requirements

Datacenter IPs (AWS, DigitalOcean) = INSTANT BLOCK on Airbnb/Yelp

You MUST use residential or mobile proxies:

# Example proxy config
proxy = "http://user:[e-mail]:8080"

See references/proxy-setup.md for proxy configuration.

Behavioral Tips

Sites like Airbnb/Yelp use behavioral analysis. To avoid detection:

1. Warm up: Don't hit target URL directly. Visit homepage first, scroll, click around.
2. Mouse movements: Inject random mouse movements (Camoufox handles this).
3. Timing: Add random delays (2-5s between actions), not fixed intervals.
4. Session stickiness: Use same proxy IP for 10-30 min sessions, don't rotate every request.

Headless Mode Warning

⚠️ Old --headless flag is DETECTED. Options:

1. New Headless: Use headless="new" (Chrome 109+)
2. Xvfb: Run headed browser in virtual display
3. Headed: Just run headed if you can (most reliable)

# Xvfb approach (Linux)
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
python scripts/camoufox-fetch.py "https://example.com"

Troubleshooting

Problem	Solution
"Access Denied" immediately	Use residential proxy
Cloudflare challenge loops	Try Camoufox instead of Nodriver
Browser crashes in pybox	Install missing deps: sudo dnf install gtk3 libXt
TLS fingerprint blocked	Use curl_cffi with impersonate="chrome120"
Turnstile checkbox appears	Add mouse movement, increase wait time
ModuleNotFoundError: camoufox	Use python3.14 not python or python3
greenlet segfault (exit 139)	Python version mismatch - use python3.14 explicitly
libstdc++.so.6 errors	NixOS lib path issue - use python3.14 in pybox

Python Version Issues (NixOS/pybox)

The pybox container may have multiple Python versions with separate site-packages:

# Check which Python has camoufox
distrobox-enter pybox -- python3.14 -c "import camoufox; print('OK')"

# Wrong (may use different Python)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ...

# Correct (explicit version)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py ...

If you get segfaults or import errors, always use python3.14 explicitly.

Examples

Scrape Airbnb Listing

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \
  "https://www.airbnb.com/rooms/12345" \
  --headless --wait 10 \
  --screenshot airbnb.png

Scrape Yelp Business

distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \
  "https://www.yelp.com/biz/some-restaurant" \
  --headless --wait 8 \
  --output yelp.html

API Scraping with TLS Spoofing

distrobox-enter pybox -- python3.14 scripts/curl-api.py \
  "https://api.yelp.com/v3/businesses/search?term=coffee&location=SF" \
  --headers '{"Authorization": "Bearer xxx"}'

Session Management

Persistent sessions allow reusing authenticated state across runs without re-logging in.

Quick Start

# 1. Login interactively (headed browser opens)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --login "https://www.airbnb.com/account-settings"

# Complete login in browser, then press Enter to save session

# 2. Reuse session in headless mode
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --headless "https://www.airbnb.com/trips"

# 3. Check session status
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile airbnb --status "https://www.airbnb.com"

Flags

Flag	Description
--profile NAME	Named profile for session storage (required)
--login	Interactive login mode - opens headed browser
--headless	Use saved session in headless mode
--status	Check if session appears valid
--export-cookies FILE	Export cookies to JSON for backup
--import-cookies FILE	Import cookies from JSON file

Storage

• Location: ~/.stealth-browser/profiles/<name>/
• Permissions: Directory 700, files 600
• Profile names: Letters, numbers, _, - only (1-63 chars)

Cookie Handling

• Save: All cookies from all domains stored in browser profile
• Restore: Only cookies matching target URL domain are used
• SSO: If redirected to Google/auth domain, re-authenticate once and profile updates

Login Wall Detection

The script detects session expiry using multiple signals:

1. HTTP status: 401, 403
2. URL patterns: /login, /signin, /auth
3. Title patterns: "login", "sign in", etc.
4. Content keywords: "captcha", "verify", "authenticate"
5. Form detection: Password input fields

If detected during --headless mode, you'll see:

🔒 Login wall signals: url-path, password-form

Re-run with --login to refresh the session.

Remote Login (SSH)

Since --login requires a visible browser, you need display forwarding:

X11 Forwarding (Preferred):

# Connect with X11 forwarding
ssh -X user@server

# Run login (opens browser on your local machine)
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile mysite --login "https://example.com"

VNC Alternative:

# On server: start VNC session
vncserver :1

# On client: connect to VNC
vncviewer server:1

# In VNC session: run login
distrobox-enter pybox -- python3.14 scripts/camoufox-session.py \
  --profile mysite --login "https://example.com"

Security Notes

⚠️ Cookies are credentials. Treat profile directories like passwords:

• Profile dirs have chmod 700 (owner only)
• Cookie exports have chmod 600
• Don't share profiles or exported cookies over insecure channels
• Consider encrypting backups

Limitations

Limitation	Reason
localStorage/sessionStorage not exported	Use browser profile instead (handles automatically)
IndexedDB not portable	Stored in browser profile, not cookie export
No parallel profile access	No file locking in v1; use one process per profile

References

• references/proxy-setup.md — Proxy configuration guide
• references/fingerprint-checks.md — What anti-bot systems check