onionscan

OnionScan

OnionScan is a security auditing tool for Tor hidden services (.onion addresses). It identifies OPSEC issues, configuration errors, and anonymity risks that could deanonymize hidden service operators.

This project is a complete rewrite inspired by the original s-rah/onionscan, which had not been maintained for several years. Major enhancements include:

• Tor v3 Support: Full support for v3 onion addresses (56-character .onion addresses using ed25519 keys)
• Embedded Tor: No need to manually configure Tor - the tool handles it automatically
• Enhanced Analyzers: Additional security checks for modern threats (browser fingerprinting, API leaks, cloud services)
• Multiple Output Formats: JSON, Markdown, and text reports with severity-based categorization
• Modern Go Codebase: Built from scratch with Go 1.25+, clean architecture, and comprehensive test coverage

[!IMPORTANT] Legal Notice: This tool is intended for legitimate purposes only, such as security research, penetration testing with authorization, and privacy auditing of your own services. Users are solely responsible for ensuring their use complies with all applicable laws and regulations. Do not use this tool for any illegal activities.

Features

• Embedded Tor Support: Automatically starts a Tor daemon - no manual Tor configuration required
• Comprehensive Security Analysis: 16+ analyzers covering various attack vectors
• Multiple Output Formats: Text, JSON, and Markdown reports
• Multi-Protocol Scanning: HTTP/HTTPS, SSH, FTP, SMTP, and database protocols
• Web Crawling: Deep analysis with configurable crawl depth
• Site-Specific Configuration: Custom cookies, headers, and patterns per target

Security Checks

Deanonymization Risks

Security Misconfigurations

Attack Surface Detection

Protocol Scanners

Requirements

• Go: 1.25 or later
• Tor: Must be installed on your system (for embedded mode)

Installing Tor

# Ubuntu/Debian
sudo apt update && sudo apt install tor

# Fedora/RHEL
sudo dnf install tor

# Arch Linux
sudo pacman -S tor

# macOS (Homebrew)
brew install tor

# Windows (Chocolatey)
choco install tor

Installation

Homebrew (macOS/Linux)

brew install nao1215/tap/onionscan

Go Install

go install github.com/nao1215/onionscan/cmd/onionscan@latest

Build from Source

git clone https://github.com/nao1215/onionscan.git
cd onionscan
go build -o onionscan ./cmd/onionscan

Quick Start

Basic Scan

# Scan a hidden service (starts embedded Tor automatically)
onionscan scan exampleonion.onion

# Scan multiple services
onionscan scan site1.onion site2.onion site3.onion

Using External Tor

If you already have Tor running:

# Use existing Tor SOCKS proxy
onionscan scan --external-tor 127.0.0.1:9050 exampleonion.onion

# Use Tor Browser's proxy
onionscan scan --external-tor 127.0.0.1:9150 exampleonion.onion

Output Formats

# JSON report
onionscan scan --json -o report.json exampleonion.onion

# Markdown report
onionscan scan --markdown -o report.md exampleonion.onion

# Text report to file
onionscan scan -o report.txt exampleonion.onion

Scan Options

# Custom crawl depth
onionscan scan --depth 50 exampleonion.onion

# Limit maximum pages to crawl
onionscan scan --max-pages 200 exampleonion.onion

# Custom timeout
onionscan scan --timeout 3m exampleonion.onion

# Verbose logging
onionscan scan -v exampleonion.onion

# Concurrent scans
onionscan scan --batch 5 site1.onion site2.onion site3.onion

CLI Options Reference

[!NOTE] Batch Mode Limitation: When using --batch with a value greater than 1, site-specific configurations (cookies, headers, depth) are ignored. Use --batch 1 to apply per-site settings from your configuration file.

Politeness Settings

OnionScan includes "politeness" settings to avoid overwhelming hidden services:

# Slower, more polite scanning (2 second delay)
onionscan scan --crawl-delay 2s exampleonion.onion

# Faster scanning for authorized testing (500ms delay)
onionscan scan --crawl-delay 500ms exampleonion.onion

# Custom User-Agent
onionscan scan --user-agent "MyScanner/1.0" exampleonion.onion

# Limit response body size (useful for memory-constrained environments)
onionscan scan --max-body-size 1048576 exampleonion.onion  # 1MB

[!TIP] Be Respectful: The default settings (1s delay, 5MB body limit) are conservative. Only reduce the delay for services you control or have explicit authorization to test aggressively.

Secure Logging

OnionScan automatically sanitizes sensitive information in log output, even in verbose mode:

• Sanitized: Cookies, Authorization headers, API tokens, passwords, session IDs, private keys
• Safe to share: Logs can be shared for debugging without accidentally exposing secrets

# Verbose mode with automatic secret sanitization
onionscan scan -v exampleonion.onion

# Example output (secrets are masked):
# INFO request sent cookie=***REDACTED*** url=http://example.onion

Data Storage

Scan results are automatically saved to a SQLite database following the XDG Base Directory specification:

Compare Scans

OnionScan stores scan results in a local database, allowing you to track changes over time:

# Compare latest two scans for a service
onionscan compare exampleonion.onion

# List all scan history for a service
onionscan compare -l exampleonion.onion

# List all scanned services in the database
onionscan compare -L

# Compare with a specific historical scan by ID
onionscan compare -i 5 exampleonion.onion

# Compare scans since a specific date
onionscan compare -s "2025-01-01" exampleonion.onion

# Output comparison in JSON format
onionscan compare -j exampleonion.onion

# Output comparison in Markdown format
onionscan compare -m exampleonion.onion

The comparison report shows:

• New findings: Issues that appeared since the previous scan
• Resolved findings: Issues that are no longer present
• Risk change: Whether the overall security posture improved, worsened, or stayed the same

Configuration

Initialize Configuration File

onionscan init

This creates .onionscan in the current directory with default settings.

Configuration File Format

# Default settings for all sites
defaults:
  cookie: ""
  depth: 100
  headers: {}
  ignore_patterns: []
  follow_patterns: []

# Site-specific configurations
sites:
  exampleonion.onion:
    cookie: "session_id=abc123"
    headers:
      Authorization: "Bearer token"
      X-Custom-Header: "value"
    depth: 50
    ignore_patterns:
      - "/logout"
      - "/admin/*"
    follow_patterns:
      - "/api/*"
      - "/docs/*"

  anotheronion.onion:
    cookie: "auth=xyz789"
    depth: 25

Report Examples

Text Report (Default)

======================================================================
                         ONIONSCAN REPORT
======================================================================

Hidden Service: exampleonion.onion
Scan Date:      2025-11-30 14:30:00 UTC
Pages Crawled:  42
Status:         Complete

----------------------------------------------------------------------
SEVERITY SUMMARY
----------------------------------------------------------------------

  CRITICAL: 1
  HIGH:     3
  MEDIUM:   5
  LOW:      2
  INFO:     4

  TOTAL:    15 findings

----------------------------------------------------------------------
DETECTED SERVICES
----------------------------------------------------------------------

  - HTTP (80)
  - SSH (22)

----------------------------------------------------------------------
CRITICAL FINDINGS
----------------------------------------------------------------------

  [!] Private Key Exposed
      Type:     Tor v3 Hidden Service Private Key
      Location: /backup/hs_ed25519_secret_key

      The hidden service private key is publicly accessible.
      Anyone can impersonate this hidden service.

...

Markdown Report

See doc/markdown-report.md for a full example.

The Markdown report includes:

• Summary table with scan metadata
• Severity distribution pie chart (Mermaid)
• GitHub-flavored alerts for critical issues
• Expandable details for each finding
• Recommendations column

Troubleshooting

Embedded Tor fails to start

Error: failed to start embedded Tor: ...

Solutions:

1. Ensure Tor is installed on your system (tor --version)
2. Check if another Tor process is already running (pgrep tor)
3. Increase the startup timeout: onionscan scan --tor-timeout 5m example.onion
4. Use an external Tor proxy instead: onionscan scan -e 127.0.0.1:9050 example.onion

Connection timeouts

Error: context deadline exceeded

Solutions:

1. Increase the request timeout: onionscan scan --timeout 5m example.onion
2. Check if the hidden service is online using Tor Browser
3. Verify your Tor connection is working properly

Configuration file not found

Error: configuration file not found: /path/to/config

When using --config with an explicit path, the file must exist. Without --config, OnionScan searches for .onionscan in:

1. Current directory
2. Home directory

If no file is found, default settings are used.

Out of memory on large sites

For sites with many pages, limit the crawl scope:

onionscan scan --max-pages 50 --depth 10 example.onion

Related Projects

• nao1215/tornago: Go library for Tor daemon management (used by OnionScan)
• s-rah/onionscan: The original OnionScan project that inspired this complete rewrite

Contributing

Contributions are welcome! Please see the Contributing Guide for more details.

Support

If you find this project useful, please consider:

• Giving it a star on GitHub - it helps others discover the project
• Becoming a sponsor - your support keeps the project alive and motivates continued development

License

MIT License