Metadata-Version: 2.4
Name: onionscout
Version: 0.4.4
Summary: CLI tool for auditing Tor hidden-service (.onion) security leaks and misconfigurations
Author: Hoek
License-Expression: MIT
Project-URL: Homepage, https://github.com/h0ek/onionscout
Project-URL: Repository, https://github.com/h0ek/onionscout
Project-URL: Issues, https://github.com/h0ek/onionscout/issues
Keywords: tor,onion,hidden-service,security,osint,audit,pentest,scanner
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests[socks]>=2.32.0
Requires-Dist: PySocks>=1.7.1
Requires-Dist: urllib3>=2.0.0
Requires-Dist: mmh3>=4.1.0
Requires-Dist: paramiko>=3.4.0
Requires-Dist: rich>=13.7.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: selectolax>=0.3.21
Dynamic: license-file

# onionscout

![onionscout](https://raw.githubusercontent.com/h0ek/onionscout/refs/heads/main/onionscout.webp)

**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

```bash
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:

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

For multiple cookies, use the normal HTTP header format:

```bash
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.
