Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
README.md

Cloudflare Bypass Tool 2026

A multi-strategy toolkit for researching and testing Cloudflare Turnstile / Challenge flows on macOS, Windows, and Linux.

面向 Cloudflare Turnstile / Challenge 的多方案研究与授权测试工具集,支持 Mac / Windows / Linux。

Python Platform License


Table of Contents / 目录

English中文
Disclaimer免责声明
Overview项目概述
Method Comparison方案对比
Features功能特性
Requirements环境要求
Installation安装
Quick Start快速开始
Usage使用说明
Python APIPython API
Proxy Format代理格式
Output输出
Project Layout项目结构
FAQ常见问题
References参考资料
Business商务合作
License许可证

Disclaimer / 免责声明

English

This project is intended for educational research and authorized automation testing only. You must comply with applicable laws and the terms of service of any target website.

  • No warranty of fitness for any particular site or environment.
  • Success rates vary with IP reputation, browser environment, target policy, and timing.
  • Datacenter IPs, true headless mode, and display-less containers typically reduce success rates.

中文

本项目仅供学习研究与已授权的自动化测试使用。使用时须遵守当地法律法规及目标站点服务条款。

  • 不对任何站点、任何环境提供通过率保证。
  • 实际效果受 IP 信誉、浏览器环境、目标策略与时机影响。
  • 机房 IP、真无头模式、无图形界面的容器环境通常会显著降低成功率。

Overview / 项目概述

English

Cloudflare defenses in 2025–2026 are layered: network reputation, TLS/HTTP fingerprinting, JavaScript challenges, Turnstile interaction, and automation-protocol signals. A single HTTP client is not sufficient for Turnstile.

This repository provides five runnable strategies plus one class-based wrapper, so you can choose the right path for single-session research, batch jobs, pure CDP control, or TLS-level reuse of an already-solved session.

Recommended baseline (open-source path):

Headed real Chrome
  + optional residential / high-quality egress IP
  + UC reconnect or pure CDP
  + OS-level captcha click when interaction is required

Not recommended as a primary Turnstile path:

True headless hard-target Managed Turnstile
Pure curl_cffi / tls-client against Turnstile
playwright-stealth alone as a “one-click” solution

中文

2025–2026 年 Cloudflare 检测已分层:网络信誉、TLS/HTTP 指纹、JS Challenge、Turnstile 交互,以及自动化协议特征。单靠 HTTP 客户端无法完成 Turnstile。

本仓库提供 5 套可运行方案 与 1 个类封装入口,覆盖单会话研究、批量任务、纯 CDP 控制,以及浏览器解出后的 TLS 层会话复用。

开源场景下更稳妥的基线:

有头真实 Chrome
  + 可选住宅或高质量出口 IP
  + UC 断连重连 或 纯 CDP
  + 需要交互时使用操作系统级点击

不建议作为 Turnstile 主路径:

真无头模式硬刚 Managed Turnstile
纯 curl_cffi / tls-client 直打 Turnstile
单独依赖 playwright-stealth 作为“一键方案”

Method Comparison / 方案对比

#ScriptStrategy / 策略TurnstileBest for / 适用场景
1bypass.pySeleniumBase UC ModeYesDefault single-session path / 默认单会话主路径
2simple_bypass.pyUC + parallel / proxy rotationYesBatch jobs; GUI click contention possible / 批量任务;并行时可能争抢系统鼠标
3bypass_nodriver.pynodriver pure CDPYesChromedriver-free CDP; needs OpenCV; AGPL-3.0 / 无 chromedriver;需 OpenCV;注意 AGPL
4bypass_curl_cffi.pyTLS fingerprint / cookie reuseNoLegacy JS Challenge or post-solve cookie reuse only / 仅旧版 Challenge 或 Cookie 复用
5bypass_cdp.pySeleniumBase CDP ModeYes2026 successor path to plain UC / UC 后继路径
—bypass_seleniumbase.pyUC class wrapperYesEmbeddable API for secondary development / 可 import 的二次开发封装

