abrasio

Abrasio SDK

Undetected web scraping SDK inspired on Patchright with human-like behavior simulation and optional cloud browser support.

Features

Anti-Detection Status

Table of Contents

• Installation
• Quick Start
• FingerprintConfig
• Human-Like Behavior
• TLS Fingerprinting (HTTP)
• Configuration
• Client Certificates
• Cloud Mode
• Error Handling
• API Reference
• Best Practices

Installation

# Install SDK
pip install abrasio

# Install real Chrome (NOT Chromium) for maximum stealth
patchright install chrome

# Optional: TLS fingerprinting for HTTP requests
pip install abrasio[tls]

# Optional: fingerprint generation utilities
pip install abrasio[fingerprint]

# Optional: client certificates (PFX/PKCS12 -> PEM conversion)
pip install abrasio[cert]

# Install everything
pip install abrasio[all]

Requirements

• Python 3.8+
• Chrome browser (installed via patchright install chrome)

Quick Start

Local Mode (Free)

import asyncio
from abrasio import Abrasio

async def main():
    async with Abrasio(headless=False) as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")
        print(await page.title())

asyncio.run(main())

Cloud Mode (Paid)

import asyncio
from abrasio import Abrasio

async def main():
    async with Abrasio(
        api_key="sk_live_xxx",
        region="BR",
        url="https://example.com.br",
    ) as browser:
        page = await browser.new_page()
        await page.goto("https://example.com.br")
        print(await page.title())

asyncio.run(main())

Synchronous API

from abrasio.sync_api import Abrasio

with Abrasio(headless=False) as browser:
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())

FingerprintConfig

Control browser fingerprint protections in local mode only. In cloud mode, the cloud browser handles all fingerprinting automatically.

from abrasio import Abrasio, FingerprintConfig

async with Abrasio(
    headless=False,
    fingerprint=FingerprintConfig(
        webgl=True,          # Keep WebGL enabled (default). False blocks it.
        webrtc=False,        # Block WebRTC IP leak (recommended with proxy)
        canvas_noise=True,   # Add noise to canvas fingerprint
        audio_noise=True,    # Add noise to audio fingerprint
    ),
) as browser:
    page = await browser.new_page()
    await page.goto("https://example.com")

Cloud mode: FingerprintConfig is completely ignored. The cloud browser uses real collected fingerprints

Human-Like Behavior

Utilities for simulating realistic human behavior to bypass behavioral analysis.

Mouse Movement (Bezier Curves)

from abrasio.utils import human_move_to, human_click

# Move mouse with natural Bezier curve trajectory
await human_move_to(page, x=500, y=300)

# Click with natural movement and random offset
await human_click(page, "button#submit")

Natural Typing

from abrasio.utils import human_type

await human_type(
    page,
    "Hello, World!",
    selector="input#search",
    mistake_probability=0.02,
    think_pause_probability=0.05,
)

Smooth Scrolling

from abrasio.utils import human_scroll, simulate_reading

await human_scroll(page, "down", amount=400, smooth=True)
await simulate_reading(page, min_seconds=3, max_seconds=8)

All Utilities

from abrasio.utils import (
    human_move_to,      # Bezier curve mouse movement
    human_click,        # Natural click with movement
    human_type,         # Variable-speed typing with mistakes
    human_scroll,       # Smooth scrolling with momentum
    human_wait,         # Random wait (skewed distribution)
    random_delay,       # Simple random delay
    simulate_reading,   # Simulate page reading behavior
)

TLS Fingerprinting (HTTP)

For HTTP requests outside the browser, use StealthClient which matches real browser TLS fingerprints via curl_cffi.

pip install abrasio[tls]

from abrasio.http import StealthClient

# Async
async with StealthClient() as client:
    response = await client.get("https://example.com")
    print(response.text)

# With region (auto-sets Accept-Language)
async with StealthClient(region="BR") as client:
    response = await client.get("https://example.com.br")

# With proxy
async with StealthClient(proxy="http://user:pass@host:8080") as client:
    response = await client.get("https://example.com")

# Rotate browser version on each request
async with StealthClient(rotate_impersonation=True) as client:
    for url in urls:
        response = await client.get(url)

Configuration

AbrasioConfig

from abrasio import Abrasio, AbrasioConfig, FingerprintConfig

config = AbrasioConfig(
    # Mode: None = local (free), "sk_xxx" = cloud (paid)
    api_key=None,

    # Browser
    headless=False,                  # Visible = more stealthy
    proxy="http://user:pass@host:8080",
    timeout=30000,

    # Region (auto-configures locale/timezone)
    region="BR",

    # Fingerprint (local mode only)
    fingerprint=FingerprintConfig(
        webgl=True,
        webrtc=False,
        canvas_noise=True,
        audio_noise=True,
    ),

    # Profile persistence
    user_data_dir="./my_profile",

    # Cloud mode
    profile_id="my-profile",

    # Client certificates - local mode only (see Client Certificates section)
    client_certificates=None,

    # Advanced
    extra_args=[],
    debug=False,
)

