onionscout

onionscout is a lightweight CLI tool for auditing Tor hidden services (.onion) for common security misconfigurations, clearnet dependencies, metadata leaks, fingerprinting indicators, and basic de-anonymization risks.

It is designed as a first-pass audit helper, not a full penetration-testing framework.

Use only against systems you own or are authorized to assess.

Features

Network and origin handling

• Tor SOCKS5h support
• mandatory SOCKS5 preflight with fail-fast before target probing
• onion v3 address checksum validation
• smart HTTP/HTTPS origin selection
• .onion-safe redirect policy
• strict target origin/port allowlist and fail-closed Tor SOCKS5h transport
• cross-onion redirect blocking
• redirect leak detection to clearnet
• bounded retry handling for common onion/Tor network errors
• response body, request-count, and scan-time limits
• separate HTTP, SSH, and TLS timeouts

Web fingerprinting

• web server header detection
• default error-page fingerprinting
• favicon discovery and Shodan-compatible favicon hash
• ETag extraction and Shodan query helper
• TLS reachability, TLS version, cipher, certificate SHA256, issuer, subject, validity, and self-issued certificate indicator

Leak and de-anonymization checks

• clearnet redirects
• external active resources
• external links
• CSP / CSP-Report-Only external allowances
• Report-To / NEL / Link header leakage
• canonical / alternate / OpenGraph / Twitter metadata leaks
• RSS / Atom feed metadata leak checks
• JSON-LD structured data URL leak checks
• protocol-relative external links
• meta-refresh redirects
• clearnet form actions
• clearnet WebSocket endpoints
• Onion-Location header
• optional clearnet mirror Onion-Location validation with --clearnet-url
• proxy-related headers
• common fingerprinting headers
• baseline security headers
• CORS misconfiguration classification
• JavaScript URL, IP, source-map, and secret-candidate leak checks
• Canvas, WebGL, WebRTC, STUN/TURN, AudioContext, and device-fingerprinting API indicators
• analytics/tracker identifier correlation
• cloud/CDN infrastructure correlation indicators
• hidden/external iframe and conservative suspicious-JavaScript indicators
• lightweight image metadata sniffing for EXIF/XMP-style markers, URLs, IPs, and GPS hints
• linked document metadata sniffing for authors, tool names, paths, IPs, emails, and clearnet URLs (including limited Office XML extraction)

Hidden-service hygiene checks

