turnstile-bypass README

The project's README from github.com/Sophomoresty/turnstile-bypass. As one markdown file: README.md.

turnstile-bypass

Self-contained Cloudflare challenge helper for macOS, Windows, and Linux.

It drives headed Chrome to pass the two CF layers people usually call “the shield”:

  1. Turnstile widget on a site page (e.g. aipaycards.com/login) → JSON token
  2. Interstitial waiting room (请稍候… / Just a moment, e.g. grok.com) → cf_clearance and the real origin

curl https://grok.com/ is 403 + cf-mitigated: challenge. After solve.py --url https://grok.com/ --fresh, the same Chrome tab is the Grok app with a cf_clearance cookie.

It does not pass IP bans (1020), rate limits (1015), or Bot Fight when this Chrome is already rejected.

A new agent should follow Install then Use. Nothing else is required.

Install

Needs: Python 3.10+, Google Chrome or Chromium.

git clone https://github.com/Sophomoresty/turnstile-bypass.git
cd turnstile-bypass
python3 scripts/install.py

install.py creates .venv in this repo, installs requirements.txt (DrissionPage), packs assets/turnstilePatch.zip, and runs scripts/preflight.py.

You want:

{ "ok": true, "methods": { "drissionpage": true } }
OS If Chrome is not found
macOS Install Google Chrome, or export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
Windows set CHROME_PATH=C:\Path\to\chrome.exe
Linux sudo apt-get install -y google-chrome-stable or chromium
Linux, no desktop sudo apt-get install -y xvfb then prefix commands with xvfb-run -a

Manual install (same result):

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt   # Windows: .venv\Scripts\python.exe
python3 scripts/pack_extension.py
python3 scripts/preflight.py

Use

python3 scripts/solve.py --url "https://aipaycards.com/login"
python3 scripts/solve.py --url "https://grok.com/" --fresh

Stdout is one JSON object.

Force a lane:

python3 scripts/solve.py --lane drission --url "https://example.com/login"
python3 scripts/solve.py --lane ab --url "https://example.com/login"

Linux without GUI:

xvfb-run -a python3 scripts/solve.py --url "https://example.com/login"

Default lane: DrissionPage + packaged extension after install.py. If agent-browser-cli and Node are already on PATH, solve.py prefers that faster lane (TURNSTILE_PREFER_AB=0 to force Drission).

--lane ab is optional and faster only if agent-browser-cli + Node are already installed and that Chrome already has this extension. Iframe clicks must use Chrome CDP (default port 19221), never the shim 19222.

YesCaptcha (last resort): YESCAPTCHA_CLIENT_KEY and

python3 scripts/solve.py --lane yescaptcha --url "https://example.com" --sitekey "0x..."

Chrome extension

Source of truth: assets/turnstilePatch/ (load unpacked).

Packed copy: assets/turnstilePatch.zip (same two files). Rebuild with python3 scripts/pack_extension.py.

The extension is Manifest V3, world: MAIN, all_frames, matches https://challenges.cloudflare.com/* only. It patches MouseEvent.screenX/Y because Chrome CDP clicks set screen coords equal to client coords (chromium 40280325), which Turnstile treats as a bot.

Load unpacked (manual Chrome): chrome://extensions → Developer mode → Load unpacked → select assets/turnstilePatch/.

DrissionPage does this for you via add_extension. You do not need to click that UI for the default solve.py path.

What it is not

In scope Out of scope
Turnstile widget on the origin page Cloudflare 1020 / 1015 / WAF block
Interstitial “请稍候…” / Just a moment (JS or managed challenge) Bot Fight when this Chrome is already banned
cf_clearance + origin HTML hCaptcha, reCAPTCHA, headless Chrome

Verified

macOS, Chrome 152, agent-browser, CDP 19221.

Target What Result Time
https://demo.turnstile.workers.dev/ dummy Turnstile tokenLen 21 3.46s
examples/interactive-dummy.html dummy interactive tokenLen 21 7.46s
https://aipaycards.com/login production Turnstile tokenLen 816, 3/3 8–11s
https://grok.com/ interstitial (cf-mitigated: challenge) kind=cf_clearance, clearanceLen 533–597, origin title Grok ~9s (--fresh)

