OnionScan

OnionScan audits Tor v3 onion services for operational-security mistakes, exposed identity signals, vulnerable server configuration, and unexpected network services. It starts Tor for you or uses an existing SOCKS5 proxy, crawls the target, runs focused analyzers, and writes text, JSON, or Markdown reports.

This is a modern Go rewrite inspired by s-rah/onionscan. It supports current 56-character onion addresses, concurrent scans, per-site configuration, scan history, and comparison reports.

The crawler supports configurable depth, page limits, delays, response-size limits, headers, cookies, and allow or ignore patterns. Sensitive values in logs are redacted automatically.

• Go 1.26.9 or later when building from source
• A tor executable on PATH

Install Tor with the package manager for your platform:

# Ubuntu or Debian
sudo apt update
sudo apt install tor

# Fedora or RHEL
sudo dnf install tor

# Arch Linux
sudo pacman -S tor

# macOS
brew install tor

# Windows
choco install tor

brew install nao1215/tap/onionscan

yay -S onionscan-bin   # or: paru -S onionscan-bin

onionscan-bin is community-maintained and installs the release binary.

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

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

Release archives are available from the GitHub Releases page.

Releases from v0.2.5 on ship supply-chain metadata so you can verify what you download:

• Signed checksums: checksums.txt is signed with cosign (keyless), producing checksums.txt.sigstore.json.
• SBOM: an SPDX Software Bill of Materials is attached to each release archive as <archive>.sbom.json.
• Build provenance: SLSA build provenance is attested via GitHub OIDC, and is also attached to the release as multiple.intoto.jsonl.

Verify the signed checksums (then check your archive against checksums.txt):

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/nao1215/onionscan/\.github/workflows/release\.yml@refs/tags/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt
sha256sum --check --ignore-missing checksums.txt

Verify the build provenance of a downloaded artifact with the GitHub CLI:

gh attestation verify onionscan_<version>_<os>_<arch>.tar.gz --repo nao1215/onionscan

Or download the multiple.intoto.jsonl release asset and verify the archive against it with slsa-verifier, which checks the provenance signature against the Sigstore transparency log:

slsa-verifier verify-artifact onionscan_<version>_<os>_<arch>.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/nao1215/onionscan \
  --source-tag v<version>

Scan one service with an automatically managed Tor process:

onionscan scan your-service.onion

Use a Tor daemon that is already running:

onionscan scan --external-tor 127.0.0.1:9050 your-service.onion

Scan several services concurrently:

onionscan scan --batch 3 first-service.onion second-service.onion third-service.onion

Write machine-readable or review-friendly reports:

onionscan scan --json --output report.json your-service.onion
onionscan scan --markdown --output report.md your-service.onion

Tune the crawl for an authorized test:

onionscan scan \
  --depth 25 \
  --max-pages 100 \
  --timeout 3m \
  --crawl-delay 2s \
  your-service.onion

Run onionscan scan --help for the complete command reference.

When --batch is greater than 1, site-specific cookies, headers, and depth settings are not applied. Use --batch 1 when those settings are required.

Create a documented starter file:

onionscan init

OnionScan looks for .onionscan in the current directory and then the home directory. An explicit --config path must exist.

defaults:
  cookie: ""
  depth: 50
  headers: {}
  ignore_patterns: []
  follow_patterns: []

sites:
  your-service.onion:
    cookie: "session_id=replace-me"
    headers:
      Authorization: "Bearer replace-me"
    depth: 20
    ignore_patterns:
      - "/logout"
      - "/admin/*"
    follow_patterns:
      - "/docs/*"

Restrict configuration-file permissions because cookies and authorization headers may be sensitive.

Every scan is stored in a local SQLite database. The location follows the XDG conventions used by the operating system.

Compare the latest two scans or inspect history:

onionscan compare your-service.onion
onionscan compare --list your-service.onion
onionscan compare --list-services
onionscan compare --with-scan-id 5 your-service.onion
onionscan compare --since 2026-01-01 your-service.onion
onionscan compare --json your-service.onion
onionscan compare --markdown your-service.onion

Comparison reports identify new, resolved, and unchanged findings and summarize whether risk improved, worsened, or stayed unchanged.

The default text report is designed for terminals. JSON preserves structured scan data for automation. Markdown produces a reviewable report with severity summaries and detailed findings.

See the Markdown report example.

Report files are created with owner-only permissions because they can contain sensitive findings.

Run the fast Go test suite:

make test

Run the real CLI through atago:

make e2e

The E2E suite builds a local HTTP fixture, exposes it as an ephemeral Tor v3 onion service with tornago, and points OnionScan at the fixture's own SOCKS5 proxy. It does not depend on a public onion site. The suite checks version output, configuration generation, JSON scanning, database persistence, and comparison behavior.

Generate one coverage profile from both Go unit tests and the atago-driven CLI runs:

make coverage

The command writes coverage.out and coverage.html. Real-Tor Go integration tests retained for focused debugging are opt-in:

make test-integration

Check the installed binary and allow more bootstrap time:

tor --version
onionscan scan --tor-timeout 5m your-service.onion

You can also use an existing proxy with --external-tor.

Onion services can be slow or offline. Confirm the address in Tor Browser, then increase the request timeout or reduce crawl scope:

onionscan scan --timeout 5m --depth 10 --max-pages 50 your-service.onion

When --config is present, OnionScan treats a missing file as an error. Remove the flag to use automatic discovery or provide the correct path.

• nao1215/tornago provides the Tor process, client, and hidden-service APIs used by OnionScan.
• nao1215/atago verifies OnionScan's real CLI behavior from YAML scenarios.
• s-rah/onionscan is the original project that inspired this rewrite.

Contributions are welcome. Read CONTRIBUTING.md before opening a change. Security reports should follow SECURITY.md.

If OnionScan is useful to you, star the repository or sponsor the maintainer.

Thanks goes to these wonderful people (emoji key):

CHIKAMATSU Naohiro 💻 📖

Rafael Baboni Dominiquini 📦

This project follows the all-contributors specification. Contributions of any kind welcome!

MIT License