cfsolve: Cloudflare Turnstile 解決用 Rust ライブラリ

cfsolve は、ヘッドレスブラウザを使わずに Cloudflare Turnstile ウィジェットや挑戦ページを解決するための Rust ライブラリおよびコマンドラインツール です。

機能と出力

• Turnstile ウィジェットの場合: Turnstile トークンを返し、ログイン処理を完了させます。
• 挑戦ページの場合:

  cf_clearance

  クッキーを返し、保護されたページへのアクセスを可能にします。
• 解決方法の違い:
  • ウィジェット: ページ URL、sitekey を使用。HTML は不要なケースが多いです。
  • 挑戦ページ: ページへの直接アクセスまたはその HTML が必須です。

ブラウザのプロフィール管理

cfsolve は、特定ブラウザを模擬するための プロフィールファイル を利用します（例：

profiles/safari-26-ios.json

プロフィールの注意点

• 保存時のルール: コピーする際は、必ずプロフィールとその関連ディレクトリも一緒に移動させてください。プロフィールは挑戦時のブラウザチェックに対する記録された応答を参照しています。
• 生成方法:
  • 通常は手動作業または AI を活用する必要があります。
  • キャプチャプロキシを設定して実際のブラウザで問題に解決することで、Cloudflare に送信されたデコード済みのペイロードを自動記録し生成をサポートできます。
  • 現在サポートされているタイプ：Safari および Chrome (iium) のみです。

コマンドラインツールの使い方

基本コマンド

cargo build --release --bin challenge

実行例

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

動作仕様:

• 成功時: トークン（または

  cf_clearance

  ）を標準出力に、進行状況を標準エラー出力に表示。
• ディレクトリ引数 (

  /tmp/solve

  ): デバッグ用リクエスト・応答を保持するため、空または既存である必要があります。
• デフォルト動作: ページ内の最初のウィジェット解決、または挑戦ページクリア。
  • 複数のウィジェットがある場合:

    --sitekey

    で特定を選択します。
  • サイト固有の設定:

    action

    および

    cData

    も含める必要があります。

Sitekey を指定したケース

特定のサイトキーを指定する場合の例：

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

空白のページ: Sitekey のみを持つ場合、以下のオプションを追加してください。

--blank-page --page <actual_site_url>

オプション一覧

--fingerprint <file>

--page <url>

--solve

--sitekey <key>

--action <value>, --cdata <value>

--sitekey

--blank-page

--solve

--sitekey

--proxy <url>

http://

https://

socks5://

socks5h://

-h, --help

ライブラリとしての使用法

パッチ適用と依存関係

Cargo.toml

[patch]

[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

  を指定することで、内部コマンドツールが無効化され、ソルバー機能のみが動作します。
• Rust バージョンは

  rust-toolchain.toml

  に記載されたもの（またはそれより新しい）を使用してください。

コード実装例

基本的な解決処理

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

Sitekey または独自 HTML を持つ Turnistle

URL と sitekey のみの場合、

PageSource::Blank

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?;

設定のポイント:

• Action/CData: サイトが設定する値に従ってください。未設定の場合は

  None

  にします。
• 複数のウィジェット:

  PageSource::Navigate

  と共に特定の

  Widget

  を渡して選択可能です。
• 読み込んだページ: 既に HTML を持つ場合（例：ログイン画面裏側）、

  PageSource::Html

  で URL と HTML を渡します。

クリアランスのルール

• プロファイルと同じ IP アドレスとユーザーエージェントから

  cf_clearance

  クッキーを送信する必要があります。これ否则 Cloudflare は拒否します。

チャンレンジ（挑戦）ページの処理

明確なケース別処理

• ブラウザがフェッチ:

  browser.clear(&url, &options)

  を使用。返却された

  Clearance

  にクッキーと保護ページが含まれます。
  • 挑戦が存在しない場合は

    Error::NotChallenged

    で失敗します。
  • 外部でフェッチしたページは、

    FetchedPage

    を渡して処理可能です。

ユーニバーサル解決 (

browser.solve

)

URL の種類が不明な場合や両方をカバーしたい場合に使用します：

use cfsolve::Outcome;

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

オプション（プロキシとログ出力）

プロキシ設定

各操作ごとに

Options

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

ログとデバッグ出力（Sink）

ライブラリ操作はデフォルトでサイレントです。進行状況やデバッグファイルを取得するには

Sink

options.sink

let options = cfsolve::Options {
    sink: Some(Arc::new(your_sink)),
    ..Default::default()
};

エラーハンドリング

Error::Network

Error::Rejected

Error::Blocked

Error::Challenged

Error::NotChallenged

Error::Config

Error::Unsupported

ライセンス

• ソースコード：MIT ライセンス。
• 例外:

  vendor/

  内のパッチ済み依存関係については、それぞれの元のライセンスが維持されます。