Priority guide / 选择优先级

Priority / 优先级Choice / 选择Notes / 说明
1bypass.py or bypass_cdp.pyPrimary research entry / 主入口
2bypass_nodriver.pyStrong CDP alternative; check AGPL / 强备选;注意许可证
3simple_bypass.pyThroughput / rotation; serialize GUI clicks if needed / 吞吐与轮换;GUI 点击宜串行
4Browser solve then curl_cffi reuseKeep the same UA and egress IP / 须保持 UA 与出口 IP 一致
AvoidPure HTTP against TurnstileWill not execute JS / interact / 无法执行 JS 与交互

Why curl_cffi cannot pass Turnstile / 为何 curl_cffi 无法过 Turnstile

Limitation / 限制Detail / 说明
No JS runtimeCannot complete Turnstile / modern Challenge PoW
No DOM / Web APIsMissing navigator, WebGL, canvas signals
No interactionManaged mode requires a real checkbox click
TLS is only one signalJA3/JA4 matching is not sufficient alone

Features / 功能特性

Feature / 功能Description / 说明
SeleniumBase UC ModeDriver disconnect-reconnect + OS-level captcha click
SeleniumBase CDP ModePure CDP path with reduced WebDriver attachment signals
nodriver CDPNo chromedriver; verify_cf() template click (OpenCV)
Parallel / proxy rotationBatch workers and proxy file rotation in simple_bypass.py
Timeout controlEnd-to-end timeout on primary flows
Cookie exportJSON and Netscape formats where applicable
Cross-platformmacOS, Windows, Linux (Linux needs Xvfb when headless host)

Requirements / 环境要求

Item / 项目Requirement / 要求
Python3.9+
BrowserGoogle Chrome (or Chromium on non-amd64 Linux)
DisplayHeaded GUI preferred; Linux servers: Xvfb / virtual display
OSmacOS, Windows, Linux
Optional proxyHTTP / HTTPS / SOCKS5 with working HTTPS CONNECT

Python packages are listed in requirements.txt (SeleniumBase, nodriver, curl_cffi, OpenCV headless, pyvirtualdisplay, etc.).

Python 依赖见 requirements.txt(含 SeleniumBase、nodriver、curl_cffi、OpenCV headless、pyvirtualdisplay 等)。


Installation / 安装

macOS / Windows

git clone https://github.com/1837620622/cloudflare-bypass-2026.git
cd cloudflare-bypass-2026
pip install -r requirements.txt

Install Google Chrome before running browser-based scripts.

请先安装 Google Chrome,再运行浏览器方案。

Linux (Ubuntu / Debian)

git clone https://github.com/1837620622/cloudflare-bypass-2026.git
cd cloudflare-bypass-2026
sudo bash install_linux.sh

Manual alternative / 手动安装:

sudo apt-get update
sudo apt-get install -y xvfb libglib2.0-0 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libgbm1 libasound2
python3 -m pip install -r requirements.txt

Notes / 说明

  • Official Chrome .deb packages are primarily amd64. On ARM hosts, install a matching Chromium/Chrome build yourself.
  • 官方 Chrome deb 主要为 amd64。ARM 环境请自行准备对应架构的 Chromium/Chrome。

Quick Start / 快速开始

# Install dependencies / 安装依赖
pip install -r requirements.txt

# Method 1 — UC Mode (recommended default) / 方案1 默认推荐
python bypass.py https://example.com
python bypass.py https://example.com -p http://127.0.0.1:7890 -t 90

# Method 5 — CDP Mode / 方案5 CDP
python bypass_cdp.py https://example.com

# Method 3 — nodriver / 方案3
python bypass_nodriver.py https://example.com

Replace https://example.com with a target you are authorized to test.

请将示例 URL 替换为你有权测试的目标地址。


Usage / 使用说明

1. UC single browser — bypass.py (default)

Single Chrome session via SeleniumBase UC Mode: uc_open_with_reconnect + uc_gui_click_captcha / uc_gui_handle_captcha.

