• Overview
• Features
• Architecture & Design
• Installation
• Usage
• Documentation
• Troubleshooting
• Security & Legal Notice
• Contributing
• Credits

ScayTor is a powerful, feature-rich command-line tool designed for security researchers, penetration testers, and cybersecurity enthusiasts who need to search and collect .onion (Tor hidden service) addresses from the clearnet.

• 🔍 Smart Search: Queries ahmia.fi search engine with intelligent retry mechanisms
• 🎨 Beautiful Interface: Hacker-themed CLI with color-coded output and animations
• 📊 Multiple Outputs: Generates both text files and professional HTML reports
• 🛡️ Robust Error Handling: Comprehensive error handling with exponential backoff
• ⚡ Performance: Threaded progress indicators and efficient processing
• 🌓 Dark/Light Mode: HTML reports support both themes with dynamic banner switching

• 🛡️ Error Handling: Comprehensive error handling with retry mechanisms and exponential backoff
• ⚡ Efficient: Threading for non-blocking progress updates
• 🔒 Safe: Proper URL encoding and input validation
• 📝 Logging: Clear status messages and warnings
• 🔄 Retry Logic: Automatic retries with exponential backoff on failures

flowchart TB
    subgraph App["ScayTor Application"]
        direction TB
        A[CLI Interface] --> B[Argument Parser]
        B --> C[Main Controller]
        C --> D[Input Handler]
        C --> E[Network Module]
        C --> F[Processing Engine]
        D --> G[Query Validator]
        D --> H[Limit Validator]
        E --> I[User-Agent Manager]
        E --> J[HTTP Client]
        E --> K[Progress Bar]
        F --> L[Regex Extractor]
        F --> M[Link Deduplicator]
        C --> N[Output Generator]
        N --> O[Text Writer]
        N --> P[HTML Generator]
    end
    
    subgraph Ext["External Services"]
        direction TB
        Q[ahmia.fi Search Engine]
        R[user-agents.txt File]
    end
    
    subgraph Out["Output Files"]
        direction TB
        S[.txt File]
        T[.html Report]
    end
    
    J --> Q
    I --> R
    O --> S
    P --> T
    
    style A fill:#ff6b9d
    style C fill:#00ffd0
    style Q fill:#ff26a6
    style S fill:#00ffd0
    style T fill:#00ffd0

sequenceDiagram
    participant U as User
    participant C as CLI
    participant P as Parser
    participant N as Network
    participant E as Extractor
    participant O as Output
    
    U->>C: Run ScayTor
    C->>P: Parse Arguments
    P-->>C: Config
    
    alt Interactive Mode
        C->>U: Prompt for Query
        U-->>C: Search Query
        C->>U: Prompt for Limit
        U-->>C: Result Count
    else CLI Arguments
        C->>P: Read Args
        P-->>C: Query & Limit
    end
    
    C->>N: Load User-Agent
    N->>N: Read user-agents.txt
    N-->>C: Random Agent
    
    C->>N: Fetch Results
    N->>N: HTTP GET Request
    N->>N: Show Progress Bar
    N-->>C: HTML Content
    
    C->>E: Extract Links
    E->>E: Regex Matching
    E->>E: Deduplication
    E-->>C: .onion Links
    
    C->>U: Display Results
    
    C->>O: Save Text File
    C->>O: Generate HTML Report
    O-->>C: Files Created
    
    C->>U: Completion Message

┌─────────────────────────────────────────────────────────────────┐
│                         ScayTor Workflow                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  Print Banner   │ ◄── ASCII Art Display
                    └────────┬────────┘
                             │
                             ▼
              ┌──────────────────────────────┐
              │  Parse Command-Line Args     │
              │  (--query, --limit, --output)│
              └──────┬───────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
        ▼                         ▼
┌───────────────┐        ┌───────────────┐
│  Interactive  │        │  CLI Args     │
│     Mode      │        │    Mode       │
└───────┬───────┘        └───────┬───────┘
        │                         │
        └────────────┬────────────┘
                     │
                     ▼
            ┌─────────────────┐
            │  Get User Agent │ ◄── Random Selection
            └────────┬────────┘     from user-agents.txt
                     │
                     ▼
            ┌─────────────────┐
            │  Build URL      │ ◄── URL Encoding
            │  & Headers      │
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │  Fetch Results  │ ◄── HTTP GET
            │ (with retries) │     Progress Bar
            └────────┬────────┘     Exponential Backoff
                     │
                     ▼
            ┌─────────────────┐
            │ Extract Links  │ ◄── Regex Pattern
            │  (.onion URLs) │     Deduplication
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │ Display Results │ ◄── Console Output
            │  (Colored)      │     (Typewriter Effect)
            └────────┬────────┘
                     │
                     ▼
        ┌─────────────────────────────┐
        │      Save to Files         │
        ├─────────────────────────────┤
        │  • .txt (plain text)        │
        │  • .html (styled report)    │
        └─────────────────────────────┘

