HTTPCloak Python

Browser fingerprint emulation HTTP client with HTTP/1.1, HTTP/2, and HTTP/3 support.

Installation

pip install httpcloak

Quick Start

Synchronous Usage

from httpcloak import Session

# Create a session with Chrome fingerprint
session = Session(preset="chrome-latest")

# Make requests
response = session.get("https://www.cloudflare.com/cdn-cgi/trace")
print(response.status_code)
print(response.text)

# POST request with JSON
response = session.post("https://api.example.com/data", json={"key": "value"})

# POST request with form data
response = session.post("https://api.example.com/form", data="field1=value1&field2=value2")

# Custom headers
response = session.get("https://example.com", headers={"X-Custom": "value"})

# With proxy
session = Session(preset="chrome-latest", proxy="http://user:pass@host:port")

# Always close when done
session.close()

Context Manager (Recommended)

from httpcloak import Session

with Session(preset="chrome-latest") as session:
    response = session.get("https://example.com")
    print(response.text)
# Session automatically closed

Asynchronous Usage

import asyncio
from httpcloak import Session

async def main():
    session = Session(preset="chrome-latest")

    # Async GET
    response = await session.get_async("https://example.com")
    print(response.text)

    # Async POST
    response = await session.post_async("https://api.example.com/data", data={"key": "value"})

    # Multiple concurrent requests
    responses = await asyncio.gather(
        session.get_async("https://example.com/1"),
        session.get_async("https://example.com/2"),
        session.get_async("https://example.com/3"),
    )

    session.close()

asyncio.run(main())

Fast Response Mode

For performance-critical applications, use get_fast() which returns a lightweight response:

from httpcloak import Session

with Session(preset="chrome-latest") as session:
    # Fast mode - minimal overhead
    response = session.get_fast("https://example.com")
    data = bytes(response.content)  # Raw bytes
    print(f"Status: {response.status_code}")
    print(f"Size: {len(data)} bytes")

Streaming Downloads

For large downloads, use streaming to avoid loading entire response into memory:

from httpcloak import Session

with Session(preset="chrome-latest") as session:
    # Stream a large file
    stream = session.get_stream("https://example.com/large-file.zip")
    print(f"Status: {stream.status_code}")
    print(f"Content-Length: {stream.content_length}")

    # Read in chunks
    with open("downloaded-file.zip", "wb") as f:
        for chunk in stream.iter_content(65536):  # 64KB chunks
            f.write(chunk)

    stream.close()

# Or use context manager
with Session(preset="chrome-latest") as session:
    with session.get_stream("https://example.com/large-file.zip") as stream:
        total = 0
        for chunk in stream.iter_content(65536):
            total += len(chunk)
        print(f"Downloaded {total} bytes")

Proxy Support

HTTPCloak supports HTTP, SOCKS5, and HTTP/3 (MASQUE) proxies with full fingerprint preservation.

HTTP Proxy

from httpcloak import Session

# Basic HTTP proxy
session = Session(preset="chrome-latest", proxy="http://host:port")

# With authentication
session = Session(preset="chrome-latest", proxy="http://user:pass@host:port")

# HTTPS proxy
session = Session(preset="chrome-latest", proxy="https://user:pass@host:port")

SOCKS5 Proxy

from httpcloak import Session

# SOCKS5 proxy (with DNS resolution on proxy)
session = Session(preset="chrome-latest", proxy="socks5h://host:port")

# With authentication
session = Session(preset="chrome-latest", proxy="socks5h://user:pass@host:port")

response = session.get("https://www.cloudflare.com/cdn-cgi/trace")
print(response.protocol)  # h3 (HTTP/3 through SOCKS5!)

HTTP/3 MASQUE Proxy

MASQUE (RFC 9484) enables HTTP/3 connections through compatible proxies:

from httpcloak import Session

# MASQUE proxy (auto-detected for known providers like Bright Data)
session = Session(preset="chrome-latest", proxy="https://user:pass@brd.superproxy.io:10001")

response = session.get("https://www.cloudflare.com/cdn-cgi/trace")
print(response.protocol)  # h3

Split Proxy Configuration

Use different proxies for TCP (HTTP/1.1, HTTP/2) and UDP (HTTP/3) traffic:

from httpcloak import Session

session = Session(
    preset="chrome-latest",
    tcp_proxy="http://tcp-proxy:port",      # For HTTP/1.1, HTTP/2
    udp_proxy="https://masque-proxy:port"   # For HTTP/3
)

Advanced Features

Encrypted Client Hello (ECH)

ECH encrypts the SNI (Server Name Indication) to prevent traffic analysis. Works with all Cloudflare domains:

from httpcloak import Session

# Enable ECH for Cloudflare domains
session = Session(preset="chrome-latest", ech_config_domain="cloudflare-ech.com")

