Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(autosolver): stop classifying pages about captchas as captchas

Darshan Jain7eccb80d51db
diff --git a/internal/autosolver/challenge_detection.go b/internal/autosolver/challenge_detection.go
index ffbd6aac..fd947e9e 100644
--- a/internal/autosolver/challenge_detection.go
+++ b/internal/autosolver/challenge_detection.go
@@ -55,9 +55,7 @@ func DetectChallengeIntent(title, url, html string) *Intent {
}
}
- if containsAny(lowerTitle, "captcha", "verify you are human", "i am not a robot") ||
- containsAny(lowerURL, "captcha", "recaptcha", "hcaptcha", "turnstile") ||
- containsAny(lowerHTML, "captcha", "verify you are human", "i am not a robot") {
+ if isGenericCaptcha(lowerTitle, lowerURL, lowerHTML) {
return &Intent{
Type: IntentCaptcha,
Confidence: 0.7,
@@ -69,19 +67,69 @@ func DetectChallengeIntent(title, url, html string) *Intent {
return nil
}
+// isGenericCaptcha is the last rung: no vendor was identified, so all that is left
+// is the word itself. It applies the same rule the vendor checks above do — the
+// title and the URL are guesses, and a guess is only worth making when there is no
+// page to check it against.
+//
+// Every branch used to be sufficient on its own, and the URL branch listed
+// "turnstile", which is a word about stadiums as often as about Cloudflare. An
+// operations report at /ops/turnstile-report, or an article at
+// /blog/how-recaptcha-works, was a captcha challenge as far as this was concerned.
+//
+// What remains deliberately ambiguous is a page whose BODY says "captcha". A
+// vendor comparison and a captcha page both contain the word, and nothing here can
+// separate them; 0.7 and a name of "generic" is what that uncertainty is for.
+func isGenericCaptcha(title, url, html string) bool {
+ if containsAny(html, "captcha", "verify you are human", "i am not a robot") {
+ return true
+ }
+ if html == "" {
+ return containsAny(title, "captcha", "verify you are human", "i am not a robot") ||
+ containsAny(url, "captcha", "turnstile")
+ }
+ return false
+}
+
func isTurnstileChallenge(title, url, html string) bool {
- return containsAny(title,
- "just a moment",
- "attention required",
- "checking your browser",
- ) || containsAny(url,
+ if containsAny(url,
"cdn-cgi/challenge-platform",
"/cdn-cgi/challenge",
) || containsAny(html,
"challenges.cloudflare.com/turnstile",
"cf-turnstile",
"turnstile.render(",
- )
+ // An interstitial is served AT the address that was asked for, so the
+ // challenge-platform script shows up in the markup while the URL still
+ // looks like the site. Matching it only in the URL meant the real page
+ // was recognised by its title and not by the thing running it.
+ "cdn-cgi/challenge-platform",
+ "__cf_chl_",
+ "cf-browser-verification",
+ ) {
+ return true
+ }
+
+ // The title is a guess, and it is only worth making when there is no page to
+ // check it against. "Attention required" and "just a moment" are ordinary
+ // English: a legal notice headed "Attention Required Before You Sign", or a
+ // support page saying "Just a moment while we finish setup", was being called
+ // a Cloudflare interstitial at 0.95 confidence and sent to the solver instead
+ // of being read.
+ //
+ // An interstitial that reached us WITH its markup always carries a marker
+ // above — the challenge-platform script is what runs it. So once html is in
+ // hand, a bare title match is a coincidence. With no html there is nothing to
+ // corroborate against and the title is all the caller has, which is the mode
+ // heuristics.go asks for by passing url and html empty.
+ if html == "" {
+ return containsAny(title,
+ "just a moment",
+ "attention required",
+ "checking your browser",
+ )
+ }
+ return false
}
func isRecaptchaV3Challenge(url, html string) bool {
@@ -94,8 +142,10 @@ func isRecaptchaV3Challenge(url, html string) bool {
}
func isRecaptchaV2Challenge(url, html string) bool {
+ // Matched a bare "recaptcha" anywhere in the URL, which is a word a URL is
+ // allowed to contain: /blog/how-recaptcha-works was classified as a reCAPTCHA
+ // challenge. The vendor's own host is the signal; the word is not.
return containsAny(url,
- "recaptcha",
"google.com/recaptcha",
) || containsAny(html,
"g-recaptcha",
@@ -106,12 +156,16 @@ func isRecaptchaV2Challenge(url, html string) bool {
}
func isHCaptchaChallenge(url, html string) bool {
+ // Same correction, and the html list had the same flaw more sharply: a bare
+ // "hcaptcha" matches any page that merely NAMES hCaptcha, so vendor
+ // comparisons and docs about captchas were themselves read as captchas. The
+ // script and the widget class stay, because those are the thing rather than
+ // the word for it.
return containsAny(url,
- "hcaptcha",
+ "hcaptcha.com",
) || containsAny(html,
"hcaptcha.com/1/api.js",
"h-captcha",
- "hcaptcha",
)
}
diff --git a/internal/autosolver/challenge_detection_test.go b/internal/autosolver/challenge_detection_test.go
index a6e7ade1..af31918d 100644
--- a/internal/autosolver/challenge_detection_test.go
+++ b/internal/autosolver/challenge_detection_test.go
@@ -325,3 +325,115 @@ func TestDetectChallengeIntent_None(t *testing.T) {
t.Fatalf("expected nil intent, got %+v", intent)
}
}
+
+// Pages that talk about captchas are not captchas.
+//
+// Every case here was classified as a challenge before, most of them at 0.90 or
+// 0.95 — the confidence the detector reserves for having identified a specific
+// vendor. The cost of a false positive is not a wasted call: the agent believes
+// it is blocked, hands the page to a solver or to a human, and never does the
+// thing it was asked to do on a page that was never blocking it.
+//
+// The shared flaw was matching a word rather than the thing the word names.
+// "Attention required" is ordinary English, a turnstile is a thing in a stadium,
+// and a URL is allowed to contain "recaptcha" without being one.
+func TestDetectChallengeIntent_PagesAboutCaptchasAreNotCaptchas(t *testing.T) {
+ for _, tc := range []struct {
+ what string
+ title string
+ url string
+ html string
+ }{
+ {
+ what: "an article explaining reCAPTCHA, named in its own URL",
+ title: "How reCAPTCHA works",
+ url: "https://example.com/blog/how-recaptcha-works",
+ html: `<article><p>A walk through the challenge flow.</p></article>`,
+ },
+ {
+ what: "a legal notice whose heading is ordinary English",
+ title: "Attention Required Before You Sign",
+ url: "https://example.com/legal/notice",
+ html: `<main><p>Please read the following carefully.</p></main>`,
+ },
+ {
+ what: "a support page that asks the reader to wait",
+ title: "Just a moment while we finish setup",
+ url: "https://example.com/support/account-setup",
+ html: `<main><p>Your account is being created.</p></main>`,
+ },
+ {
+ what: "an operations report about actual turnstiles",
+ title: "Stadium turnstile throughput, Q3",
+ url: "https://example.com/ops/turnstile-report",
+ html: `<main><p>Gate counts by entrance.</p></main>`,
+ },
+ } {
+ t.Run(tc.what, func(t *testing.T) {
+ if got := DetectChallengeIntent(tc.title, tc.url, tc.html); got != nil {
+ t.Errorf("classified as %s at %.2f confidence (%s); this page is about captchas, it is not one",
+ got.ChallengeType, got.Confidence, got.Details)
+ }
+ })
+ }
+}
+
+// The corroboration rule cuts one way only: with no page in hand there is nothing
+// to check a title against, so the title still decides. heuristics.go depends on
+// this, calling DetectChallengeIntent(title, "", "") to classify by title alone.
+func TestDetectChallengeIntent_TitleStillDecidesWithNoPage(t *testing.T) {
+ for _, title := range []string{
+ "Just a moment...",
+ "Attention Required! | Cloudflare",
+ "Checking your browser before accessing",
+ } {
+ intent := DetectChallengeIntent(strings.ToLower(title), "", "")
+ if intent == nil {
+ t.Fatalf("%q with no url or html returned no intent; the title-only path is what heuristics.go asks for", title)
+ }
+ if intent.ChallengeType != "turnstile" {
+ t.Errorf("%q classified as %q, want turnstile", title, intent.ChallengeType)
+ }
+ }
+}
+
+// A real interstitial arrives with the script that runs it, so tightening the
+// title never costs a true positive: the markers alone are enough.
+func TestDetectChallengeIntent_RealInterstitialNeedsNoTitle(t *testing.T) {
+ intent := DetectChallengeIntent(
+ "",
+ "https://example.com/",
+ `<script src="/cdn-cgi/challenge-platform/h/b/orchestrate/chl_page/v1"></script>`,
+ )
+ if intent == nil {
+ t.Fatal("a challenge-platform script with no title was not detected")
+ }
+ if intent.ChallengeType != "turnstile" {
+ t.Errorf("classified as %q, want turnstile", intent.ChallengeType)
+ }
+}
+
+// The shape that matters most: a Cloudflare interstitial as actually served —
+// the address the caller asked for, the familiar title, and the script that runs
+// the challenge. Detection must rest on the script, because the title is the part
+// an ordinary page can imitate by accident.
+func TestDetectChallengeIntent_RealCloudflareInterstitial(t *testing.T) {
+ const page = `<!DOCTYPE html><html><head><title>Just a moment...</title></head>
+<body class="no-js">
+<div class="main-wrapper" role="main">
+ <div id="challenge-running">Checking your browser before accessing example.com.</div>
+</div>
+<script src="/cdn-cgi/challenge-platform/h/b/orchestrate/chl_page/v1?ray=8f1a2b3c4d5e"></script>
+</body></html>`
+
+ intent := DetectChallengeIntent("just a moment...", "https://example.com/pricing", strings.ToLower(page))
+ if intent == nil {
+ t.Fatal("a served Cloudflare interstitial was not detected")
+ }
+ if intent.ChallengeType != "turnstile" {
+ t.Errorf("classified as %q at %.2f, want turnstile", intent.ChallengeType, intent.Confidence)
+ }
+ if intent.Confidence < 0.9 {
+ t.Errorf("confidence %.2f is too low for a page carrying the challenge script", intent.Confidence)
+ }
+}
diff --git a/internal/autosolver/semantic/adapter_test.go b/internal/autosolver/semantic/adapter_test.go
index e25bc220..0955ea16 100644
--- a/internal/autosolver/semantic/adapter_test.go
+++ b/internal/autosolver/semantic/adapter_test.go
@@ -166,8 +166,13 @@ var detectIntentGolden = []struct {
{"Home page", "https://example.com/challenge/step", autosolver.IntentCaptcha, "", 0.8, "captcha detected via semantic analysis"},
{"Home page", "https://example.com/verify-me", autosolver.IntentCaptcha, "", 0.8, "captcha detected via semantic analysis"},
{"Home page", "https://example.com/captcha", autosolver.IntentCaptcha, "captcha-generic", 0.7, "generic captcha challenge detected"},
- {"Home page", "https://example.com/recaptcha", autosolver.IntentCaptcha, "recaptcha-v2", 0.9, "reCAPTCHA v2 challenge detected"},
- {"Home page", "https://example.com/hcaptcha", autosolver.IntentCaptcha, "hcaptcha", 0.9, "hCaptcha challenge detected"},
+ // A URL that merely contains a vendor's name, on a page titled "Home page",
+ // used to be named as that vendor's challenge at 0.9. It is a word in a path;
+ // /blog/how-recaptcha-works is the same shape. Naming a vendor is a claim
+ // about the page, and the URL alone does not support one — these land on
+ // generic at 0.7 now, which says captcha-ish without asserting which.
+ {"Home page", "https://example.com/recaptcha", autosolver.IntentCaptcha, "captcha-generic", 0.7, "generic captcha challenge detected"},
+ {"Home page", "https://example.com/hcaptcha", autosolver.IntentCaptcha, "captcha-generic", 0.7, "generic captcha challenge detected"},
{"Log In", "", autosolver.IntentLogin, "", 0.7, "login page detected via semantic title analysis"},
{"Login", "", autosolver.IntentLogin, "", 0.7, "login page detected via semantic title analysis"},
{"Sign In", "", autosolver.IntentLogin, "", 0.7, "login page detected via semantic title analysis"},