stealthium 0.1.0

Create undetectable browser sessions for web scraping without automation flags

Stealthium

Create undetectable browser sessions for web scraping without automation flags. Stealthium provides a drop-in replacement for Selenium's webdriver.Chrome - use it exactly like Selenium, but with built-in anti-detection features.

Features

• 🕵️ Anti-Detection: Removes automation flags and makes browsers appear as real users
• 🔄 Drop-in Replacement: Use StealthChrome() exactly like webdriver.Chrome()
• 🌐 Extract Headers: Get real HTTP headers from browser sessions
• 🔄 Proxy Support: Built-in proxy configuration
• 🎭 Random User Agents: Automatically uses random, realistic user agents
• 🖥️ Cross-Platform: Works on Windows, Linux, and macOS
• ✅ Full Selenium Compatibility: All Selenium methods work as expected

Installation

pip install stealthium

For Linux systems (to enable virtual display):

pip install stealthium[linux]

Linux System Requirements

Install Chrome/Chromium

Stealthium requires Chrome or Chromium to be installed. If you get a "cannot find Chrome binary" error, install one of the following:

Ubuntu/Debian:

# Install Google Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f  # Fix dependencies

# OR install Chromium (lighter alternative)
sudo apt-get update
sudo apt-get install chromium-browser

Fedora/RHEL/CentOS:

# Install Google Chrome
sudo dnf install google-chrome-stable

# OR install Chromium
sudo dnf install chromium

Arch Linux:

# Install Google Chrome
yay -S google-chrome

# OR install Chromium
sudo pacman -S chromium

Install Xvfb (Optional - for virtual display)

On Linux systems, if you want to use the virtual display feature (optional), you need to install Xvfb:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install xvfb

Fedora/RHEL/CentOS:

sudo dnf install xorg-x11-server-Xvfb

Arch Linux:

sudo pacman -S xorg-server-xvfb

Note: The virtual display is optional. Chrome can run in headless mode without it, so you can skip this step if you don't need the virtual display feature.

Or install from source:

git clone https://github.com/yourusername/stealthium.git
cd stealthium
pip install -e .

Quick Start

Basic Usage (Just like Selenium!)

from stealthium import StealthChrome

# Use it exactly like webdriver.Chrome()
driver = StealthChrome(headless=True)

try:
    driver.get('https://example.com')
    print(driver.title)
    
    # All Selenium methods work!
    element = driver.find_element('tag name', 'h1')
    print(element.text)
finally:
    driver.quit()

Extract Headers

from stealthium import StealthChrome

driver = StealthChrome(headless=True)

try:
    driver.get('https://example.com')
    
    # Extract real HTTP headers (new method!)
    headers = driver.get_headers()
    print(f"User-Agent: {headers.get('user-agent')}")
finally:
    driver.quit()

With Proxy

from stealthium import StealthChrome

# Set proxy during initialization
driver = StealthChrome(
    headless=True,
    proxy_host='proxy.example.com',
    proxy_port=8080,
    proxy_user='username',  # Optional
    proxy_password='password'  # Optional
)

try:
    driver.get('https://httpbin.org/ip')
    print(driver.page_source)
finally:
    driver.quit()

Context Manager

from stealthium import StealthChrome

# Automatic cleanup with context manager
with StealthChrome(headless=True) as driver:
    driver.get('https://example.com')
    print(driver.title)
    # Driver automatically quits when exiting

Custom Options

from stealthium import StealthChrome
from selenium.webdriver.chrome.options import Options

# Use custom ChromeOptions (stealth features still applied)
options = Options()
options.add_argument('--window-size=1920,1080')

driver = StealthChrome(options=options, headless=True)
try:
    driver.get('https://example.com')
finally:
    driver.quit()

Migration from Selenium

It's super easy! Just replace webdriver.Chrome with StealthChrome:

# Before (Selenium)
from selenium import webdriver
driver = webdriver.Chrome()
driver.get('https://example.com')

# After (Stealthium)
from stealthium import StealthChrome
driver = StealthChrome()
driver.get('https://example.com')

That's it! Everything else works exactly the same.

How It Works

Stealthium uses several techniques to make automated browsers undetectable:

1. Removes Automation Flags: Disables navigator.webdriver and other automation indicators
2. Real Browser Headers: Extracts actual HTTP headers from Chrome performance logs
3. Random User Agents: Uses realistic, random user agents from the fake-useragent library
4. Chrome Options: Configures Chrome with anti-detection settings
5. CDP Commands: Uses Chrome DevTools Protocol to override user agents

API Reference

StealthChrome

Drop-in replacement for webdriver.Chrome with stealth features.

Parameters (same as webdriver.Chrome, plus):

• headless (bool): Whether to run in headless mode. Default: True
• logger (logging.Logger, optional): Logger instance. If None, creates a basic logger.
• proxy_host (str, optional): Proxy host address
• proxy_port (int, optional): Proxy port number
• proxy_user (str, optional): Proxy username for authentication
• proxy_password (str, optional): Proxy password for authentication

Additional Methods:

• get_headers(url=None): Extract HTTP headers from browser performance logs
  • Returns: Dictionary of HTTP headers
  • Example: headers = driver.get_headers()

All standard Selenium methods work:

• get(url), find_element(), find_elements(), execute_script(), etc.
• Everything that works with webdriver.Chrome works with StealthChrome!

Requirements

• Python 3.8+
• Chrome/Chromium browser installed
• ChromeDriver (automatically managed by webdriver-manager)
• Linux users (optional): Xvfb for virtual display support (see Linux System Requirements above)

Limitations

• Requires Chrome/Chromium to be installed
• Browser header extraction is slower than using predefined headers
• Some websites may still detect automation through other means (behavioral analysis, etc.)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Disclaimer

This tool is for educational and legitimate web scraping purposes only. Always respect websites' terms of service and robots.txt files. Use responsibly and ethically.