• Apache mod_status
• Apache mod_info
• nginx stub_status
• WebDAV exposure
• HTTP method exposure checks, including TRACE, PUT, DELETE, PATCH, PROPFIND, and MKCOL
• common sensitive files and paths
• Swagger/OpenAPI, GraphQL, and common debug/API endpoint exposure checks
• backup, archive, SQL dump, and stale file leak detection
• directory listing detection
• verbose error-page fingerprinting
• .well-known/* endpoints
• robots.txt
• sitemap.xml
• clearnet URL detection inside robots.txt and sitemap.xml
• security.txt at root and .well-known
• basic security.txt Expires, Canonical, and clearnet URL review
• CAPTCHA-related external resource leakage
• Set-Cookie attributes:
  • Secure
  • HttpOnly
  • SameSite
  • Domain

Content indicators

• minimal same-host crawler
• email extraction
• obfuscated email extraction, for example name(at)domain(dot)tld
• placeholder email separation, for example example.com
• BTC / ETH / XMR address indicators
• HTML comments review
• comment-based IP, URL, JWT, private key, and secret-candidate detection

Output

• human-readable Rich table
• JSON output for automation
• optional report file export
• standalone HTML report export
• check profiles: basic, safe, extended
• check selection with --only and --skip
• optional local SQLite scan history and diffing

Requirements

• Python 3.10+
• Tor SOCKS proxy:
  • Tor daemon: 127.0.0.1:9050
  • Tor Browser: 127.0.0.1:9150
  • Whonix Gateway example: 10.152.152.10:9050

Installation

From PyPI

pipx install onionscout

From GitHub

pipx install git+https://github.com/h0ek/onionscout.git

For local development:

git clone https://github.com/h0ek/onionscout.git
cd onionscout
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -U pip
python3 -m pip install -e .
python3 onionscout.py -u <ONION_URL> --skip-tor-check

Usage

onionscout -u <ONION_URL>

Example:

onionscout -u http://exampleonionaddress.onion --skip-tor-check

Use Tor Browser SOCKS:

onionscout -u http://exampleonionaddress.onion --socks 127.0.0.1:9150 --skip-tor-check

Force HTTP:

onionscout -u exampleonionaddress.onion --scheme http

Force HTTPS:

onionscout -u exampleonionaddress.onion --scheme https

Self-signed target onion certificates are detected automatically and HTTPS verification is disabled only for target HTTP checks. Use --no-auto-insecure-https to keep strict verification behavior.

Manual insecure HTTPS mode is still available:

onionscout -u exampleonionaddress.onion --scheme https --insecure-https

Validate a clearnet mirror Onion-Location header against the target onion:

onionscout -u exampleonionaddress.onion --clearnet-url https://mirror.example

Save TXT report:

onionscout -u exampleonionaddress.onion -o report.txt

Save JSON report:

onionscout -u exampleonionaddress.onion --json -o report.json

Save HTML report:

onionscout -u exampleonionaddress.onion --html-report report.html

Use a specific profile:

onionscout -u exampleonionaddress.onion --profile basic
onionscout -u exampleonionaddress.onion --profile safe
onionscout -u exampleonionaddress.onion --profile extended

Run only selected checks:

onionscout -u exampleonionaddress.onion --only headers,js,robots,metadata

Skip selected checks:

onionscout -u exampleonionaddress.onion --skip ssh,images,crawl

Disable crawler:

onionscout -u exampleonionaddress.onion --no-crawl

Tune crawler:

onionscout -u exampleonionaddress.onion --max-urls 150 --depth 2

Tune timeouts:

onionscout -u exampleonionaddress.onion --http-timeout 20 --ssh-timeout 8 --tls-timeout 12

Save a scan to local history:

onionscout -u exampleonionaddress.onion --save-scan

Compare against the latest saved scan and save the current result:

onionscout -u exampleonionaddress.onion --diff

Show saved history for a target:

onionscout -u exampleonionaddress.onion --history

Authenticated scans

Some onion services require an authenticated session. You can pass a raw HTTP Cookie header with --cookie. The cookie is scoped by onionscout to the selected target onion host and is not sent to the Tor connectivity check or blocked off-target URLs.

Example:

onionscout -u http://exampleonionaddress.onion --cookie 'access=abcd1234'

For multiple cookies, use the normal HTTP header format:

onionscout -u http://exampleonionaddress.onion --cookie 'access=VALUE; session=VALUE2; csrftoken=VALUE3'

How to get the cookie value from a browser:

1. Log in to the target service.
2. Open Developer Tools.
3. Go to Storage / Cookies.
4. Select the target onion domain.
5. Copy the cookie name and value.
6. Pass it as name=value.

Do not share session cookies. They are equivalent to temporary access tokens for your logged-in session.

Options

-u, --url              Target .onion URL
--scheme              Origin scheme mode: auto, http, https
--socks               SOCKS5h proxy, default 127.0.0.1:9050
--skip-tor-check      Skip external Tor Project verification; local SOCKS5 preflight still runs
--http-timeout        HTTP timeout
--ssh-timeout         SSH timeout
--tls-timeout         TLS timeout
--ssh-port            SSH port for fingerprint check
--retries             Retries for transient onion/Tor errors
--max-requests        Maximum HTTP requests per scan
--max-body-bytes      Maximum decompressed response size
--max-duration        Scan time budget in seconds
--profile             Check profile: basic, safe, extended
--only                Run only selected checks
--skip                Skip selected checks
--cookie              Raw HTTP Cookie header, e.g. 'access=VALUE; session=VALUE2'
--clearnet-url        Optional clearnet mirror URL for Onion-Location validation
--insecure-https      Disable HTTPS verification for the target onion only
--no-auto-insecure-https
                       Keep strict verification even for self-signed target onion certificates
--no-crawl            Disable crawler-based checks
--max-urls            Crawler URL limit
--depth               Crawler depth
--save-scan           Save this scan to local SQLite history
--diff                Compare with latest saved scan and save this scan
--history             Show saved scan history for target and exit
--history-limit       Number of history rows to show
--history-db          Custom SQLite history database path
--json                Output JSON
--html-report         Save standalone HTML report
-o, --output          Save report to file

Notes

• Most onion services use plain HTTP internally; HTTPS is supported when present.
• In auto mode, onionscout tests available origins and chooses a working HTTP or HTTPS origin.
• Before origin probing, onionscout requires a working SOCKS5 endpoint and aborts immediately if it is unavailable or invalid. By default it also verifies Tor egress with Tor Project; --skip-tor-check skips only that external verification.
• Redirects are followed only within the approved onion host and port; clearnet and cross-onion redirects are reported, not fetched.
• Some findings are context-dependent. For example, public social links may be intentional, while active clearnet scripts are usually more relevant for anonymity risk.
• basic is for quick low-noise checks, safe is the default, and extended increases selected metadata/archive review limits.
• --only and --skip accept check names or short aliases such as headers, js, fingerprinting, api, cloud, analytics, iframes, robots, metadata, docs, backup, and errors.
• --save-scan stores a local, redacted result. --diff reports unverifiable checks as UNKNOWN rather than resolved.
• --workers is retained for CLI compatibility; crawling is sequential and rate-limited.
• Scan history is stored in ${XDG_DATA_HOME:-~/.local/share}/onionscout/onionscout.db unless --history-db is used.