flowchart TD
    A[Start: HTML Content] --> B[Define Regex Pattern]
    B --> C[Pattern: Base32 16-56 chars + .onion]
    C --> D[Find All Matches]
    D --> E{Matches Found?}
    E -->|No| F[Return Empty List]
    E -->|Yes| G[Convert to Dictionary]
    G --> H[Keys Preserve Order]
    H --> I[Remove Duplicates]
    I --> J[Convert Back to List]
    J --> K[Return Deduplicated Links]
    
    style A fill:#00ffd0
    style C fill:#ff26a6
    style K fill:#00ffd0

Algorithm Details:

• Pattern: \b[a-zA-Z2-7]{16,56}\.onion\b
• Word Boundaries (\b): Ensures complete matches
• Base32 Alphabet ([a-zA-Z2-7]): Tor uses base32 encoding
• Length Range ({16,56}): Valid .onion address length
• Domain (\.onion): Literal ".onion" TLD

flowchart TD
    A[Start Request] --> B[Attempt = 1]
    B --> C[HTTP GET Request]
    C --> D{Success?}
    D -->|Yes| E[Return HTML Content]
    D -->|No| F{Attempt < Max?}
    F -->|No| G[Return Failure]
    F -->|Yes| H[Wait: 2 * Attempt seconds]
    H --> I[Increment Attempt]
    I --> C
    
    style A fill:#00ffd0
    style E fill:#00ffd0
    style G fill:#ff26a6

Retry Strategy:

• Maximum Attempts: 3
• Exponential Backoff: 2s, 4s, 6s delays
• Timeout: 15 seconds per request
• Error Types: Timeout, ConnectionError, HTTPError

• Python 3.8+ (tested on 3.8, 3.9, 3.10, 3.11, 3.12)
• pip (Python package manager)
• Internet connection (for fetching search results)

# Clone the repository
git clone https://github.com/scayar/ScayTor.git
cd ScayTor

# Install dependencies
pip install -r requirements.txt

# Run ScayTor
python TorSearch.py

git clone https://github.com/scayar/ScayTor.git
cd ScayTor

Or download and extract the ZIP file from the releases.

Using pip:

pip install -r requirements.txt

Or manually:

pip install colorama requests

For Python 3, you may need:

pip3 install colorama requests

python TorSearch.py --version

Expected output:

ScayTor 2.0.0

python TorSearch.py

The tool will prompt you for:

1. Search query
2. Number of results to retrieve

ScayTor supports various command-line arguments for automation and scripting:

python TorSearch.py --query "marketplace" --limit 20
python TorSearch.py -q "security" -l 10 -o results.txt
python TorSearch.py --query "tor" --limit 5 --no-progress

                                              ___
                                          ,o88888
                                       ,o8888888'
                 ,:o:o:oooo.        ,8O88Pd8888"
             ,.::.::o:ooooOoOoO. ,oO8O8Pd888'"
           ,.:.::o:ooOoOoOO8O8OOo.8OOPd8O8O"
          , ..:.::o:ooOoOOOO8OOOOo.FdO8O8"
         , ..:.::o:ooOoOO8O888O8O,COCOO"
        , . ..:.::o:ooOoOOOO8OOOOCOCO"
         . ..:.::o:ooOoOoOO8O8OCCCC"o
            . ..:.::o:ooooOoCoCCC"o:o
            . ..:.::o:o:,cooooCo"oo:o:
         `   . . ..:.:cocoooo"'o:o:::'
         .`   . ..::ccccoc"'o:o:o:::'
        :.:.    ,c:cccc"':.:.:.:.:.'
      ..:.:"'`::::c:"'..:.:.:.:.:.'
    ...:.'.:.::::"'    . . . . .'
   .. . ....:."' `   .  . . . ''
 . . . ...."'
 .. . ."'     ScayTor 

[?] Enter your search: cybersecurity
[?] How many .onion sites do you want? 5
[*] Fetching from ahmia.fi |██████████████████████████████| 100%
[+] Found 12 .onion links. Displaying up to 5...
[01] example1234567890abcdef.onion
[02] example0987654321fedcba.onion
[03] exampleabcdef1234567890.onion
[04] examplefedcba0987654321.onion
[05] example1122334455667788.onion
[+] Completed! 5 links saved in a3b2c.txt
[+] HTML report generated: a3b2c.html
[=] Session complete. Stay anonymous, hacker.