response = session.get("https://www.cloudflare.com/cdn-cgi/trace")
print(response.text)
# Output includes: sni=encrypted, http=http/3

Domain Fronting (Connect-To)

Connect to one server while requesting a different domain:

from httpcloak import Session

# Connect to example.com's IP but request www.cloudflare.com
session = Session(
    preset="chrome-latest",
    connect_to={"www.cloudflare.com": "example.com"}
)

response = session.get("https://www.cloudflare.com/cdn-cgi/trace")

Combined: SOCKS5 + ECH

Get HTTP/3 with encrypted SNI through a SOCKS5 proxy:

from httpcloak import Session

session = Session(
    preset="chrome-latest",
    proxy="socks5h://user:pass@host:port",
    ech_config_domain="cloudflare-ech.com"
)

response = session.get("https://www.cloudflare.com/cdn-cgi/trace")
# Response shows: http=http/3, sni=encrypted

Cookie Management

from httpcloak import Session

session = Session()

# Set a simple cookie (global, sent to all domains)
session.set_cookie("session_id", "abc123")

# Set a domain-scoped cookie with full metadata
session.set_cookie("auth", "token",
    domain=".example.com",
    path="/",
    secure=True,
    http_only=True,
    same_site="Lax",
)

# Get all cookies (returns List[Cookie] with full metadata)
cookies = session.get_cookies()
for cookie in cookies:
    print(f"{cookie.name}={cookie.value} (domain: {cookie.domain})")

# Get a specific cookie by name (returns Cookie or None)
cookie = session.get_cookie("session_id")
if cookie:
    print(cookie.value)

# Delete a cookie (omit domain to delete from all domains)
session.delete_cookie("session_id")
session.delete_cookie("auth", domain=".example.com")  # delete from specific domain

# Clear all cookies
session.clear_cookies()

session.close()

Session Configuration

from httpcloak import Session

session = Session(
    preset="chrome-latest",           # Browser fingerprint preset
    proxy=None,                    # Proxy URL
    tcp_proxy=None,                # Separate TCP proxy
    udp_proxy=None,                # Separate UDP proxy (MASQUE)
    timeout=30,                    # Request timeout in seconds
    http_version="auto",           # "auto", "h1", "h2", "h3"
    verify=True,                   # SSL certificate verification
    allow_redirects=True,          # Follow redirects
    max_redirects=10,              # Maximum redirect count
    retry=3,                       # Retry count on failure
    prefer_ipv4=False,             # Prefer IPv4 over IPv6
    auth=("user", "pass"),         # Default basic auth
    connect_to=None,               # Domain fronting map
    ech_config_domain=None         # ECH config domain
)

Available Presets

from httpcloak import available_presets

print(available_presets())
# ['chrome-146', 'chrome-145', 'chrome-144', 'chrome-143', 'chrome-141', 'chrome-133',
#  'firefox-133', 'safari-18', 'chrome-146-ios', ...]

Response Object

Standard Response

response = session.get("https://example.com")

response.status_code   # int: HTTP status code
response.headers       # dict[str, list[str]]: Response headers (multi-value)
response.content       # bytes: Raw response body
response.text          # str: Response body as text
response.url           # str: Final URL after redirects
response.protocol      # str: Protocol used (h2, h3)
response.ok            # bool: True if status < 400
response.elapsed       # float: Request duration in seconds
response.cookies       # list: Cookies from response
response.history       # list: Redirect history
response.reason        # str: Status reason phrase

# Get specific header
content_type = response.get_header("Content-Type")
all_cookies = response.get_headers("Set-Cookie")

# Parse JSON
data = response.json()

Fast Response

response = session.get_fast("https://example.com")

response.status_code   # int: HTTP status code
response.headers       # dict: Response headers
response.content       # memoryview: Raw response body (zero-copy)
response.url           # str: Final URL after redirects
response.protocol      # str: Protocol used

Streaming Response

stream = session.get_stream("https://example.com")

stream.status_code      # int: HTTP status code
stream.headers          # dict[str, list[str]]: Response headers
stream.content_length   # int: Content length (-1 if unknown)
stream.url              # str: Final URL after redirects
stream.protocol         # str: Protocol used

# Read all bytes
data = b"".join(stream.iter_content(65536))

# Read in chunks (memory efficient)
for chunk in stream.iter_content(65536):
    process(chunk)

stream.close()

HTTP Methods

from httpcloak import Session

with Session(preset="chrome-latest") as session:
    # GET
    response = session.get("https://example.com")

    # POST
    response = session.post("https://example.com", data="data")
    response = session.post("https://example.com", json={"key": "value"})

    # PUT
    response = session.put("https://example.com", data="data")

    # PATCH
    response = session.patch("https://example.com", data="data")

    # DELETE
    response = session.delete("https://example.com")

    # HEAD
    response = session.head("https://example.com")

    # OPTIONS
    response = session.options("https://example.com")

    # Custom method
    response = session.request("CUSTOM", "https://example.com")

