From 976f5ae5346dce17b54275f7027f262bbf722517 Mon Sep 17 00:00:00 2001 From: Cloak-HQ Date: Thu, 5 Mar 2026 03:41:36 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20streamline=20READMEs=20for=20launch=20?= =?UTF-8?q?=E2=80=94=20remove=20repetition,=20reorder=20for=20conversion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Hero: remove emojis, cut weak bullets, add auto-updating/free+OSS - Latest: rename to v0.3.5 (Chromium 145), swap weaker items for CDP/audit/persistent - Why: remove unverified AI agent claims, cut redundant lines - Test Results: 30/30 → tested against 30+ detection sites - Comparison: move up after proof images, Camoufox "Unstable" - Fingerprint flags: collapse into
block - Platforms: move up before Docker - Headed Mode: merge into Troubleshooting - Roadmap: move down after FAQ - FAQ legal: rewrite to "do not condone illegal use" - Add rollback instructions via CLOAKBROWSER_BINARY_PATH - Examples: update descriptions, remove persistent-context.ts - js/README.md: sync hero, platforms, test table, reCAPTCHA tips --- .gitignore | 1 + Dockerfile | 3 +- README.md | 131 ++++++++++++++++++++++++++++----------------------- js/README.md | 45 +++++++++++++----- 4 files changed, 108 insertions(+), 72 deletions(-) diff --git a/.gitignore b/.gitignore index 11c24fb..698c301 100644 --- a/.gitignore +++ b/.gitignore @@ -61,3 +61,4 @@ publish.sh deploy.sh .env debug +publish-docker.sh diff --git a/Dockerfile b/Dockerfile index 274b78d..3d52ca4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,8 +13,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ WORKDIR /app -COPY pyproject.toml README.md LICENSE ./ +COPY pyproject.toml README.md LICENSE BINARY-LICENSE.md CHANGELOG.md ./ COPY cloakbrowser/ cloakbrowser/ +COPY examples/ examples/ RUN pip install --no-cache-dir . diff --git a/README.md b/README.md index 4ca54b3..5829802 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,12 @@ Drop-in Playwright/Puppeteer replacement for Python and JavaScript.
Same API, same code — just swap the import. 3 lines of code, 30 seconds to unblock.

