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 } }

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.

• Widget success: "ok": true and token longer than 20 characters. Use it immediately (~300s TTL).
• Waiting-room success (grok.com): "ok": true and kind is cf_clearance or cf_passed, with clearanceLen > 20. The tab is the real site.
• Failure: "ok": false and error. Do not invent a token.

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

Verified

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

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

• Headed Chrome only. Interstitial needs the tab visible (Page.bringToFront).
• Datacenter IPs often fail; one residential-proxy retry, then stop.
• Do not cache tokens across sessions.
• Not 1020/1015/WAF block, not a fingerprint browser.

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

🚩 友情链接

License

MIT. See LICENSE.