Error Handling

from httpcloak import Session, HTTPCloakError

try:
    session = Session()
    response = session.get("https://example.com")
except HTTPCloakError as e:
    print(f"Request failed: {e}")
finally:
    session.close()

Convenience Functions

For one-off requests without managing a session:

import httpcloak

# Simple GET
response = httpcloak.get("https://example.com")
print(response.text)

# With options
response = httpcloak.get(
    "https://example.com",
    headers={"X-Custom": "value"},
    timeout=60
)

# POST
response = httpcloak.post("https://api.example.com", data={"key": "value"})

Local Proxy

Use LocalProxy to apply TLS fingerprinting to any HTTP client (requests, httpx, etc.).

Basic Usage

Request the target as http:// and add X-HTTPCloak-Scheme: https. That one detail decides whether any fingerprinting happens at all:

from httpcloak import LocalProxy
import requests

# Start local proxy with Chrome fingerprint
proxy = LocalProxy(preset="chrome-latest")
print(f"Proxy running on {proxy.proxy_url}")

response = requests.get(
    "http://example.com/api",              # note: http://
    proxies={"http": proxy.proxy_url},
    headers={"X-HTTPCloak-Scheme": "https"},  # upgraded to HTTPS by the proxy
)

# Per-request upstream proxy rotation
response = requests.get(
    "http://example.com",
    proxies={"http": proxy.proxy_url},
    headers={
        "X-HTTPCloak-Scheme": "https",
        "X-Upstream-Proxy": "http://user:pass@rotating-proxy.com:8080",
    },
)

proxy.close()

This gives you full TLS fingerprinting, HTTP/2 and HTTP/3 support, and true streaming: request and response bodies are never materialized into memory.

Requesting https:// through the proxy applies no fingerprint

# Runs fine, returns a real response, and carries Python's TLS fingerprint
response = requests.get("https://example.com", proxies={"https": proxy.proxy_url})

requests, like every mainstream client, handles an https:// URL through a proxy by sending CONNECT and then doing its own TLS handshake straight through to the target. The proxy relays encrypted bytes it cannot read, so the target sees Python's handshake rather than the preset's. Nothing errors, which is what makes it easy to ship by accident.

Measured against tls.peet.ws, same proxy, same preset:

The first row is byte-identical to requests with no proxy at all. The same applies to X-HTTPCloak-Session: on a CONNECT request your headers travel inside the tunnel, so the proxy never reads them and session routing silently does nothing.

TLS-Only Mode

When your client already provides authentic browser headers, use TLS-only mode:

from httpcloak import LocalProxy

# Only apply TLS fingerprint, pass headers through
proxy = LocalProxy(preset="chrome-latest", tls_only=True)

# Your client's headers are preserved
response = requests.get(
    "http://example.com",
    proxies={"http": proxy.proxy_url},
    headers={
        "X-HTTPCloak-Scheme": "https",
        "User-Agent": "My Custom UA",
    },
)

proxy.close()

Session Registry

Route different requests through different browser fingerprints:

from httpcloak import LocalProxy, Session

proxy = LocalProxy(preset="chrome-latest")

# Create sessions with different fingerprints
chrome_session = Session(preset="chrome-latest")
firefox_session = Session(preset="firefox-133")

# Register sessions with the proxy
proxy.register_session("chrome-user", chrome_session)
proxy.register_session("firefox-user", firefox_session)

# Route requests using X-HTTPCloak-Session header
response = requests.get(
    "http://example.com",
    proxies={"http": proxy.proxy_url},
    headers={
        "X-HTTPCloak-Scheme": "https",
        "X-HTTPCloak-Session": "firefox-user",  # uses firefox fingerprint
    },
)

# Unregister when done
proxy.unregister_session("chrome-user")
proxy.unregister_session("firefox-user")

chrome_session.close()
firefox_session.close()
proxy.close()

LocalProxy Options

proxy = LocalProxy(
    port=0,              # Port (0 = auto-select)
    preset="chrome-latest", # Browser fingerprint
    timeout=30,          # Request timeout in seconds
    max_connections=1000,# Max concurrent connections
    tcp_proxy=None,      # Default upstream TCP proxy
    udp_proxy=None,      # Default upstream UDP proxy
    tls_only=False       # TLS-only mode
)

proxy.port           # Actual port number
proxy.proxy_url      # Full proxy URL (http://127.0.0.1:port)
proxy.is_running     # True if proxy is active
proxy.get_stats()    # Returns dict with request/connection stats
proxy.close()        # Stop the proxy

Platform Support

• Linux (x64, arm64)
• macOS (x64, arm64)
• Windows (x64, arm64)
• Python 3.8+

License

MIT