Metadata-Version: 2.4
Name: onionscout
Version: 0.3.1
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 support
- onion v3 hostname sanity check
- smart HTTP/HTTPS origin selection
- `.onion`-safe redirect policy
- initial clearnet URL blocking for policy-managed fetches
- cross-onion redirect blocking
- redirect leak detection to clearnet
- retry handling for common onion/Tor network errors
- 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-signed/self-issued certificate detection

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

### 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
- 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`

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

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

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

## 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
--socks               SOCKS5h proxy, default 127.0.0.1:9050
--skip-tor-check      Skip check.torproject.org connectivity check
--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
--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 certificate verification for HTTP requests
--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
--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.
- Redirects are followed only when they stay on the selected target onion host; clearnet and cross-onion redirects are reported instead of being 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`, `robots`, `metadata`, `docs`, `backup`, and `errors`.
