Cloudflare Turnstile Nedir? Modlar, Token ve Doğrulama

what is cloudflare turnstile - What Is Cloudflare Turnstile? Modes, Token and Verification

Cloudflare Turnstile nedir? Cloudflare’ın CAPTCHA alternatifidir: ziyaretçiyi resim bulmacaları yerine arka planda çalışan testlerle denetler ve ziyaretçi geçtiğinde sayfaya, sitenin sunucusunun Cloudflare ile doğruladığı bir token verir. Bu kılavuz üç widget modunu, token’ı ve sınırlarını, doğrulamanın nasıl çalıştığını ve widget ile tam sayfa challenge’ı nasıl ayırt edeceğinizi anlatır.

Ziyaretçinin gördüğü: üç widget modu

Cloudflare üç modu tanımlar, bkz. widget dokümantasyonu. Site sahibi widget’ı oluştururken bunlardan birini seçer.

ModZiyaretçinin gördüğü
Managed modeCloudflare, etkileşimsiz bir denetim ile bir onay kutusu arasında seçim yapar; bu yüzden onay kutusu yalnızca ek bir denetim gerektiğinde görünür
Non-interactive modeDenetimler çalışırken yükleme göstergesi olan bir widget; ziyaretçiden hiçbir şey yapması istenmez
Invisible modeHiçbir şey yok: ne widget ne de gösterge var, denetimler arka planda çalışır

Üçü de ziyaretçiden bozuk metin okumasını ya da resim seçmesini istemez. Cloudflare genel bakışına göre bir site, widget’ı kullanmak için trafiğini Cloudflare üzerinden geçirmek zorunda değildir, ama sahibinin bir widget oluşturmak için Cloudflare hesabına ihtiyacı vardır.

Cloudflare Turnstile sayfaya ne verir? Bir token

Bir geliştirici için konu şuna iner: cf-turnstile-response adlı bir form alanı, sunucuda bir doğrulama çağrısı ve onu kullanan bir siteyi otomatikleştirirken kendinizin sağlamanız gereken bir token. Widget bir formun içindeyse Cloudflare, cf-turnstile-response adlı görünmez bir input eklediğini ve bunun diğer alanlarla birlikte sunucuya gittiğini söyler. Widget örtük olarak render edilebilir; bu durumda işaretlemede cf-turnstile sınıfına sahip bir öğe arar. Ya da sayfa script’inden turnstile.render() çağrısıyla açıkça render edilebilir. Açıkça render eden bir sayfa ayrıca bir callback verebilir ve CapSkip API belgeleri, sayfa bir callback tanımlıyorsa onu dönen token ile çalıştırmanızı söyler.

Token kısa ömürlüdür. Sunucu tarafı doğrulama kılavuzu her token’ın 300 saniye geçerli ve tek kullanım için tasarlanmış olduğunu, Cloudflare’ın da kullanımı ağı genelinde gecikmeyle izlediğini söyler. Bu yüzden uzun bir script’in başında istediğiniz token, form gönderilene kadar harcanmış ya da bayatlamış olabilir.

Sunucu token’ı nasıl doğrular

Alanın ulaşması tek başına hiçbir şey kanıtlamaz. Cloudflare sunucu tarafı doğrulamayı zorunlu tutar: site, token’ı ve gizli anahtarını Cloudflare’a iletmek için siteverify endpoint’ini, yani https://challenges.cloudflare.com/turnstile/v0/siteverify adresini, POST ile çağırır ve bir JSON yanıtı okur. Belgelenmiş değerler aşağıdadır.

YönDeğerAnlamı
Gönderilensecret (zorunlu)Widget’ın gizli anahtarı
Gönderilenresponse (zorunlu)Form alanından gelen token
Gönderilenremoteip (isteğe bağlı)Ziyaretçinin IP adresi
Gönderilenidempotency_key (isteğe bağlı)Aynı denetimin yeniden denenmesini güvenli kılmak için oluşturduğunuz bir UUID
DönensuccessDoğrulamanın geçip geçmediği
Dönenchallenge_ts, hostnameChallenge’ın ne zaman çözüldüğü ve nerede sunulduğu
Dönenerror-codesmissing-input-response ya da timeout-or-duplicate gibi bir liste
Dönenaction, cdataSayfanın widget’a ayarladığı özel değerler

Cloudflare yedi hata kodu listeler ve ikisi burada önemlidir. missing-input-response kodu Cloudflare’a hiç token ulaşmadığı, timeout-or-duplicate ise token’ın süresinin dolduğu ya da zaten doğrulandığı anlamına gelir. Belgelenmiş yanıt skor taşımaz: sonuç geçti ya da kaldı şeklindedir ve yanında, sunucunun kontrol edebilmesi için sayfanın ayarladığı action ve cdata değerleri bulunur. Bu, belgelenmiş alanların bir okumasıdır; Cloudflare’ın hiçbir zaman neyi döndürmediğine dair bir açıklama değildir.