$ python TorSearch.py --query "marketplace" --limit 10 --output market_results

                                              ___
                                          ,o88888
                                       ,o8888888'
                 ,:o:o:oooo.        ,8O88Pd8888"
             ,.::.::o:ooooOoOoO. ,oO8O8Pd888'"
           ,.:.::o:ooOoOoOO8O8OOo.8OOPd8O8O"
          , ..:.::o:ooOoOOOO8OOOOo.FdO8O8"
         , ..:.::o:ooOoOO8O888O8O,COCOO"
        , . ..:.::o:ooOoOOOO8OOOOCOCO"
         . ..:.::o:ooOoOoOO8O8OCCCC"o
            . ..:.::o:ooooOoCoCCC"o:o
            . ..:.::o:o:,cooooCo"oo:o:
         `   . . ..:.:cocoooo"'o:o:::'
         .`   . ..::ccccoc"'o:o:o:::'
        :.:.    ,c:cccc"':.:.:.:.:.'
      ..:.:"'`::::c:"'..:.:.:.:.:.'
    ...:.'.:.::::"'    . . . . .'
   .. . ....:."' `   .  . . . ''
 . . . ...."'
 .. . ."'     ScayTor 

[*] Fetching from ahmia.fi |██████████████████████████████| 100%
[+] Found 25 .onion links. Displaying up to 10...
[01] marketplace1234567890.onion
...
[+] Completed! 10 links saved in market_results.txt
[+] HTML report generated: market_results.html
[=] Session complete. Stay anonymous, hacker.

Functions:

• print_banner(): Displays ASCII art banner
• type_out(): Animated character-by-character printing
• hacker_prompt(): Styled input prompts with typewriter effect

Features:

• Color-coded output (green for prompts, red for errors, cyan for info)
• Typewriter effect for dramatic presentation
• Cross-platform color support via colorama

Functions:

• get_search_query(): Validates and URL-encodes search input
• get_result_limit(): Ensures positive integer input

Validation Rules:

• Search query cannot be empty
• Result count must be positive integer
• Proper URL encoding using urllib.parse.quote_plus

Functions:

• get_user_agent(): Loads and randomizes user agents
• fetch_results(): HTTP GET with retry logic and exponential backoff
• progress_bar(): Animated progress indicator using threading

Features:

• 3 retry attempts on failure
• 15-second timeout per request
• Exponential backoff (2s, 4s, 6s delays)
• Threaded progress bar animation
• Random user-agent selection from user-agents.txt
• Enhanced HTTP headers for better compatibility

Functions:

• extract_onion_links(): Regex-based link extraction with deduplication

Pattern:

\b[a-zA-Z2-7]{16,56}\.onion\b

Explanation:

• \b: Word boundary (prevents partial matches)
• [a-zA-Z2-7]: Base32 alphabet (no 0, 1, 8, 9)
• {16,56}: Valid .onion address length range
• \.onion: Literal ".onion" TLD

Functions:

• save_results(): Writes .txt file with links
• save_html_report(): Generates styled HTML report with dark/light mode

File Formats:

Text File:

• One .onion URL per line
• UTF-8 encoding
• Random 5-character alphanumeric filename (or custom via --output)
• Easy to parse programmatically

HTML File:

• Self-contained HTML with embedded CSS/JS
• Responsive design (mobile-friendly)
• Dark/Light mode toggle
• Dynamic banner switching (CuteCat/Scarycat)
• Clickable links (open in Tor Browser)
• Professional styling with CSS variables

flowchart TD
    A[Operation] --> B{Error Type}
    B -->|Timeout| C[Exponential Backoff]
    B -->|Connection Error| C
    B -->|HTTP Error| C
    B -->|Other Exception| D[Log & Retry]
    C --> E{Retries < Max?}
    E -->|Yes| F[Wait & Retry]
    E -->|No| G[Return Failure]
    F --> A
    D --> E
    G --> H[Exit with Error Message]
    
    style A fill:#00ffd0
    style G fill:#ff26a6
    style H fill:#ff26a6

Error Types Handled:

• TimeoutException → Exponential backoff
• ConnectionError → Exponential backoff
• HTTPError → Exponential backoff
• Other Exceptions → Log and retry with backoff

Retry Logic:

• Maximum 3 attempts
• Exponential backoff delays: 2s, 4s, 6s
• Clear error messages to user
• Graceful failure handling

Symptoms:

• Tool runs successfully but returns 0 links

Possible Causes:

• Search query too specific
• ahmia.fi returned no results
• Network connectivity issues

Solutions:

1. Try broader search terms
2. Check internet connection
3. Verify ahmia.fi is accessible: curl https://ahmia.fi
4. Try a different search query

Symptoms:

• Network requests fail repeatedly

Possible Causes:

• Network timeout
• ahmia.fi server issues
• Firewall blocking requests
• Proxy configuration

Solutions:

1. Check internet connection
2. Try again later (server might be down)
3. Verify firewall/proxy settings
4. Ensure user-agents.txt exists
5. Try using --no-progress flag

Symptoms:

• HTML report generated but banner images missing

Possible Causes:

• Banner images missing (CuteCat.png, Scarycat.png)
• Incorrect file paths
• File permissions

Solutions:

1. Ensure CuteCat.png and Scarycat.png are in same directory as script
2. Check file permissions
3. Verify filenames match exactly (case-sensitive on Linux/Mac)
4. Images are optional - report will work without them

Symptoms:

ModuleNotFoundError: No module named 'colorama'

Possible Causes:

• Dependencies not installed
• Wrong Python environment
• Virtual environment not activated

Solutions:

# Install dependencies
pip install -r requirements.txt

# Or manually
pip install colorama requests

# For Python 3 specifically
pip3 install colorama requests

# If using virtual environment
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install -r requirements.txt

Symptoms:

• Error when trying to save output files

Possible Causes:

• Insufficient write permissions
• Read-only directory
• Disk space full

Solutions:

1. Run with appropriate permissions
2. Change to writable directory: cd ~/Desktop && python TorSearch.py
3. Check disk space: df -h (Linux/Mac) or check in File Explorer (Windows)
4. Specify output directory: --output /path/to/writable/dir/results.txt

Symptoms:

• Errors related to character encoding

Solutions:

• Ensure terminal supports UTF-8
• On Windows, use PowerShell or modern terminal (Windows Terminal)
• Files are saved with UTF-8 encoding by default

1. Legal Compliance

   • This tool is for educational and research purposes only
   • Users are responsible for complying with local laws
   • Accessing illegal content is prohibited
   • Use at your own risk

2. Privacy Considerations

   • Search queries are sent to ahmia.fi (clearnet service)
   • Consider using Tor Browser for maximum anonymity
   • User-agent randomization helps but doesn't guarantee anonymity
   • HTTP requests are not encrypted (use HTTPS when possible)

3. Security Best Practices

   • Always use Tor Browser to access .onion links
   • Verify links before clicking (some may be malicious)
   • Be cautious of malicious sites
   • Don't share personal information on dark web sites
   • Keep your system updated and use antivirus software

4. Ethical Use

   • Use responsibly and ethically
   • Respect terms of service of ahmia.fi
   • Don't abuse the service with excessive requests
   • Follow rate limiting best practices

Contributions are welcome! Please follow these guidelines:

flowchart LR
    A[Fork Repository] --> B[Create Branch]
    B --> C[Make Changes]
    C --> D[Test Thoroughly]
    D --> E[Commit Changes]
    E --> F[Push to Branch]
    F --> G[Open Pull Request]
    G --> H[Code Review]
    H --> I{Merge?}
    I -->|Yes| J[Merge to Main]
    I -->|No| K[Request Changes]
    K --> C
    
    style A fill:#00ffd0
    style J fill:#00ffd0
    style K fill:#ff26a6

Workflow Steps:

1. Fork the repository on GitHub
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your code changes following PEP 8
4. Test thoroughly on different Python versions
5. Commit changes with clear messages
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request on GitHub
8. Wait for code review
9. Address feedback or celebrate merge! 🎉

1. Fork the repository

   git fork https://github.com/scayar/ScayTor.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Follow PEP 8 (Python style guide)
   • Use descriptive variable names
   • Add comments for complex logic
   • Maintain existing formatting

4. Test thoroughly

   • Test on different Python versions
   • Test on different operating systems
   • Test edge cases

5. Commit with clear messages

   git commit -m 'Add amazing feature: description'

6. Push to branch

   git push origin feature/amazing-feature

7. Open a Pull Request

   • Provide clear description
   • Reference related issues
   • Include screenshots if UI changes

• Follow PEP 8 (Python style guide)
• Use descriptive variable names
• Add comments for complex logic
• Maintain existing formatting
• Write docstrings for functions
• Use type hints where appropriate

If you find a bug, please open an issue with:

• Description of the problem
• Steps to reproduce
• Expected vs. actual behavior
• System information (OS, Python version)
• Error messages (if any)
• Screenshots (if applicable)

Scayar

• 🌐 Website: Scayar.com
• 📧 Email: Scayar.exe@gmail.com
• 💬 Telegram: @im_scayar
• ☕ Buy Me a Coffee: buymeacoffee.com/scayar

• ahmia.fi for providing the search API
• Tor Project for creating the Tor network
• Python Community for excellent libraries (colorama, requests)
• Contributors who help improve ScayTor

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Potential features for future versions:

• Multiple search engine support (notjustahmia, others)
• Export to JSON/CSV formats
• Link validation (check if .onion sites are active)
• Search history tracking
• Configurable themes
• Batch search capability
• Proxy support (SOCKS5, HTTP)
• Rate limiting configuration
• Database storage for results
• API mode (RESTful interface)
• Docker containerization
• GUI version (Tkinter/PyQt)