-- 🔒 **26 source-level C++ patches** — not JS injection, not config flags -- 🛡️ **CDP stealth built-in** — uses [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) to reduce Playwright's automation footprint -- 🎯 **0.9 reCAPTCHA v3 score** — human-level, server-verified -- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 30/30 tests -- 🔄 **Drop-in replacement** — works with Playwright (Python & JS) and Puppeteer (JS) -- 📦 **`pip install cloakbrowser`** or **`npm install cloakbrowser`** — binary auto-downloads, zero config -- 💸 **Enterprise results, zero cost** — anti-detect browsers charge $49–299/month for the same results. CloakBrowser is free +- **26 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, automation signals +- **0.9 reCAPTCHA v3 score** — human-level, server-verified +- **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — tested against 30+ detection sites +- **Auto-updating binary** — background update checks, always on the latest stealth build +- **`pip install cloakbrowser`** or **`npm install cloakbrowser`** — binary auto-downloads, zero config +- **Free and open source** — no subscriptions, no usage limits **Python:** ```python @@ -104,16 +103,16 @@ page.goto("https://example.com") > ⭐ **Star** to show support — **[Watch releases](https://github.com/CloakHQ/CloakBrowser/subscription)** to get notified when new builds drop. -## What's New in v0.3.4 +## Latest: v0.3.5 (Chromium 145.0.7632.109) - **All 4 platforms** — Linux x64, macOS arm64, macOS x64, and Windows x64 all on Chromium 145 - **26 fingerprint patches** — 10 new patches since v142 (screen, device memory, audio, WebGL, auto-spoof, and more) - **Stealthy with zero flags** — binary auto-generates a random fingerprint seed at startup. No configuration required -- **Deterministic seeds** — `--fingerprint=seed` produces the same identity across launches for session persistence - **Full stealth audit** — every patch reviewed for detection vectors, multiple fixes shipped -- **Timezone & locale from proxy IP** — `launch(proxy="...", geoip=True)` auto-detects timezone and locale -- **SHA-256 checksum verification** — binary downloads are verified for integrity - **CDP hardening** — audited and patched known automation detection vectors +- **Timezone & locale from proxy IP** — `launch(proxy="...", geoip=True)` auto-detects timezone and locale +- **Playwright + Puppeteer from one package** — `import from 'cloakbrowser'` or `import from 'cloakbrowser/puppeteer'`. Same binary, your choice of API +- **Persistent profiles** — `launch_persistent_context()` keeps cookies and localStorage across sessions, bypasses incognito detection See the full [CHANGELOG.md](CHANGELOG.md) for details. @@ -123,10 +122,9 @@ See the full [CHANGELOG.md](CHANGELOG.md) for details. - **CloakBrowser patches Chromium source code** — fingerprints are modified at the C++ level, compiled into the binary. Detection sites see a real browser because it *is* a real browser. - **Two layers of stealth** — C++ patches handle fingerprints (GPU, screen, UA, hardware reporting), while the Patchright driver defers Playwright's binding registration and randomizes internal world names. Most stealth tools only do one or the other. - **Same behavior everywhere** — works identically local, in Docker, and on VPS. No environment-specific patches or config needed. -- **Works with AI browser agents** — drop-in stealth binary for [browser-use](https://github.com/browser-use/browser-use), [agent-browser](https://github.com/nichochar/agent-browser), Claude computer use, and OpenAI Operator -- **One line to switch** — same Playwright API, no new abstractions, no CAPTCHA-solving services. +- **Works with any browser automation framework** — tested and passing stealth checks with Playwright, Puppeteer, Selenium, undetected-chromedriver, browser-use, Crawl4AI, and agent-browser. Just point any Chromium-based framework at the binary path. -CloakBrowser doesn't solve CAPTCHAs — it prevents them from appearing. Antibot systems score it as a normal browser because it *is* a normal browser, just with your fingerprints instead of theirs. No CAPTCHA services, no proxy rotation built in — bring your own proxies, use the Playwright API you already know. +CloakBrowser doesn't solve CAPTCHAs — it prevents them from appearing. No CAPTCHA-solving services, no proxy rotation built in — bring your own proxies, use the Playwright API you already know. ## Test Results @@ -148,7 +146,7 @@ All tests verified against live detection services. Last tested: Mar 2026 (Chrom | UA string | `HeadlessChrome` | **`Chrome/145.0.0.0`** | No headless leak | | CDP detection | Detected | **Not detected** | `isAutomatedWithCDP: false` | | TLS fingerprint | Mismatch | **Identical to Chrome** | ja3n/ja4/akamai match | -| | | **30/30 passed** | | +| | | **Tested against 30+ detection sites** | | ### Proof @@ -172,6 +170,18 @@ All tests verified against live detection services. Last tested: Mar 2026 (Chrom
FingerprintJS web-scraping demo — data served, not blocked

