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 and transparent Tor transport support
• fail-fast Tor transport verification 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 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 transport:
  • SOCKS5h: Tor daemon 127.0.0.1:9050, Tor Browser 127.0.0.1:9150, or another reachable Tor SOCKS endpoint
  • transparent: a system whose TCP/DNS traffic is already enforced through Tor, such as a correctly configured workstation behind Whonix-Gateway

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

Use a transparently torified workstation, for example Kali behind Whonix-Gateway:

onionscout -u http://exampleonionaddress.onion --tor-mode transparent

Transparent mode does not use a local SOCKS proxy. It requires successful Tor Project egress verification before the target is contacted and relies on the operating system or gateway to enforce TCP/DNS through Tor.

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
--tor-mode            Tor transport mode: socks or transparent, default socks
--socks               SOCKS5h proxy for socks mode, default 127.0.0.1:9050
--skip-tor-check      Skip external Tor Project verification in socks mode only
--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.
• In socks mode, onionscout requires a working SOCKS5 endpoint before origin probing and aborts if it is unavailable or invalid. In transparent mode, no local SOCKS proxy is used and successful Tor Project egress verification is mandatory before the target is contacted. Transparent mode relies on external fail-closed TCP/DNS Tor enforcement, such as a correctly configured Whonix-Gateway. --skip-tor-check is available only in socks mode.
• 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.