单浏览器 UC 模式:断连打开页面,并在检测到挑战时进行系统级点击。

python bypass.py https://example.com
python bypass.py https://example.com -p http://127.0.0.1:7890
python bypass.py https://example.com -t 90 --incognito
Argument / 参数Description / 说明Default / 默认
urlTarget URL / 目标 URLrequired
-p, --proxyProxy URL / 代理地址none
-t, --timeoutOverall timeout (seconds) / 总超时秒数60
-r, --reconnectReconnect disconnect window / 断连秒数5
--incognitoIncognito profile / 无痕模式off
--no-saveDo not write cookies / 不保存 Cookieoff

2. Parallel / rotation — simple_bypass.py

For multi-proxy or multi-browser batches. OS-level GUI clicks are not multi-window safe on one desktop; parallel workers may contend for the mouse.

适用于多代理或多浏览器批处理。操作系统级点击在同一桌面上不具备多窗口安全;并行时可能互相干扰。

python simple_bypass.py https://example.com
python simple_bypass.py https://example.com -r -f proxy.txt -c
python simple_bypass.py https://example.com -P -b 3 -t 30 -n 5 -c
Argument / 参数Description / 说明Default / 默认
-p, --proxyFixed proxy / 固定代理none
-f, --proxy-fileProxy list file / 代理列表文件proxy.txt
-r, --rotateSequential proxy rotation / 顺序轮换off
-P, --parallelParallel browsers / 并行浏览器off
-b, --batchBrowsers per batch / 每批浏览器数3
-t, --timeoutTimeout (seconds) / 超时秒数60
-n, --retriesMax batches or proxy attempts / 批次数或代理尝试数3
-c, --check-proxyPreflight proxy liveness / 代理存活预检off
-w, --waitPage wait / reconnect wait / 页面等待5
--no-saveDo not write cookies / 不保存 Cookieoff

3. nodriver pure CDP — bypass_nodriver.py

Chromedriver-free CDP control. Challenge click uses verify_cf() (OpenCV template match). Upstream license is AGPL-3.0.

无 chromedriver 的 CDP 控制。挑战点击使用 verify_cf()(OpenCV 模板匹配)。上游许可证为 AGPL-3.0。

pip install "nodriver>=0.50.0" opencv-python-headless
python bypass_nodriver.py https://example.com
python bypass_nodriver.py https://example.com -p http://127.0.0.1:7890
Argument / 参数Description / 说明Default / 默认
-p, --proxyProxy URL / 代理none
-t, --timeoutOverall timeout / 总超时60
--headlessHeadless (not recommended) / 无头(不推荐)off
--no-saveDo not write cookies / 不保存 Cookieoff

Commercial closed-source redistribution of AGPL components requires a separate compliance review.

闭源商用分发 AGPL 组件前请自行完成合规评估。


4. TLS client — bypass_curl_cffi.py (not for Turnstile)

HTTP/TLS fingerprint impersonation only. Suitable for weak or legacy challenges, or for replaying cookies obtained by a browser solver with matching User-Agent and egress IP.

仅 HTTP/TLS 指纹仿冒。适用于低防护或旧版 Challenge,或在 UA 与出口 IP 一致 的前提下复用浏览器解出的 Cookie。

python bypass_curl_cffi.py https://example.com
python bypass_curl_cffi.py https://example.com -f chrome146
python bypass_curl_cffi.py https://example.com -p http://127.0.0.1:7890
Argument / 参数Description / 说明Default / 默认
-p, --proxyProxy URL / 代理none
-f, --fingerprintImpersonation profile / 指纹配置chrome136
-t, --timeoutRequest timeout / 请求超时30
-n, --retriesRetry count / 重试次数3
--no-saveDo not write cookies / 不保存 Cookieoff

Common fingerprints include: chrome120, chrome124, chrome131, chrome136, chrome142, chrome146, firefox135, firefox144, safari17_0, safari18_0, edge101.


5. CDP Mode — bypass_cdp.py