Widget mı challenge sayfası mı: bu hangi Turnstile?

Widget bir şeydir, tam sayfa challenge başka bir şey. Widget, zaten yüklenmiş bir sayfadaki bir öğedir. Challenge sayfası ise Cloudflare’ın, herhangi bir içerik gelmeden önce site yerine gösterdiği sayfadır. Cloudflare’ın clearance belgeleri, böyle bir challenge’ı çözmenin ziyaretçiye ve cihaza bağlı bir cf_clearance cookie’si ayarladığını söyler. Ayrıca pre-clearance etkin bir widget’ın o cookie’yi verebildiğini, varsayılanda ise widget’ın tek seferlik bir token verdiğini belirtir. Neye baktığınıza karar vermek için bu tabloyu kullanın.

GördüğünüzNe olduğuCapSkip’in sizden istediği
Bir formun içinde kutu ya da yükleme göstergesi ve HTML’de bir cf-turnstile-response input’uManaged ya da non-interactive modda widgetSitekey ve tam sayfa adresi. Token alana girer
Token olmadan başarısız olan bir form, ama ekranda kutu yokInvisible modda widget ya da render edilmemiş bir widgetAynı iki değer. Sitekey’i işaretlemede ya da render çağrısında bulun
Site yüklenmeden önce "Just a moment" yazan tam bir sayfaTam sayfa challengeİki CapSkip yolu. Sayfa action, data ve pagedata değerlerini turnstile.render fonksiyonuna veriyorsa bunları taşıyan bir Turnstile token isteği ya da aşağıda anlatılan cf_clearance cookie isteği

CapSkip’ten Turnstile token’ı almak

CapSkip kendi Windows bilgisayarınızda çalışır, 127.0.0.1:8080 adresinde 2captcha istek biçiminde yanıt verir ve lisanslı bir kopyada çözüm başına ücret yoktur. Cloudflare Turnstile çözücü sayfası ürünü anlatır ve API belgeleri burada kullanılan parametreleri listeler. Script’iniz başka bir makinede çalışıyorsa CapSkip’i Server moduna alın ve o bilgisayarın adresini host olarak kullanın. Kurulum kılavuzunun bağlantı ayarları bölümü bunu anlatır. CapSkip, Server modu başladığında portunu her adrese açar; bu yüzden portu yalnızca beklediğiniz makinelere ayırmak için diğerlerine karşı bir Windows Güvenlik Duvarı engelleme kuralı ekleyin.

İşte widget isteği elle. Metot turnstile, API belgeleri ise zorunlu değerler olarak sitekey ve pageurl değerlerini listeler. Her çağrı, PowerShell’in yazıldığı gibi çalıştırdığı tek satırlık bir curl.exe’dir. cmd’de diyez ile başlayan satırları dışarıda bırakın.

# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}

# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}

Aynı görev Python SDK ile tek bir çağrıdır. Görevi gönderir, yoklar ve code değeri cf-turnstile-response alanının token’ı olan bir sözlük döndürür.

# python -m pip install capskip
from capskip import CapSkip

# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)

result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")

print(result["code"])  # the token for the cf-turnstile-response field
print(result.get("userAgent"))  # the User-Agent to send with it

API belgeleri, CapSkip’in Turnstile’ı belirli bir tarayıcı User-Agent’ı ile çözdüğünü ve token’ı gönderirken aynısını göndermeniz gerektiğini söyler. JSON yanıtında bunu userAgent olarak taşır, düz metin modunda ise X-Turnstile-User-Agent yanıt başlığı olarak gelir. SDK JSON yanıtı ister; bu yüzden değeri sonuçtan okuyun ve token’ı taşıyan isteğe koyun.

Challenge sayfası isteği

Bir challenge sayfası için API belgeleri üç değer daha vermenizi ister; bunları sayfanın turnstile.render() fonksiyonuna verdiği argümanlardan okursunuz. Sayfanın tanımladıklarını gönderin, boş olanları göndermeyin. Belgeler, o fonksiyonu geçersiz kılan ve argümanları yazdıran kısa bir script içerir.

İstek değeriSayfanın onu tuttuğu yer
actiondata-action özniteliği ya da render çağrısındaki action
dataRender çağrısındaki cData değeri ya da data-cdata özniteliği
pagedataRender çağrısındaki chlPageData değeri
# python -m pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)

# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
    "YOUR_SITEKEY",
    "https://example.com/protected",
    action="managed",
    data="YOUR_CDATA",
    pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))

action için managed değeri API belgelerindeki örnek istekten kopyalanmıştır; bu yüzden sayfanızın tanımladığı action ne ise onu kullanın.