+## Comparison + +| Feature | Playwright | playwright-stealth | undetected-chromedriver | Camoufox | CloakBrowser | +|---|---|---|---|---|---| +| reCAPTCHA v3 score | 0.1 | 0.3-0.5 | 0.3-0.7 | 0.7-0.9 | **0.9** | +| Cloudflare Turnstile | Fail | Sometimes | Sometimes | Pass | **Pass** | +| Patch level | None | JS injection | Config patches | C++ (Firefox) | **C++ (Chromium)** | +| Survives Chrome updates | N/A | Breaks often | Breaks often | Yes | **Yes** | +| Maintained | Yes | Stale | Stale | Unstable | **Active** | +| Browser engine | Chromium | Chromium | Chrome | Firefox | **Chromium** | +| Playwright API | Native | Native | No (Selenium) | No | **Native** | + ## How It Works CloakBrowser is a thin wrapper (Python + JavaScript) around a custom-built Chromium binary: @@ -403,6 +413,9 @@ The binary detects its platform at compile time — a macOS binary reports as ma > const browser = await launch({ args: ['--fingerprint=12345'] }); > ``` +
+Default Fingerprint & All Flags (click to expand) + ### Default Fingerprint Every `launch()` call sets these automatically. The **wrapper** applies platform-aware defaults — on Linux it spoofs as Windows for a more common fingerprint, on macOS it runs as a native Mac browser: @@ -462,17 +475,21 @@ browser = launch(args=[ ]) ``` -## Comparison +
-| Feature | Playwright | playwright-stealth | undetected-chromedriver | Camoufox | CloakBrowser | -|---|---|---|---|---|---| -| reCAPTCHA v3 score | 0.1 | 0.3-0.5 | 0.3-0.7 | 0.7-0.9 | **0.9** | -| Cloudflare Turnstile | Fail | Sometimes | Sometimes | Pass | **Pass** | -| Patch level | None | JS injection | Config patches | C++ (Firefox) | **C++ (Chromium)** | -| Survives Chrome updates | N/A | Breaks often | Breaks often | Yes | **Yes** | -| Maintained | Yes | Stale | Stale | Unstable (2026 beta) | **Active** | -| Browser engine | Chromium | Chromium | Chrome | Firefox | **Chromium** | -| Playwright API | Native | Native | No (Selenium) | No | **Native** | +## Examples + +**Python** — see [`examples/`](examples/): +- [`basic.py`](examples/basic.py) — Launch and load a page +- [`persistent_context.py`](examples/persistent_context.py) — Persistent profile with cookie/localStorage persistence +- [`recaptcha_score.py`](examples/recaptcha_score.py) — Check your reCAPTCHA v3 score +- [`stealth_test.py`](examples/stealth_test.py) — Run against 6 detection sites +- [`fingerprint_scan_test.py`](examples/fingerprint_scan_test.py) — Test against fingerprint-scan.com and CreepJS + +**JavaScript** — see [`js/examples/`](js/examples/): +- [`basic-playwright.ts`](js/examples/basic-playwright.ts) — Playwright launch and load +- [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer launch and load +- [`stealth-test.ts`](js/examples/stealth-test.ts) — Run against 6 detection sites ## Platforms @@ -487,32 +504,6 @@ The wrapper auto-downloads the correct binary for your platform. **macOS first launch:** The binary is ad-hoc signed. On first run, macOS Gatekeeper will block it. Right-click the app → **Open** → click **Open** in the dialog. This is only needed once. -## Examples - -**Python** — see [`examples/`](examples/): -- [`basic.py`](examples/basic.py) — Launch and load a page -- [`persistent_context.py`](examples/persistent_context.py) — Persistent profile with cookie/localStorage persistence -- [`recaptcha_score.py`](examples/recaptcha_score.py) — Check your reCAPTCHA v3 score -- [`stealth_test.py`](examples/stealth_test.py) — Run against all detection services -- [`fingerprint_scan_test.py`](examples/fingerprint_scan_test.py) — Test against fingerprint-scan.com and CreepJS - -**JavaScript** — see [`js/examples/`](js/examples/): -- [`basic-playwright.ts`](js/examples/basic-playwright.ts) — Playwright launch and load -- [`persistent-context.ts`](js/examples/persistent-context.ts) — Persistent profile with cookie/localStorage persistence -- [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer launch and load -- [`stealth-test.ts`](js/examples/stealth-test.ts) — Full 6-site detection test suite - -## Roadmap - -| Feature | Status | -|---------|--------| -| Linux x64 — Chromium 145 (26 patches) | ✅ Released | -| macOS arm64/x64 — Chromium 145 (26 patches) | ✅ Released | -| Windows x64 — Chromium 145 (26 patches) | ✅ Released | -| JavaScript/Puppeteer + Playwright support | ✅ Released | -| Fingerprint rotation per session | ✅ Released | -| Built-in proxy rotation | 📋 Planned | - ## Docker A ready-to-use [`Dockerfile`](Dockerfile) is included. It installs system deps, the package, and pre-downloads the stealth binary during build: @@ -552,9 +543,11 @@ CloakBrowser works identically local, in Docker, and on VPS. No environment-spec **Note:** If you run CloakBrowser inside a web server with uvloop (e.g., `uvicorn[standard]`), use `--loop asyncio` to avoid subprocess pipe hangs. -## Headed Mode (for aggressive bot detection) +## Troubleshooting -Some sites using advanced bot detection (e.g., DataDome, Cloudflare Turnstile) can detect headless mode even with our C++ patches. For these sites, run in **headed mode** with a virtual display: +**Still getting blocked on aggressive sites (DataDome, Turnstile)?** + +Some sites detect headless mode even with our C++ patches. Run in **headed mode** with a virtual display: ```bash # Install Xvfb (virtual framebuffer) @@ -575,11 +568,7 @@ page.goto("https://heavily-protected-site.com") # passes DataDome, etc. browser.close() ``` -This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combined with a residential proxy, this passes even the most aggressive detection services. - -> **Tip:** Datacenter IPs are often flagged by IP reputation databases regardless of browser fingerprint. For sites with strict bot detection, a residential proxy makes the difference. - -## Troubleshooting +This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combined with a residential proxy, this passes even the most aggressive detection services. Datacenter IPs are often flagged by IP reputation regardless of browser fingerprint — a residential proxy makes the difference. **Reddit or similar sites show CAPTCHA / "Prove your humanity"** @@ -608,6 +597,19 @@ Set a custom download URL or use a local binary: export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome ``` +**New update broke something? Roll back to the previous version** +When auto-update downloads a newer binary, the previous version stays in `~/.cloakbrowser/`. Point `CLOAKBROWSER_BINARY_PATH` to the older cached binary: +```bash +# Linux +export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109/chrome + +# macOS +export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109/Chromium.app/Contents/MacOS/Chromium + +# Windows +set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.109\chrome.exe +``` + **macOS: "App is damaged" or Gatekeeper blocks launch** The binary is ad-hoc signed. macOS quarantines downloaded files. Run once to clear it: ```bash @@ -682,7 +684,7 @@ Other tips for maximizing reCAPTCHA scores: ## FAQ **Q: Is this legal?** -A: CloakBrowser is a browser. Using it is legal. What you do with it is your responsibility, just like with Chrome, Firefox, or any browser. We do not endorse violating website terms of service. Use against financial, banking, healthcare, or government authentication systems without authorization is expressly prohibited. See [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md) for full terms. +A: CloakBrowser is a browser built on open-source Chromium. We do not condone illegal use. Automating systems without authorization, credential stuffing, and account creation abuse are expressly prohibited. See [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md) for full terms. **Q: How is this different from Camoufox?** A: Camoufox patches Firefox. We patch Chromium. Chromium means native Playwright support, larger ecosystem, and TLS fingerprints that match real Chrome. Camoufox returned in early 2026 but is in unstable beta — CloakBrowser is production-ready. @@ -693,6 +695,17 @@ A: Possibly. Bot detection is an arms race. Source-level patches are harder to d **Q: Can I use my own proxy?** A: Yes. Pass `proxy="http://user:pass@host:port"` to `launch()`. +## Roadmap + +| Feature | Status | +|---------|--------| +| Linux x64 — Chromium 145 (26 patches) | ✅ Released | +| macOS arm64/x64 — Chromium 145 (26 patches) | ✅ Released | +| Windows x64 — Chromium 145 (26 patches) | ✅ Released | +| JavaScript/Puppeteer + Playwright support | ✅ Released | +| Fingerprint rotation per session | ✅ Released | +| Built-in proxy rotation | 📋 Planned | + ## Links - 📋 **Changelog** — [CHANGELOG.md](CHANGELOG.md) diff --git a/js/README.md b/js/README.md index feccada..b4c720c 100644 --- a/js/README.md +++ b/js/README.md @@ -9,13 +9,14 @@ **Stealth Chromium that passes every bot detection test.** -Drop-in Playwright/Puppeteer replacement. Same API — just swap the import. Scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **30/30** stealth detection tests. +Drop-in Playwright/Puppeteer replacement. Same API, same code — just swap the import. **3 lines of code, 30 seconds to unblock.** -- 🔒 **26 source-level C++ patches** — not JS injection, not config flags -- 🎯 **0.9 reCAPTCHA v3 score** — human-level, server-verified -- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 30/30 tests -- 🔄 **Drop-in replacement** — works with both Playwright and Puppeteer -- 📦 **`npm install cloakbrowser`** — binary auto-downloads, zero config +- **26 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, automation signals +- **0.9 reCAPTCHA v3 score** — human-level, server-verified +- **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — tested against 30+ detection sites +- **`npm install cloakbrowser`** — binary auto-downloads, auto-updates, zero config +- **Free and open source** — no subscriptions, no usage limits +- **Works with any framework** — also tested with Selenium, undetected-chromedriver, browser-use, Crawl4AI, and agent-browser ## Install @@ -161,6 +162,9 @@ if (newVersion) console.log(`Updated to ${newVersion}`); | **BrowserScan** | DETECTED | **NORMAL** (4/4) | | **bot.incolumitas.com** | 13 fails | **1 fail** | | `navigator.webdriver` | `true` | **`false`** | +| CDP detection | Detected | **Not detected** | +| TLS fingerprint | Mismatch | **Identical to Chrome** | +| | | **Tested against 30+ detection sites** | ## Configuration @@ -186,12 +190,12 @@ const page = await browser.newPage(); ## Platforms -| Platform | Status | -|---|---| -| Linux x86_64 | ✅ Available | -| macOS arm64 (Apple Silicon) | ✅ Available | -| macOS x86_64 (Intel) | ✅ Available | -| Windows x86_64 | ✅ Available | +| Platform | Chromium | Patches | Status | +|---|---|---|---| +| Linux x86_64 | 145 | 26 | ✅ Latest | +| macOS arm64 (Apple Silicon) | 145 | 26 | ✅ Latest | +| macOS x86_64 (Intel) | 145 | 26 | ✅ Latest | +| Windows x86_64 | 145 | 26 | ✅ Latest | ## Requirements @@ -233,8 +237,25 @@ Other tips for maximizing reCAPTCHA scores: - **Spend 15+ seconds on the page** before triggering reCAPTCHA — short visits score lower - **Space out requests** — back-to-back `grecaptcha.execute()` calls from the same session get penalized. Wait 30+ seconds between pages with reCAPTCHA - **Use a fixed fingerprint seed** (`--fingerprint=12345`) for consistent device identity across sessions +- **Use `page.type()` instead of `page.fill()`** for form filling — `fill()` sets values directly without keyboard events, which reCAPTCHA's behavioral analysis flags. `type()` with a delay simulates real keystrokes: + ```javascript + await page.type('#email', 'user@example.com', { delay: 50 }); + ``` - **Minimize `page.evaluate()` calls** before the reCAPTCHA check fires — each one sends CDP traffic +**New update broke something? Roll back to the previous version** +When auto-update downloads a newer binary, the previous version stays in `~/.cloakbrowser/`. Point `CLOAKBROWSER_BINARY_PATH` to the older cached binary: +```bash +# Linux +export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109/chrome + +# macOS +export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109/Chromium.app/Contents/MacOS/Chromium + +# Windows +set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.109\chrome.exe +``` + ## Links - 🌐 [Website](https://cloakbrowser.dev)