OnionSpy

OnionSpy is a CLI toolkit for Tor-based research workflows. It helps you validate Tor connectivity, inspect onion services, crawl metadata, run dark web search collection and filtering workflows, and optionally store outputs in MongoDB.

Key Features

• Tor connection verification and local Tor daemon control
• Proxy management (default Tor SOCKS, optional Privoxy)
• Onion service health scanning and metadata crawling
• Relay lookup by IP, fingerprint, or relay name
• Dark web search aggregation and AI-based content filtering
• Data breach lookups (full list and company-specific)
• Optional MongoDB insertion for collected outputs

Target Audience

• Security researchers
• Threat intelligence analysts
• Incident response teams
• Advanced learners studying Tor ecosystem operations

Scope

The tool is built for research and monitoring workflows, not for offensive or illegal use.

⚠️ Warning: This project is intended for legitimate security research, education, and defensive analysis only. Do not use OnionSpy for illegal activity. You are responsible for following applicable laws, platform rules, and provider policies (including Ollama terms and service conditions). The developer and contributors are not responsible for misuse.

Requirements

Required:

• Python 3.13+
• Tor daemon
  • Windows: Tor Expert Bundle is recommended
  • Linux/macOS: system Tor package is fine
• torcc configuration with at least:
  • SocksPort 9050
  • ControlPort 9051
  • CookieAuthentication 1

Optional but recommended:

• Ollama (needed for search, crawl, and AI-powered install guidance flows)
• Privoxy (only if you want HTTP proxy forwarding through http://127.0.0.1:8118)
• MongoDB (only for optional data insertion prompts)

Tor Daemon Connection (Core Requirement)

Tor daemon is a core dependency for OnionSpy. If Tor is not installed, Tor-based commands can fail with connection or startup errors.

Use a valid torcc file with proper configuration, at minimum:

• SocksPort 9050
• ControlPort 9051
• CookieAuthentication 1

Behavior summary:

• If Tor daemon is already installed, running, and using the correct torcc setup, OnionSpy connects normally.
• If Tor daemon is installed but not running, and app.tor.tor_executable plus app.tor.torcc are set correctly in config.yaml, OnionSpy can start Tor automatically and then connect to the Tor network.
• If the executable path or torcc path is invalid, startup/connection will fail until the paths and Tor config are fixed.

Installation

Windows

1. Clone and enter project directory.
2. Run setup:
   • .\setup.bat
3. Edit config.yaml values:
   • tor_executable (Tor binary path)
   • tor_data_dir
   • proxy_url (socks5h://127.0.0.1:9050 by default)
   • Optional MongoDB/Ollama fields
4. Start Tor with your local setup (if not already running).
5. Launch tool:
   • python main.py

Linux

1. Clone and enter project directory.
2. Run setup:
   • bash setup.sh
3. Edit config.yaml values as needed (Tor path/proxy/MongoDB/Ollama).
4. Ensure Tor daemon is running with compatible control and SOCKS ports.
5. Launch tool:
   • python3 main.py

macOS

1. Clone and enter project directory.
2. Run setup:
   • bash setup.sh
3. Edit config.yaml values as needed (Tor path/proxy/MongoDB/Ollama).
4. Ensure Tor daemon is running with compatible control and SOCKS ports.
5. Launch tool:
   • python3 main.py

Setup Scripts

• Windows script: setup.bat
• Linux/macOS script: setup.sh

Both scripts:

• create .venv
• install dependencies from requirements.txt
• bootstrap config.yaml from example.config.yaml if missing
• create required data/log directories (if not exist or missing)

Configuration Notes

• Default proxy is Tor SOCKS: socks5h://127.0.0.1:9050
• Privoxy can be enabled by switching proxy with:
  • changeproxy http://127.0.0.1:8118
• Keep Tor control port reachable (9051) for torverify, torconn, and torclose.

Documentation Index

• Usage and commands: USAGE.md
• Engine and workflow internals: WORKING.md
• Contribution guidelines: CONTRIBUTING.md
• Project layout reference: PROJECT_STRUCTURE.md

License

This project is released under the Apache License.

Version

Current project version in code: 0.1.0