async with Abrasio(config) as browser:
    ...

Region Auto-Configuration

config = AbrasioConfig(region="BR")
# locale="pt-BR", timezone="America/Sao_Paulo"

config = AbrasioConfig(region="JP")
# locale="ja-JP", timezone="Asia/Tokyo"

50+ regions supported. If you set a mismatched timezone, you'll get a warning:

config = AbrasioConfig(region="BR", timezone="America/New_York")
print(config.region_warnings)
# ['Timezone mismatch: using America/New_York but region BR expects America/Sao_Paulo']

Without explicit region, locale/timezone are auto-detected from your public IP.

Environment Variables

Client Certificates

Some sites require TLS Client Authentication during login — the browser must present a client certificate during the TLS handshake (e.g. ICP-Brasil digital certificates used to log into gov.br services). There are two ways to do this, and which one works depends on the mode:

pip install abrasio[cert]   # cryptography, only needed to convert PFX/PKCS12 -> PEM

from abrasio import build_client_certificate

cert = build_client_certificate(
    origin="https://sso.acesso.gov.br",   # exact origin the cert is valid for
    pfx_path="certificado.pfx",           # or cert_path= / key_path= for a PEM pair
    passphrase="minha-senha",
)

Local mode: native client_certificates

Playwright/Patchright support client_certificates as a context option, applied when the browser launches. Pass it to AbrasioConfig/Abrasio(...):

async with Abrasio(headless=False, client_certificates=[cert]) as browser:
    page = await browser.new_page()
    await page.goto("https://sso.acesso.gov.br/login")

This only works in local mode. Under the hood, Playwright applies it via a local SOCKS proxy that the browser dials back into — that requires the browser and the Playwright driver to be on the same machine. In cloud mode the browser runs on Abrasio's infrastructure, so that proxy is unreachable and the certificate is silently never used.

Cloud mode (and local too): route_with_certificate

Intercept the specific certificate-login request and replay it outside the browser using httpx (which supports client certificates natively), then feed the real response back into the browser. Since the interception always runs in the driver process — never inside the browser itself — this works regardless of where the browser runs:

async with Abrasio(api_key="sk_live_xxx", region="BR") as browser:
    page = await browser.new_page()
    await page.goto("https://sso.acesso.gov.br/login")

    certificate_button = page.locator("#login-certificate")
    form_action = await certificate_button.get_attribute("formaction")

    await browser.route_with_certificate(page, form_action, cert)
    await certificate_button.click()

route_with_certificate defaults the replay request's proxy to the session's configured proxy, so the authenticated request leaves through the same exit IP as the rest of the browser session — important, since an IP mismatch between normal navigation and the certificate-authenticated request is exactly the kind of signal sites use to flag a session.

