cfsolve README

README проекта с github.com/chris124567/cfsolve. Одним файлом markdown: README.md.

cfsolve

cfsolve is a Rust library and command line tool that solves Cloudflare Turnstile widgets and challenge pages without a headless browser. It returns a Turnstile token for widgets or a cf_clearance cookie for challenge pages.

Turnstile widgets can be solved using the page URL, the sitekey, and optionally the page's HTML (this should not be required in most cases). Challenge pages require a direct fetch or the HTML of the page.

Browser profiles

cfsolve impersonates a specific browser, described by a profile file. One is included: profiles/safari-26-ios.json (Safari on iPhone).

Each profile references recorded responses to the challenge's browser checks, stored as JSON in a directory. Keep each profile with its directory when you copy. Producing these files requires some manual (or AI) effort though it can be greatly aided by solving challenges in a real web browser with the proxy set to the address of a running capture-proxy, which records the decoded payloads sent to Cloudflare. Currently only Safari and Chrome(ium) profile types are supported.

Building

You need the Rust version pinned in rust-toolchain.toml, plus CMake, a C/C++ compiler, libclang, and Git (to patch and build BoringSSL).

cargo build --release --bin challenge

Command line tool

./target/release/challenge --page 'https://example.com/login' /tmp/solve \
  --solve --fingerprint profiles/safari-26-ios.json

On success it prints the token (or cf_clearance=...) and sends progress to stderr. The directory argument holds all requests and responses for debugging, so it must be empty or not exist yet.

By default it solves the first Turnstile widget on the page, or clears the challenge page. To pick one widget when the page has several, pass its sitekey, with its action and cData when the site sets them. With --sitekey, it fails on a challenge page.

./target/release/challenge --page 'https://example.com/login' /tmp/solve \
  --solve --fingerprint profiles/safari-26-ios.json \
  --sitekey 'SITEKEY' --action 'login' --cdata 'CUSTOM_DATA'

If you only have a sitekey, add --blank-page and set --page to the site's real URL.

Option Description
--fingerprint <file> Browser profile file to use. Required.
--page <url> The page with the widget, or the challenge page.
--solve Solve the widget or challenge. Without this, cfsolve stops after sending the widget's first payload.
--sitekey <key> Select a widget by sitekey.
--action <value>, --cdata <value> Override the widget's action and cData. This needs --sitekey.
--blank-page Skip loading the page. Render the widget on a blank page at the page URL. This needs --solve and --sitekey.
--proxy <url> Send every request through an http://, https://, socks5://, or socks5h:// proxy. Put credentials in the URL, as in socks5h://user:password@host:1080.
-h, --help Show help.

Library

Add cfsolve as a path dependency and copy its [patch] section, since Cargo only reads patches from the top-level Cargo.toml:

[dependencies]
cfsolve = { path = "/path/to/cfsolve", default-features = false }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

[patch.crates-io]
btls-sys = { path = "/path/to/cfsolve/vendor/btls-sys" }
wreq = { path = "/path/to/cfsolve/vendor/wreq" }
http2 = { path = "/path/to/cfsolve/vendor/http2" }

default-features = false turns off the internal tools so only the solver remains. Use the Rust version in rust-toolchain.toml or newer.

use cfsolve::{Browser, Options, PageSource, Turnstile};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let browser = Browser::read("/path/to/cfsolve/profiles/safari-26-ios.json")?;
    let options = Options::default();

    let turnstile = Turnstile {
        url: "https://example.com/login".parse()?,
        page: PageSource::Navigate,
        widget: None,
    };
    let token = browser.solve_turnstile(turnstile, &options).await?;
    println!("{token}");

    let cleared = browser.clear(&"https://example.com/".parse()?, &options).await?;
    println!("cf_clearance={}", cleared.clearance);
    println!("{} cookies; protected page: {}", cleared.cookies.len(), cleared.page.url);
    Ok(())
}

Load a Browser once and share it. Concurrent operations each get their own connections and cookies.

Send the cf_clearance cookie from the same IP address and user agent as the profile, or Cloudflare will reject it.

Turnstile with a sitekey or your own HTML

PageSource::Navigate fetches the page. With only a URL and sitekey, use PageSource::Blank and specify the widget:

use cfsolve::{PageSource, Turnstile, Widget};

let turnstile = Turnstile {
    url: "https://example.com/login".parse()?,
    page: PageSource::Blank,
    widget: Some(Widget {
        sitekey: "SITEKEY".into(),
        action: Some("login".into()),
        cdata: None,
    }),
};
let token = browser.solve_turnstile(turnstile, &options).await?;

Set action and cdata to the values the site uses, or None when the site doesn't set them. You can also pass a Widget with PageSource::Navigate to pick one widget out of several or to supply one the site adds with JavaScript.