Cookie yolu farklı bir istektir. API belgeleri onu, "Just a moment" yazan tam sayfa için Cloudflare Challenge (cf_clearance) başlığı altında listeler. Yalnızca JSON createTask API’si üzerinden çalışır, Cloudflare ayarları altında Return cf_clearance cookies açılana kadar kapalıdır ve her istek, sonradan kullanacağınız proxy’yi belirtmelidir. Python SDK’sında bunun için bir çağrı yoktur; bu yüzden işte istek, API belgelerinin yazdığı biçimde ve PowerShell ile gönderilmiş olarak. Proxy değeri belgelerdeki yer tutucudur.

# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body

# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")

$result.solution.cookies.cf_clearance
$result.solution.userAgent

Challenge’dan sonra siteyi sıradan HTTP istekleriyle almak istediğinizde cookie isteğini kullanın. API belgeleri bu durumu, kendi tarayıcısı olmayan bir script ya da araç için tarif eder ve cookie’yi aynı proxy üzerinden ve aynı User-Agent ile göndermenizi söyler. Token isteği, turnstile.render() çağıran ve bir callback’i ya da token kabul eden bir alanı olan bir sayfaya uyar. Token isteği için bu eşleştirme, belgelerin iki bölümünden çıkarılmış bir sonuçtur; belgelerin bir ifadesi değildir.

Cookie’yi Python’da yeniden kullanmak için bkz. cf_clearance cookie’leri nasıl yeniden kullanılır. Koddaki token isteği için bkz. Node.js kılavuzu. PHP sürümü şurada: PHP’de Turnstile çözme, C# sürümü ise şurada: C# challenge sayfası kılavuzu.

Ne çalıştırdım ve bu neyi göstermez

Dört kod bloğunun hepsini CapSkip’i oynayan bir mock’a karşı, capskip 1.7.0 ile Python 3.11.7, 3.13.7 ve 3.14.0 üzerinde, iki PowerShell bloğunu da Windows PowerShell 5.1’de çalıştırdım. Gerçek uygulamaya hiçbir görev göndermedim; bu yüzden burada hiçbir şey gerçek bir Turnstile sayfasının nasıl yanıt verdiğini ya da gerçek uygulamanın bir widget için ne döndürdüğünü göstermez.

Mock’a karşı denetimSonuç
Python widget çağrısıturnstile metoduyla, sitekey ve sayfa adresiyle tek bir görev; sonuçta token ve User-Agent geri geldi
Python challenge sayfası çağrısıAynı görev ayrıca action, data ve pagedata değerlerini, verildiği gibi taşıdı
İki Python bloğu da tek bir dosyaya yapıştırıldıİki görev de gönderildi ve geri okundu
PowerShell’de cookie yoluMock, AntiCloudflareTask türünü, sayfa adresini ve proxy’yi gördü. Bir kez processing yanıtı verdi, ardından blokun yazdırdığı cookie’yi ve User-Agent’ı döndürdü
curl.exe ile gönderim, sonra yoklamaİlk yoklama görevin hazır olmadığını söyledi, ikincisi token’ı döndürdü

FAQ

Bir Turnstile token’ı ne kadar geçerli kalır?

Cloudflare 300 saniye der ve token’lar tek kullanım için tasarlanmıştır. Token’ı CapSkip’ten, form gönderilmeden hemen önce isteyin.

Turnstile, bir site yüklenmeden önceki Cloudflare denetimiyle aynı şey mi?

Hayır. Widget bir sayfanın içinde yaşar ve token üretir. Tam sayfa challenge ise sayfanın yerini alır ve bir cf_clearance cookie’si ile biter. Yukarıdaki karar tablosu ikisini nasıl ayırt edeceğinizi gösterir.

Kod yazmadan önce bir Turnstile widget’ı görebilir miyim?

Evet. Canlı bir widget’ı ve doldurduğu alanı görmek için Turnstile demo sayfasını açın.

Çözücüyü başka bir bilgisayardan çağırabilir miyim?

Evet, Server modu ile. CapSkip’i çalıştıran bilgisayarın adresini host olarak kullanın ve ona ulaşmaması gereken her adres için bir Windows Güvenlik Duvarı engelleme kuralı ekleyin. Çözücü yine kendi Windows donanımınızda çalışır.

Kısa özet

Kısacası, Cloudflare Turnstile nedir? Sitenin Cloudflare ile denetlediği, cf-turnstile-response içindeki bir token ve onun yanında cookie ile biten ayrı bir tam sayfa challenge. Token’ı ya da cookie’yi kendi kodunuzdan sağlamak için CapSkip gibi yerel bir captcha atlatma aracı bunu kendi bilgisayarınızda, sabit bir lisansla ve çözüm başına ücret olmadan yapar.