curl to grok.com without this Chrome is 403 + cf-mitigated: challenge. After solve, the same tab is the Grok app. Interstitial path focuses the tab (Page.bringToFront) and clicks the CF iframe; waiting-room JS often refuses to finish if document.visibilityState is hidden.

python3 scripts/solve.py --url "https://grok.com/" --fresh
python3 scripts/e2e.py

Layout

AGENTS.md                 # short runbook for coding agents
README.md                 # this file
LICENSE
requirements.txt          # DrissionPage
assets/turnstilePatch/    # unpacked MV3 extension
assets/turnstilePatch.zip # same, zipped
examples/interactive-dummy.html
scripts/install.py            # venv + deps + pack + preflight
scripts/e2e.py                # live two-page check; exit 0 only on success
scripts/preflight.py
scripts/solve.py          # entry
scripts/solve_turnstile.py
scripts/pack_extension.py
scripts/solve_agent_browser.py
scripts/camoufox_turnstile.py
scripts/solve_yescaptcha.py
scripts/proxy_auth_extension.py
scripts/runtime.py

Limits

本项目的开发 agent 能力由 GenericAgent 提供。

🚩 友情链接

GenericAgent LinuxDo

License

MIT. See LICENSE.

turnstile-bypass (Sophomoresty/turnstile-bypass)

Searching Database…

502 ·GitHub
Turnstile-bypass
这是什么？一个跨平台工具，驱动真实的带界面 Chrome 浏览器来解开 Cloudflare Turnstile 组件，并通过 Cloudflare 的插页式“等候室”页面，以 JSON 形式返回令牌或 cfclearance cookie。
这是 GUI 应用还是命令行脚本？它是一个 Python 命令行脚本（solve.py），自动化一个真实的 Chrome 实例；它把单个 JSON 结果打印到标准输出，而不是显示界面。
怎么让它跑起来？运行 install.py，它会创建 .venv、从 requirements.txt 安装 DrissionPage、打包 turnstilePatch Chrome 扩展并运行 scripts/preflight.py；然后带 --url 调用 solve.py（插页式页面的情况再加 --fresh）。
这需要 Python 和真实的 Chrome 安装吗？需要——Python 3.10+ 加上 Google Chrome 或 Chromium；在没有图形界面的 Linux 机器上，你还需要 xvfb 来给 Chrome 提供显示。
它也能绕过 Cloudflare 的 IP 封禁和速率限制吗？不能——它只能解开 Turnstile 组件和 JS/托管式插页挑战；一旦 Chrome 实例已被标记，它无法越过 IP 封禁（1020）、速率限制（1015）、WAF 拦截或 Bot Fight。
这个扩展是怎么让 Turnstile 以为有真人点击的？这个 Manifest V3 扩展会给 MouseEvent.screenX/Y 打补丁，因为 Chrome DevTools Protocol 的点击通常把屏幕坐标设成与客户区坐标相同，而 Turnstile 把这一点当作机器人信号。
它能在没有显示器的无头服务器上运行吗？在 Linux 上可以，但插页式等候室需要 Chrome 标签页可见，因此安装 xvfb 后必须在命令前加上 xvfb-run -a；标签页还会通过 Page.bringToFront 强制聚焦。
有没有比默认更快的解题路径？如果已安装 agent-browser-cli 和 Node.js，并且那个 Chrome 已加载该扩展，solve.py 可以切换到更快的“ab”通道，而不是默认的 DrissionPage 通道。
如果浏览器解题仍然失败，有什么后备方案？作为最后手段，项目支持通过 YESCAPTCHACLIENTKEY 环境变量路由到 YesCaptcha 服务。
What are similar projects?SeleniumBase, nopecha-extension, undetected-chromedriver, cloudflare-turnstile-bypass, CloakBrowser, camofox-browser, botasaurus, ovobrowser
Which topics is it in?captcha-solving, cloudflare-bypass, bot-detection, captcha, scraping, chrome-extension, web-scraping, browser-automation, command-line-tool, automation, tool, cli
Creator
Sophomoresty
Size
<0.1 MB
Stars
502
Updated
CommitSep 07
Age
1mo
Commits · 90 Days