It also defaults timeout to the session's configured timeout (AbrasioConfig.timeout, 30s by default) instead of httpx's own 5s default — going through a proxy to a government auth server can easily take longer than that. If you see the route time out (the page ends up on chrome-error://chromewebdata/), pass a larger timeout= explicitly:

await browser.route_with_certificate(page, form_action, cert, timeout=60)

See examples/certificado.py for a full working example.

Cloud Mode (Paid)

With an API key, you get access to the Abrasio cloud infrastructure:

from abrasio import Abrasio

async with Abrasio(
    api_key="sk_live_xxx",
    region="BR",
    url="https://target-site.com.br",
    profile_id="my-profile",
) as browser:
    page = await browser.new_page()

    # Live view URL (if enabled on server)
    if browser.live_view_url:
        print(f"Watch live: {browser.live_view_url}")

    await page.goto("https://target-site.com.br")
    print(await page.title())

Error Handling

from abrasio import (
    Abrasio,
    AbrasioError,           # Base error
    AuthenticationError,    # Invalid API key (401)
    InsufficientFundsError, # Not enough balance (402)
    RateLimitError,         # Too many sessions (429) - auto-retried
    SessionError,           # Session creation/management error
    BrowserError,           # Browser operation error
    TimeoutError,           # Operation timeout
    BlockedError,           # Target site blocked request
)

try:
    async with Abrasio(api_key="sk_live_xxx") as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")
except AuthenticationError:
    print("Invalid API key")
except InsufficientFundsError as e:
    print(f"Add funds. Balance: ${e.balance:.2f}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except SessionError as e:
    print(f"Session error: {e.message}")
except AbrasioError as e:
    print(f"Error: {e.message}")

Note: The SDK automatically retries on 429 (rate limit), 502, 503, 504 with exponential backoff up to 3 times.

API Reference

Abrasio

class Abrasio:
    def __init__(
        self,
        config: Optional[AbrasioConfig] = None,
        *,
        api_key: Optional[str] = None,
        headless: bool = True,
        proxy: Optional[str] = None,
        stealth: bool = True,
        **kwargs,
    ): ...

    async def start(self) -> "Abrasio": ...
    async def close(self) -> None: ...
    async def new_page(self) -> Page: ...
    async def new_context(self, **kwargs) -> BrowserContext: ...
    async def route_with_certificate(self, target, url, certificate, *, proxy=None, timeout=None) -> None: ...

    @property
    def browser(self): ...       # Browser (cloud) or BrowserContext (local)
    @property
    def is_cloud(self) -> bool: ...
    @property
    def is_local(self) -> bool: ...
    @property
    def live_view_url(self) -> Optional[str]: ...  # Cloud mode only

Human Utilities

async def human_move_to(page, x, y, *, min_time=0.1, max_time=1.5): ...
async def human_click(page, selector=None, *, offset_range=5, move_first=True): ...
async def human_type(page, text, selector=None, *, mistake_probability=0.02): ...
async def human_scroll(page, direction="down", amount=None, *, smooth=True): ...
async def random_delay(min_ms=100, max_ms=500): ...
async def human_wait(min_seconds=0.5, max_seconds=2.0): ...
async def simulate_reading(page, min_seconds=2.0, max_seconds=8.0): ...

StealthClient (TLS)

from abrasio.http import StealthClient, BrowserImpersonation

class StealthClient:
    def __init__(self, impersonate=BrowserImpersonation.DEFAULT,
                 proxy=None, region=None, rotate_impersonation=False): ...

    async def get(self, url, **kwargs) -> StealthResponse: ...
    async def post(self, url, **kwargs) -> StealthResponse: ...

Best Practices

1. Headless mode is safe — SDK automatically removes "HeadlessChrome" from User-Agent
2. Don't set user_agent — let the SDK handle it (auto-fixed in headless mode)
3. Don't set viewport — uses no_viewport for realistic behavior
4. Add human behavior between actions (human_wait, human_click)
5. Use persistent profiles with user_data_dir for cookie persistence
6. Use region to auto-configure locale/timezone consistently
7. Set webrtc=False when using a proxy (prevents IP leak)
8. Test against bot detection sites before production deployment

Testing Anti-Detection

import asyncio
from abrasio import Abrasio

async def test():
    async with Abrasio(headless=False) as browser:
        page = await browser.new_page()

        await page.goto("https://bot.sannysoft.com/")
        await page.screenshot(path="sannysoft.png")

        await page.goto("https://abrahamjuliot.github.io/creepjs/")
        await page.wait_for_timeout(5000)
        await page.screenshot(path="creepjs.png")

asyncio.run(test())

Project Structure

abrasio-sdk/
├── abrasio/
│   ├── __init__.py          # Public API exports
│   ├── _api.py              # Abrasio class (local + cloud)
│   ├── _config.py           # AbrasioConfig, FingerprintConfig
│   ├── _exceptions.py       # Exception hierarchy
│   ├── local/
│   │   └── browser.py       # StealthBrowser (Patchright)
│   ├── cloud/
│   │   ├── browser.py       # CloudBrowser (API + CDP)
│   │   └── api_client.py    # HTTP client with retry
│   ├── http/
│   │   └── client.py        # StealthClient (curl_cffi TLS)
│   ├── sync_api/
│   │   └── _sync.py         # Synchronous wrapper
│   └── utils/
│       ├── human.py         # Human behavior simulation
│       ├── fingerprint.py   # Region config, validation
│       ├── geolocation.py   # IP-based locale detection
│       └── certificates.py  # Client certificates (TLS Client Auth)
├── examples/
│   ├── basic_local.py       # Local mode example
│   ├── basic_cloud.py       # Cloud mode example
│   ├── human_behavior.py    # Human behavior demo
│   ├── fingerprint_check.py # Fingerprint validation
│   ├── tls_fingerprint.py   # TLS fingerprinting
│   └── certificado.py       # Client certificate login (gov.br)
├── docs/                    # Documentation
└── pyproject.toml

References

• Patchright - Undetected Playwright fork
• curl_cffi - TLS fingerprinting HTTP client
• BrowserForge - Fingerprint generation
• Ghost Cursor - Bezier curve mouse movements

Support & Community

For bug reports and feature requests, open a thread in the #abrasio-feedback channel on Discord.

License

Proprietary - Scrape Technology