A robust, 'plug-and-play' wrapper around SeleniumBase UC Mode for stealth web automation.
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.
pip install sb-stealth-wrapperIf 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 xvfbHere 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")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.
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.
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.
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.
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!
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
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.
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.
- 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).
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.