Tor Browser Automation

Headless browser automation with Tor SOCKS5 proxy support for accessing .onion sites and anonymous browsing. Use when navigating dark web resources, scraping...

Headless browser automation with Tor SOCKS5 proxy support for accessing .onion sites and anonymous web browsing.

Prerequisites

• Tor service running with SOCKS5 proxy on port 9050
• Python 3.8+
• Playwright with Chromium browser

Quick setup:

# Install Tor
sudo apt install tor && sudo systemctl start tor

# Install Python dependencies
pip install playwright
playwright install chromium

Quick Start

# Check Tor connection
tor-browser check-tor

# Navigate to a .onion site
tor-browser open http://3g2upl4pq6kufc4m.onion

# Get page snapshot
tor-browser snapshot -i

# Click an element
tor-browser click @e1

# Take screenshot
tor-browser screenshot -o output.png --full

Commands

Navigation

# Open URL via Tor
tor-browser open <url> [--proxy socks5://host:port]

# Check Tor connection status
tor-browser check-tor

Page Analysis

# Get full page snapshot
tor-browser snapshot

# Get interactive elements only (forms, buttons, links)
tor-browser snapshot -i

# Extract all links
tor-browser links

# Get page text
tor-browser gettext
tor-browser gettext --ref @e5

Interaction

# Click element by ref
tor-browser click @e1

# Fill input field
tor-browser fill @e2 "text to enter"

# Wait for page load
tor-browser wait 2000

Screenshots

# Take viewport screenshot
tor-browser screenshot

# Save to file
tor-browser screenshot -o capture.png

# Full page screenshot
tor-browser screenshot --full -o page.png

Python API

from scripts.tor_browser import TorBrowser, Config
import asyncio

async def main():
    # Configure browser
    config = Config(
        tor_proxy="socks5://127.0.0.1:9050",
        headless=True,
        timeout=30000
    )
    
    # Initialize and start
    browser = TorBrowser(config)
    await browser.start()
    
    # Navigate
    result = await browser.navigate("http://3g2upl4pq6kufc4m.onion")
    print(f"Loaded: {result['title']}")
    
    # Get snapshot
    snapshot = await browser.get_snapshot(interactive_only=True)
    for elem in snapshot['elements']:
        print(f"{elem['ref']}: {elem['tag']} - {elem['text'][:30]}")
    
    # Interact
    await browser.fill("@e2", "search query")
    await browser.click("@e3")
    
    # Extract data
    links = await browser.extract_links()
    for link in links:
        print(f"{link['text']}: {link['href']}")
    
    # Cleanup
    await browser.close()

asyncio.run(main())

Configuration Options

Option	Default	Description
tor_proxy	socks5://127.0.0.1:9050	Tor SOCKS5 proxy URL
headless	true	Run without GUI
timeout	30000	Page load timeout (ms)
user_agent	Tor Browser UA	Browser user agent
viewport	1920x1080	Browser viewport size

Security & Legal

Intended Use:

• Security research and threat intelligence
• Anonymous web scraping of public dark web resources
• Testing .onion site accessibility
• Privacy-preserving web automation

Important:

• Only use for legal purposes
• Respect site Terms of Service
• Do not use for unauthorized access
• Comply with local laws regarding dark web access
• Be aware that some activities may be monitored

Troubleshooting

Tor Connection Issues

# Check Tor is running
sudo systemctl status tor

# Test SOCKS5 proxy
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip

# View Tor logs
sudo journalctl -u tor -f

Common Errors

Connection refused:

• Ensure Tor service is started
• Check firewall rules
• Verify proxy URL

Timeout:

• .onion sites may be slow; increase timeout
• Try different Tor circuits: restart Tor service

CAPTCHA blocking:

• Use --headed mode to manually solve
• Some sites block automation

Docker Setup

FROM python:3.11-slim

RUN apt-get update && apt-get install -y tor
RUN pip install playwright && playwright install chromium

COPY . /app
WORKDIR /app

CMD ["tor-browser", "check-tor"]

References

• Setup Guide: references/setup-guide.md
• Playwright Docs: https://playwright.dev/python/
• Tor Project: https://www.torproject.org/

License

MIT - See original licenses for Playwright and Tor Project components.