SeleniumBase CDP Mode (sb_cdp): solve_captcha() with gui_click_captcha() fallback. Preferred upgrade path alongside UC Mode in 2026.

SeleniumBase CDP 模式:优先 solve_captcha(),失败时回退 gui_click_captcha()。2026 年与 UC 并列的升级路径。

python bypass_cdp.py https://example.com
python bypass_cdp.py https://example.com -p http://127.0.0.1:7890 -t 90
Argument / 参数Description / 说明Default / 默认
-p, --proxyProxy URL / 代理none
-t, --timeoutOverall timeout budget / 总超时预算60
--no-saveDo not write cookies / 不保存 Cookieoff

6. Class wrapper — bypass_seleniumbase.py

Object-oriented UC wrapper for embedding in larger projects.

面向对象的 UC 封装,便于嵌入更大工程。

python bypass_seleniumbase.py https://example.com -p http://127.0.0.1:7890

Python API

UC Mode (bypass.py)

from bypass import bypass_cloudflare

result = bypass_cloudflare(
    "https://example.com",
    proxy="http://127.0.0.1:7890",
    timeout=90,
    save_cookies=True,
)

if result["success"]:
    print(result["cf_clearance"])
    print(result["user_agent"])
    print(result["cookies"])
else:
    print(result["error"])

Class wrapper (bypass_seleniumbase.py)

from bypass_seleniumbase import bypass_and_get_cookies

result = bypass_and_get_cookies(
    "https://example.com",
    proxy="http://127.0.0.1:7890",
    session_name="demo",
)

if result["success"]:
    print(result["cf_clearance"])

nodriver (sync helper)

from bypass_nodriver import bypass_sync

result = bypass_sync("https://example.com", timeout=60.0)

curl_cffi (non-Turnstile)

from bypass_curl_cffi import bypass_cloudflare_http

# Optional: reuse browser-solved cookies
result = bypass_cloudflare_http(
    "https://example.com",
    fingerprint="chrome146",
    cookies={"cf_clearance": "..."},  # optional
)

Result shape / 返回字段

Field / 字段Type / 类型Meaning / 含义
successboolWhether a usable clearance path was obtained / 是否获得可用通过结果
cookiesdictName to value map / Cookie 字典
cf_clearancestr or NoneCloudflare clearance cookie when present
user_agentstr or NoneBrowser UA used for the session / 会话 UA
errorstr or NoneFailure reason / 失败原因
methodstrStrategy identifier / 方案标识

Proxy Format / 代理格式

File: proxy.txt (one entry per line) / 每行一个代理:

127.0.0.1:7890
http://127.0.0.1:7890
socks5://127.0.0.1:1080
http://user:pass@host:port

Most free public proxies do not support HTTPS CONNECT reliably. Prefer verified residential or high-quality providers for production research.

绝大多数免费公共代理无法稳定支持 HTTPS 隧道。研究与生产环境请使用经验证的住宅或高质量代理。


Output / 输出

Cookies are written under output/cookies/ when saving is enabled.

启用保存时,Cookie 写入 output/cookies/。

Prefix / 前缀Source / 来源
cookies_*.json / cookies_*.txtbypass.py, simple_bypass.py
cookies_cdp_*.jsonbypass_cdp.py
cookies_nodriver_*.json / cookies_nodriver_*.txtbypass_nodriver.py
cookies_curl_*.json / cookies_curl_*.txtbypass_curl_cffi.py

JSON example / JSON 示例

{
  "url": "https://example.com",
  "cookies": {
    "cf_clearance": "..."
  },
  "user_agent": "Mozilla/5.0 ...",
  "timestamp": "20260714_120000",
  "method": "seleniumbase_uc"
}

cf_clearance is frequently bound to IP + User-Agent. Changing either often requires a new solve.

cf_clearance 常与 IP + User-Agent 绑定。更换任一端通常需要重新求解。


Project Layout / 项目结构

