Tor Browser Automation

Tor Browser Automation

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

Prerequisites

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  [--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:

Important:

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:

Timeout:

CAPTCHA blocking:

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

License

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

# 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

Quick setup:

# Install Tor
sudo apt install tor && sudo systemctl start tor
Install Python dependencies
pip install playwright
playwright install chromium

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:

Timeout:

CAPTCHA blocking: