go-cfscraper

README

go-cfscraper

A Go library for bypassing Cloudflare's anti-bot protection with both TLS fingerprinting and JS challenge solving.

Forked from Advik-B/cloudscraper (a Go port of the Python VeNoMouS/cloudscraper), which provides the JS challenge solving engine. This fork replaces the default net/http transport with sardanioss/httpcloak to add TLS fingerprinting (JA3/JA4 + HTTP/2 browser profiles), which the original library lacked.

Pure Go with no external runtime dependencies by default. Uses a built-in JS interpreter (goja) to solve Cloudflare challenges. Optionally supports Node.js, Deno, or Bun for advanced challenges.

Features

Feature	Status	Description
Standalone Binary	✅	Uses a pure Go JS interpreter (goja) by default. No Node.js required.
External JS Runtimes	✅	Supports Node.js, Deno, or Bun for maximum compatibility.
Session & Cookie Handling	✅	Automatically manages cookies for Cloudflare sessions.
JS Challenge Solver (v1)	✅	Solves classic JavaScript math-based challenges.
JS Challenge Solver (v2/v3)	✅	Simulates a browser DOM to solve modern JS VM challenges.
Stealth Mode	✅	Human-like delays, header randomization, browser-specific quirks.
Proxy Management	✅	Thread-safe proxy manager with sequential, random, and smart rotation.
403 Recovery	✅	Automatically recovers from 403 errors by refreshing the session.
Captcha Solver	✅	Extensible Solver interface with a 2captcha implementation.
Thread-Safe	✅	Safe for concurrent use from multiple goroutines.

Installation

go get github.com/sriharsha-y/go-cfscraper/lib

Basic Usage

package main

import (
	"context"
	"fmt"
	"log"

	cloudscraper "github.com/sriharsha-y/go-cfscraper/lib"
)

func main() {
	sc, err := cloudscraper.New()
	if err != nil {
		log.Fatalf("Failed to create scraper: %v", err)
	}
	defer sc.Close()

	resp, err := sc.Get(context.Background(), "https://nowsecure.nl")
	if err != nil {
		log.Fatalf("Request failed: %v", err)
	}

	fmt.Printf("Status: %d\n", resp.StatusCode)
	fmt.Printf("Body: %s\n", string(resp.Body[:min(len(resp.Body), 500)]))
}

Advanced Configuration

External JavaScript Runtimes

import (
	cloudscraper "github.com/sriharsha-y/go-cfscraper/lib"
	"github.com/sriharsha-y/go-cfscraper/lib/js"
)

sc, err := cloudscraper.New(
	cloudscraper.WithJSRuntime(js.Node), // or js.Deno, js.Bun
)

Proxies

import (
	"time"
	cloudscraper "github.com/sriharsha-y/go-cfscraper/lib"
	"github.com/sriharsha-y/go-cfscraper/lib/proxy"
)

sc, err := cloudscraper.New(
	cloudscraper.WithProxies(
		[]string{"http://user:pass@proxy1:8080", "http://user:pass@proxy2:8080"},
		proxy.Random,
		5*time.Minute,
	),
)

Captcha Solver

import (
	cloudscraper "github.com/sriharsha-y/go-cfscraper/lib"
	"github.com/sriharsha-y/go-cfscraper/lib/captcha"
)

solver := captcha.NewTwoCaptchaSolver("YOUR_2CAPTCHA_API_KEY")
sc, err := cloudscraper.New(
	cloudscraper.WithCaptchaSolver(solver),
)

Browser & Stealth Configuration

import (
	"time"
	cloudscraper "github.com/sriharsha-y/go-cfscraper/lib"
	"github.com/sriharsha-y/go-cfscraper/lib/stealth"
	useragent "github.com/sriharsha-y/go-cfscraper/lib/user_agent"
)

sc, err := cloudscraper.New(
	cloudscraper.WithBrowser(useragent.Config{
		Browser:  "firefox",
		Platform: "linux",
		Desktop:  true,
	}),
	cloudscraper.WithStealth(stealth.Options{
		Enabled:         true,
		MinDelay:        1 * time.Second,
		MaxDelay:        5 * time.Second,
		HumanLikeDelays: true,
	}),
)

Session Configuration

sc, err := cloudscraper.New(
	cloudscraper.WithSessionConfig(
		true,           // Auto-refresh on 403
		30*time.Minute, // Refresh interval
		5,              // Max 403 retries
	),
)

How It Works

1. Initial Request — makes a request to the target URL
2. Challenge Detection — checks for Cloudflare 503/403 responses
3. Challenge Solving — uses the JS engine to compute the answer (v1/v2/v3 challenges) or delegates to a captcha solver
4. Cookie Handling — stores the cf_clearance cookie for subsequent requests
5. Retry — retries the original request with the clearance cookie

Attribution

This project builds on the work of:

• Advik-B/cloudscraper — Go port of the Python cloudscraper library. Provides the JS challenge solving engine (goja VM, DOM shims, PoW solver, challenge detection). The core challenge-solving code is preserved from this project.
• VeNoMouS/cloudscraper — The original Python library that pioneered Cloudflare bypass techniques.
• sardanioss/httpcloak — HTTP client with TLS fingerprinting (JA3/JA4) and browser profile emulation. Used as the HTTP transport layer.

License

MIT License — see LICENSE.txt