For a page you have already loaded, such as one behind a login, pass its URL and HTML:

PageSource::Html {
    html: std::fs::read_to_string("account.html")?,
    referrer_policy: None, // Or the response's Referrer-Policy header.
}

The widget runs in a cross-site iframe, so you don't need your login cookies. With Html, widget: None solves the first widget on the page, while Blank always needs a Widget and renders it on a blank page at the site's URL.

Challenge pages

browser.clear(&url, &options) fetches the page and clears the challenge. The Clearance it returns contains the cf_clearance cookie, all cookies for the page, and the protected page. It fails with Error::NotChallenged when there's no challenge.

If you fetched the challenge page yourself, pass the response as a FetchedPage to browser.clear_fetched(page, &options). Use the same IP and user agent as the profile.

If you don't know whether a URL shows a widget or a challenge page, use browser.solve, which covers both cases:

use cfsolve::Outcome;

match browser.solve(&url, &options).await? {
    Outcome::Token(token) => println!("{token}"),
    Outcome::Cleared(cleared) => println!("cf_clearance={}", cleared.clearance),
}

Options

Set a proxy per operation through Options, using HTTP, HTTPS, or SOCKS5:

let options = cfsolve::Options {
    proxy: Some("socks5h://127.0.0.1:1080".into()),
    ..Default::default()
};

Library operations are silent by default. For progress messages and debug files, implement Sink and set options.sink to Some(Arc::new(your_sink)).

Errors

Error Cause Retry?
Error::Network Connection failed. Yes
Error::Rejected Cloudflare rejected the solution. Yes
Error::Blocked The site returned an error page instead of a challenge. No
Error::Challenged You asked for a Turnstile token but got a challenge page. Yes, after clearing it
Error::NotChallenged You asked for a challenge clearance but there was no challenge. No
Error::Config Invalid profile or options. No
Error::Unsupported Any other failure, such as a new challenge build or a page with no widget. No

Contributions (new policy as of 2026-11-07)

Thank you to everyone who has contributed via pull requests. Unfortunately, there has been a very large volume of them, which I lack the time to meaningfully review. For that reason I would encourage you to fork the project instead. I will not be maintaining this a few weeks from now, so forking will become necessary regardless. If you think an exception should be made in the mean time, please email me.

License

MIT, except for the patched dependencies in vendor/, which keep their own licenses.

cfsolve (chris124567/cfsolve)

Ищем в базе…

Что это такое?Библиотека и инструмент командной строки на Rust, которые решают виджеты Cloudflare Turnstile и страницы проверки без безголового браузера. Для виджетов возвращается токен Turnstile, для страниц проверки — cookie cfclearance.
Это библиотека, CLI или и то, и другое?И то, и другое. Можно добавить её в проект на Rust как зависимость по локальному пути или запустить инструмент командной строки напрямую с --fingerprint и --page.
Как это запустить?Соберите из исходников: установите версию Rust, закреплённую в rust-toolchain.toml, а также CMake, компилятор C/C++, libclang и Git, затем соберите репозиторий. Запускайте CLI с --fingerprint (файл профиля), --page (URL) и --solve и передайте каталог для отладки, который пуст или ещё не существует.
Какие браузеры можно имитировать?Пока поддерживаются только типы профилей Safari и Chrome(ium). Создание нового профиля требует записи ответов реального браузера на проверки Cloudflare, и это делается вручную или с помощью ИИ.
Это всегда работает?Нет. Решение может быть отклонено Cloudflare или завершиться ошибкой Unsupported, если появилась новая сборка проверки или на странице нет виджета. Если сайт возвращает страницу с ошибкой вместо проверки, ошибка будет Blocked, и повторная попытка не поможет.
Нужен ли безголовый браузер?Нет. Инструмент использует записанные ответы браузера на проверки, которые хранятся в профилях, поэтому решает виджеты и страницы проверки без запуска безголового браузера.
Как выбрать один виджет, если на странице их несколько?Передайте его sitekey через --sitekey и добавьте --action и --cdata, если сайт их задаёт. --sitekey завершится ошибкой, если страница является страницей проверки.
Что библиотека возвращает для страницы проверки?clear() возвращает Clearance с cookie cfclearance, все cookie для страницы и защищённую страницу. Если проверки нет, возвращается ошибка NotChallenged.
Как создать профиль для нового браузера?Пройдите проверки в реальном браузере, указав в его прокси запущенный capture-proxy, который записывает декодированные данные, отправленные Cloudflare. Файлы профиля затем создаются по этим записям вручную или с помощью ИИ.
Автор
chris124567
Размер
7.1 MB
Звёзды
800
Обновлён
КоммитNov 17
Возраст
23 д
Коммиты · 90 дней