cfcrawler - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #llm #machine-learning #deep-learning #linux #awesome #cli #kubernetes #awesome-list #vue #security #ios #openai

cfcrawler

(★ 120)

Cloudflare scraper and cralwer written in Async, In-place library for HTTPX. Crawl website that has cloudflare enabled, easier than ever!

File Explorer

Download Latest Version (.zip)

- - main.yml
  - on-release-main.yml
- __init__.py
- client.py
- py.typed
- tls.py
- types.py
- user_agent.py
- index.md
- modules.md
- __init__.py
- test_ciphers.py
- test_detect.py
- test_rotation.py
.gitignore
.pre-commit-config.yaml
codecov.yaml
CONTRIBUTING.rst
LICENSE
Makefile
mkdocs.yml
poetry.lock
pyproject.toml
README.md
tox.ini
uv.lock

# Installation Guide

1. Get the code

git clone https://github.com/ManiMozaffar/cfcrawler

Downloads the entire project code from GitHub to your computer.

cd cfcrawler

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Python 3 Python is required to use pip.

pip install cfcrawler

Installs the package published on PyPI directly — no need to clone the source.

pip install "cfcrawler[ua]"

Installs the package published on PyPI directly — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install cfcrawler

Installs the package published on PyPI directly — no need to clone the source.

pip install "cfcrawler[ua]"

Installs the package published on PyPI directly — no need to clone the source.

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

4. Make

Medium

Prerequisites

Git Needed to download the project code from GitHub.
Make Usually pre-installed on Linux/macOS. On Windows, install separately (e.g. via MSYS2 or WSL).

make

Compiles the code based on the generated build configuration to produce an executable.

✅ If it finishes without errors, it worked. Try running the generated executable directly.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# cfcrawler

[![Release](https://img.shields.io/github/v/release/ManiMozaffar/cfcrawler)](https://img.shields.io/github/v/release/ManiMozaffar/cfcrawler)
[![Build status](https://img.shields.io/github/actions/workflow/status/ManiMozaffar/cfcrawler/main.yml?branch=main)](https://github.com/ManiMozaffar/cfcrawler/actions/workflows/main.yml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/ManiMozaffar/cfcrawler/branch/main/graph/badge.svg)](https://codecov.io/gh/ManiMozaffar/cfcrawler)
[![Commit activity](https://img.shields.io/github/commit-activity/m/ManiMozaffar/cfcrawler)](https://img.shields.io/github/commit-activity/m/ManiMozaffar/cfcrawler)
[![License](https://img.shields.io/github/license/ManiMozaffar/cfcrawler)](https://img.shields.io/github/license/ManiMozaffar/cfcrawler)

Cloudflare scraper and cralwer written in Async, In-place library for HTTPX. Crawl website that has cloudflare enabled, easier than ever!

This library is a HTTP client designed to crawl websites protected by Cloudflare, even when their bot detection system is active. If you're already using httpx, you can switch to this library easily since it's a drop-in replacement. Just change the import, and you're good to go.

- **Github repository**: <https://github.com/ManiMozaffar/cfcrawler/>

## Installation

To install base package, you can do:

```bash
pip install cfcrawler
```

To install `fake-useragent` backend support to rotate user agents, you can do:

```bash
pip install "cfcrawler[ua]"
```

## Getting started

To use library, simply replace your aiohttp client with ours! It's completely in-place :)

```python
from cfcrawler import AsyncClient

async def get(url):
    client = AsyncClient()
    await client.get(url)

```

By default, we're using one random user agent, which is still undetected in tests.
To rotate user agent, you need to explicitly call `rotate_useragent` method.
By default, we have a pool of few user agents, But you can also install extra optional dependencies to have a big pool of user agents to rotate between them.

```python
from cfcrawler import AsyncClient

client = AsyncClient(use_fake_useragent_library=True) # one random user agent is selected
# do something
client.rotate_useragent() # user agent is rotated
# do something
client.rotate_useragent() # user agent is rotated again
# do something
```

You can also specify which browser you want to use

```python
from cfcrawler.types import Browser
from cfcrawler import AsyncClient

AsyncClient(browser=Browser.CHROME)
```

If you wish to have your own user agent pool, you can pass the factory callable to the client

```python
from cfcrawler import AsyncClient

def my_useragent_factory():
    return "My User Agent" # your implementation

client = AsyncClient(user_agent_factory=my_useragent_factory)
```

You can also use asyncer to syncify the implementation

```python
from cfcrawler import AsyncClient
from asyncer import syncify

def get(url):
    client = AsyncClient()
    syncify(client.get)(url)
```

## How this library works

### The Problem

Websites using Cloudflare often rely on a bot detection mechanism that works by checking your TLS Fingerprint. So, what's a TLS Fingerprint? When you connect to a website that uses HTTPS, the first thing that happens is the exchange of a "Client Hello" message. This message tells the server some basic info about your client, like the TLS version you support and a list of cipher suites, and etc.

### What's a Cipher Suite?

A cipher suite is a set of cryptographic algorithms that the client and server use to establish a secure connection. Each browser or client has its own specific list of cipher suites, and their order is unique. For instance, Chrome has its own list, Firefox has another, and Python's requests library has a completely different one.

### The Detection

Cloudflare figures out if you're not a real browser by comparing your TLS Fingerprint—which is a combination of the TLS version and cipher suite order—with your user-agent. If there's a mismatch, like if your user-agent says you're Chrome but your cipher suites suggest you're a Python script, Cloudflare knows you're not a browser and blocks the request.

### How My Library Helps

This library handles that problem by aligning your TLS Fingerprint with your user-agent, making it harder for Cloudflare to detect that you're not a real browser. The best part? It's just 10 lines of code! In source code, checkout `cfcrawler/tls.py` to see how it works.

## Coming Next

1. CF JS Challenge solver
2. Captcha solver integration (2Captcha and etc)