A robust, plug-and-play wrapper around SeleniumBase UC Mode for stealth web automation.
Project description
SB Stealth Wrapper
A robust, 'plug-and-play' wrapper around SeleniumBase UC Mode for stealth web automation.
🚀 Why Use This Package?
Modern web automation often requires complex configurations to bypass bot detection systems like Cloudflare Turnstile. SB Stealth Wrapper abstracts this complexity into a single, easy-to-use class.
It handles:
- Auto-Evasion: Automatically configures the environment for maximum stealth (e.g., using
xvfbon Linux). - Behavioral Biometrics: Simulates human-like Bezier curve mouse movements and variable typing speeds with occasional typos to defeat behavioral analysis.
- Active Fingerprint Evasion: Proactively injects "poisoned" Canvas and AudioContext data to create unique, consistent fingerprints that mask the standard WebDriver footprint.
- Smart Interactions: Provides interactions that automatically handle scrolling, waiting, and challenge detection.
- Generic Challenge Management: Detects common challenge screens and attempts to solve them.
It allows you to focus on what your bot needs to do, rather than how to keep it undetected.
📦 Installation
1. Install via pip
pip install sb-stealth-wrapper
2. Prerequisites (Linux / Docker Only)
If you are running this on a Linux server or inside a Docker container (like GitHub Actions), you MUST install xvfb.
Why?
Stealth automation works best in "headed" mode (where the browser GUI is visible). Native "headless" mode is easily detected by anti-bots. xvfb creates a "virtual display" so the browser thinks it has a screen, allowing it to run in headed mode on a headless server.
# Debian / Ubuntu
sudo apt-get install xvfb
⚡ Quick Start
Here is the minimal code to get started. This example navigates to a site and clicks a button safely.
from sb_stealth_wrapper import StealthBot
# Initialize the bot
# Use success_criteria to tell the bot what text confirms the page is fully loaded/unlocked.
with StealthBot(headless=False, success_criteria="Welcome") as bot:
# 1. Navigate safely
bot.safe_get("https://example.com/protected-page")
# 2. Click elements with auto-evasion
bot.smart_click("#login-button")
# 3. Save a screenshot for debugging
bot.save_screenshot("debug_step_1")
🛠️ Detailed Usage & API Reference
StealthBot Class
The main entry point. Use it as a context manager (with ...) to ensure the browser closes properly.
StealthBot(
headless=False,
proxy=None,
screenshot_path="debug_screenshots",
success_criteria=None
)
Parameters:
headless(bool): Defaults toFalse. Recommended. True headless mode is risky for stealth. On Linux, this is automatically managed (see Core Concepts).proxy(str): Optional. Format:user:pass@host:port.screenshot_path(str): Directory where screenshots are saved. Created automatically.success_criteria(str): Optional. A specific string to wait for (e.g., "Dashboard", "Login Successful") which confirms that challenges are passed. IfNone, the bot relies on the disappearance of challenge words (like "Turnstile") to assume success.
bot.safe_get(url)
Navigates to a URL and immediately checks for challenges.
- What it does: Opens the URL → Waits for
<body>→ Checks for "Challenge"/"Turnstile" → auto-solves if found.
bot.smart_click(selector)
A stealthy alternative to standard clicks.
- What it does:
- Checks for challenges before clicking.
- Scrolls the element into view.
- waits for it to be visible.
- Attempts a "Human" click (UC Mode).
- Fallbacks: If the human click fails, it tries a standard Selenium click, then a JavaScript click, ensuring high reliability.
🔧 Advanced Modular Usage (New in v0.4.0)
StealthBot now uses a Strategy Pattern, allowing you to customize its behavior.
from sb_stealth_wrapper import StealthBot
from sb_stealth_wrapper.strategies.input import HumanInputStrategy
# 1. Custom Input Strategy
# You can tweak specific input behaviors if needed for different target sites.
my_input = HumanInputStrategy()
# 2. Inject Strategies
with StealthBot(input_strategy=my_input) as bot:
bot.safe_get("https://high-security-site.com")
# All clicks now use Bezier curves automatically
bot.smart_click("#login")
The bot comes with powerful defaults:
- CanvasPoisoningStrategy: Randomizes canvas hash per session.
- AudioContextNoiseStrategy: Randomizes audio fingerprint.
- HumanInputStrategy: Physics-based mouse movements and human-like typing.
🧠 Core Concepts & Best Practices
The "Headed vs Headless" Dilemma
Anti-bot systems (Cloudflare, Akamai, etc.) aggressively target "Headless Chrome".
- Rule of Thumb: ALWAYS run with
headless=Falsefor stealth. - On Servers: Use
xvfb(as explained in Installation) to runheadless=Falseon a server without a monitor.StealthBotdetects Linux automatically and configures this for you!
Challenge Handling Logic
The bot uses a smart loop to handle challenges:
- Detection: It scans the page source for keywords: "challenge", "turnstile", "verify you are human".
- Action: If found, it uses SeleniumBase's
uc_gui_click_captcha(simulating a real human mouse) to click the checkbox. - Verification:
- If
success_criteria="My Dashboard"was passed, it waits until that text appears. - If not, it waits until "challenge" text disappears.
- If
⚠️ Edge Cases & Troubleshooting
1. The Bot Gets Stuck in a Loop
If the bot keeps clicking the challenge but it never solves:
- Solution: The IP might be bad (if using a proxy), or the site needs a stronger interaction. Try increasing
time.sleepin your own script or manually slowing down interactions. StealthBotwill try 3 times and then warn you ("Max retries reached") to prevent infinite hangs.
2. "Element Not Found" Errors
smart_click is robust, but if the page is heavy with JavaScript:
- Ensure you used
success_criteriain__init__so the bot really waits for the page to be ready before trying to click.
3. CI/GitHub Actions Fails
- Did you install
xvfb? Check the prerequisites. - Screen Size: Sometimes elements are off-screen. The bot uses
scroll_to_elementautomatically, but you can also try setting a window size explicitly using the underlyingbot.sb.set_window_size(1920, 1080).
Credits & Disclaimer
Created by Dhiraj Das • Built on top of the incredible SeleniumBase by Michael Mintz.
Ethical Use Only: This tool is for testing your own infrastructure or sites you have permission to test. Do not use for unauthorized scraping or bypassing security controls on 3rd party services.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sb_stealth_wrapper-0.4.0.tar.gz.
File metadata
- Download URL: sb_stealth_wrapper-0.4.0.tar.gz
- Upload date:
- Size: 16.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2ecc18cd251696a46c3e26e8f69316cdd38190716d51bc064dd04a6d2f4f177a
|
|
| MD5 |
8ce55f35266987852a5275ad019cf973
|
|
| BLAKE2b-256 |
2fe47300dc6ac90daa2adfe50ec720487cab819856984c66c27b4537c128006d
|
File details
Details for the file sb_stealth_wrapper-0.4.0-py3-none-any.whl.
File metadata
- Download URL: sb_stealth_wrapper-0.4.0-py3-none-any.whl
- Upload date:
- Size: 12.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f2baca0f6cf7de9572fb11c6c7b799af407e9bf446b4937d05d6b86f28fcc8d5
|
|
| MD5 |
a43713facc0af963b7e8f3e74525d963
|
|
| BLAKE2b-256 |
a65264fb1d01c669b99f09df24ce9109de19c8061dd22f9c5224e0a92326aa35
|