cloudflare-bypass-2026/
├── bypass.py                 # Method 1: SeleniumBase UC (default)
├── simple_bypass.py          # Method 2: parallel + proxy rotation
├── bypass_nodriver.py        # Method 3: nodriver CDP
├── bypass_curl_cffi.py       # Method 4: TLS fingerprint (non-Turnstile)
├── bypass_cdp.py             # Method 5: SeleniumBase CDP Mode
├── bypass_seleniumbase.py    # UC class wrapper
├── install_linux.sh          # Linux bootstrap
├── requirements.txt          # Python dependencies
├── proxy.txt                 # Sample proxy list
├── LICENSE
├── README.md
└── output/                   # Runtime cookie exports (created on use)

FAQ / 常见问题

Which method should I use first?
优先使用哪个方案?

Start with bypass.py or bypass_cdp.py. Use bypass_nodriver.py when you want a chromedriver-free CDP stack. Use simple_bypass.py for batch/proxy rotation. Do not use bypass_curl_cffi.py for Turnstile.

优先 bypass.py 或 bypass_cdp.py。需要无 chromedriver 的 CDP 时用 bypass_nodriver.py。批量与代理轮换用 simple_bypass.py。Turnstile 不要使用 bypass_curl_cffi.py。


Why avoid true headless mode?
为什么避免真无头模式?

Automation headless profiles are easier to fingerprint. On Linux servers without a desktop, use Xvfb / virtual display (install_linux.sh, pyvirtualdisplay, or SeleniumBase xvfb=True) instead of Chrome headless.

无头自动化特征更容易被识别。无桌面的 Linux 请使用 Xvfb / 虚拟显示,而不是 Chrome 真无头。


How long does cf_clearance last?
cf_clearance 有效期多久?

Typically tens of minutes to several hours, depending on site policy. It is often tied to IP and UA; proxy changes frequently invalidate it.

通常数十分钟到数小时,取决于站点策略;常与 IP、UA 绑定,换代理后往往需要重解。


Linux error: X11 / display failed
Linux 报 X11 / display 失败

sudo bash install_linux.sh
# or / 或
sudo apt-get install -y xvfb
pip install pyvirtualdisplay

Proxy does not work
代理不可用

Confirm HTTPS CONNECT support and authentication. Public free lists are mostly unusable for this workload.

确认代理支持 HTTPS CONNECT 与鉴权。公开免费列表对本场景大多不可用。


nodriver reports missing OpenCV
nodriver 提示缺少 OpenCV

pip install opencv-python-headless

Is there a universal bypass?
是否存在通杀方案?

No. Defenses evolve continuously. Outcomes depend on target configuration, egress reputation, browser fidelity, and timing. This toolkit does not claim universal success.

没有。防御持续演进。结果取决于目标配置、出口信誉、浏览器还原度与时机。本工具不宣称通杀。


References / 参考资料


Business / 商务合作

Sponsorship placement, custom development, and technical consulting are welcome.

欢迎洽谈赞助展示、定制开发与技术咨询。

Channel / 渠道Contact / 联系方式
WeChat / 微信1837620622 (传康Kk)
Email / 邮箱2040168455@qq.com
Xianyu / Bilibili万能程序员

Please contact via WeChat first and note Business / 商务合作.

请优先微信联系,并备注「商务合作」。


License / 许可证

  • Repository code is distributed under the MIT License (see LICENSE).

  • nodriver is licensed under AGPL-3.0. Using Method 3 requires compliance with that license.

  • 本仓库代码按 MIT License 分发(见 LICENSE)。

  • nodriver 上游为 AGPL-3.0。使用方案 3 时须遵守其许可证。


If this project is useful, consider starring the repository.

如果本项目对你有帮助,欢迎 Star 支持。

关于 About

Cloudflare Turnstile 绕过工具 | Cloudflare Bypass Tool based on SeleniumBase UC Mode | 支持 Mac/Windows/Linux
automationbypasscloudflarepythonseleniumturnstile

语言 Languages

Python96.7%
Shell3.3%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
6
Total Commits
峰值: 3次/周
Less
More

核心贡献者 Contributors