onionlint is a CLI tool for anonymity risk diagnosis of .onion sites. It performs static checks and Tor-based crawling to detect potential anonymity risks such as external resource loading, tracking headers, insecure cookies, and fingerprinting vectors.

All traffic is routed through Tor to maintain anonymity during scanning.

This project was created to demonstrate and validate the capabilities of tornago, a lightweight Go wrapper around the Tor command-line tool. By building a practical application that leverages Tor's client functionality, we can showcase how tornago enables Go developers to easily integrate Tor-based networking into their applications.

onionlint serves as both a useful security tool and a real-world example of tornago in action - managing Tor daemon lifecycle, routing HTTP traffic through Tor's SOCKS5 proxy, and accessing .onion hidden services programmatically.

• Anonymity risk detection for .onion sites
• 34 built-in rules across 3 categories (Visitor Protection, Operator Protection, Attack Detection)
• Tor-based crawling with configurable depth
• Multiple output formats (text, JSON, Markdown)
• Configurable rules via YAML configuration file
• Embedded Tor daemon or system Tor support

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

• Linux
• macOS
• Windows
• Go 1.25 or later

onionlint requires the Tor daemon to be installed on your system when using system Tor mode. The embedded Tor mode will automatically manage the Tor process.

Installation:

# 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

onionlint scan http://example.onion/

# Scan with increased crawl depth
onionlint scan http://example.onion/ --depth 3

# Output as JSON
onionlint scan http://example.onion/ --format json

# Output as Markdown to file
onionlint scan http://example.onion/ --format md --out report.md

# Use custom configuration
onionlint scan http://example.onion/ --config custom.yml

# Use system Tor instead of embedded
onionlint scan http://example.onion/ --tor-mode system

onionlint rules

onionlint init

This creates a .onionlint.yml file with default settings.

The .onionlint.yml file allows you to customize onionlint behavior:

# Rule configuration
rules:
  # Disable specific rules
  disable:
    - favicon_fingerprint
    - update_pattern_leak

  # Or enable only specific rules (overrides disable)
  # enable:
  #   - no_external_resources
  #   - mixed_content_leak

# Severity overrides
severity:
  etag_tracking: high
  cookie_insecure: low

# Scan settings
scan:
  depth: 2
  timeout: 60s

onionlint includes 34 rules organized into 3 categories:

Rules that protect site visitors from tracking, fingerprinting, and deanonymization.

Rules that protect site operators from identification and correlation attacks.

Rules that detect potential attacks against site visitors.

Scan Results for: http://example.onion/
Resources scanned: 5
Issues found: 3 (High: 2, Medium: 1, Low: 0)

[1] HIGH
    Rule:    no_external_resources
    Message: External script loaded from clearnet
    URL:     http://example.onion/
    Details: External resource 'https://cdn.example.com/script.js' loaded

onionlint scan http://example.onion/ --format json

{
  "url": "http://example.onion/",
  "resource_count": 5,
  "issues": [...],
  "summary": {
    "high": 2,
    "medium": 1,
    "low": 0,
    "total": 3
  }
}

onionlint scan http://example.onion/ --format md --out report.md

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

First off, thanks for taking the time to contribute! Contributions are not only related to development. For example, GitHub Star motivates me to develop!

If you would like to send comments such as "find a bug" or "request for additional features" to the developer, please use one of the following contacts.

• GitHub Issue

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

Your support, whether through stars, sponsorships, or contributions, is what drives this project forward. Thank you!

The onionlint project is licensed under the terms of MIT LICENSE.