onionprobe 1.0.0

Test and monitors the status of Tor Onion Services

Onionprobe

Onionprobe is a tool for testing and monitoring the status of Tor Onion Services sites.

It can run a single time or continuously to probe a set of onion services endpoints and paths, optionally exporting to Prometheus.

Requirements

Onionprobe requires the following software:

• Python 3
• Stem Tor Control library
• Prometheus Python client
• PyYAML
• Requests
• PySocks
• Tor daemon

On Debian, they can be installed using

sudo apt install python3 python3-prometheus-client \
                 python3-stem python3-cryptography \
                 python3-yaml python3-requests     \
                 python3-socks tor

Installation

Onionprobe is available on PyPI:

pip install onionprobe

It's also possible to run it directly from the Git repository:

git clone https://gitlab.torproject.org/tpo/onion-services/onionprobe
cd onionprobe

Usage

Simply ask Onionprobe to try an Onion Service site:

onionprobe -e http://2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion

It's possible to supply multiple addresses:

onionprobe -e <onion-address1> <onionaddress2> ...

Onionprobe also accepts a configuration file with a list of .onion endpoints and options. A detailed sample config is provided and can be invoked with:

onionprobe -c configs/tor.yaml

By default, Onionprobe starts it's own Tor daemon instance, so the tor binary must be available in the system.

See the manual page for the complete list of options and available metrics.

Standalone monitoring node

Onionprobe comes with full monitoring environment based on Docker Compose with:

• An Onionprobe instance continuously monitoring endpoints.
• Metrics are exported to a Prometheus instance.
• Alerts are managed using Alertmanager.
• A Grafana Dashboard is available for browsing the metrics and using a PostgreSQL service container as the database backend.

Configuring the monitoring node

By default, the monitoring node periodically compiles the Onionprobe configuration from the official Tor Project Onion Services into contrib/tpo.yaml, by using the tpo.py script.

This and other configurations can be changed by creating an .env file in the toplevel project folder.

Check the sample .env for an example.

Starting the monitoring node

The monitoring node may be started using docker-compose:

docker-compose up -d   # Remove "-d" to not fork into the background
docker-compose logs -f # View container logs

The monitoring node sets up storage volumes, which means that the monitoring dataset collected is persistent across service container reboots.

Accessing the monitoring dashboards and the exporter

Once the dashboards are started, point your browser to the following addresses if you're running locally:

• The built-in Prometheus dashboard: http://localhost:9090
• The built-in Alertmanager dashboard: http://localhost:9093
• The built-in Grafana dashboard: http://localhost:3030
• The built-in Onionprobe Prometheus exporter: http://localhost:9935

These services are also automatically exported as Onion Services, which addresses can be discovered by running the following commands when the services are running:

docker exec -ti onionprobe_tor_1 cat /var/lib/tor/prometheus/hostname
docker exec -ti onionprobe_tor_1 cat /var/lib/tor/alertmanager/hostname
docker exec -ti onionprobe_tor_1 cat /var/lib/tor/grafana/hostname
docker exec -ti onionprobe_tor_1 cat /var/lib/tor/onionprobe/hostname

You can also get this info from the host by browsing directly the onionprobe_tor volume.

It's also possible to replace the automatically generated Onion Service addresses by using keys with vanity addresses using a tool like Onionmine.

Protecting the monitoring dashboards and the exporter

By default, all dashboards and the are accessible without credentials.

You can protect them by setting up Client Authorization:

0. Enter in the tor service container: docker exec -ti onionprobe_tor_1 /bin/bash.

1. Setup your client credentials according to the docs. The tor service container already comes with all programs to generate it. Onionprobe ships with a handy generate-auth-keys-for-all-onion-services available at the tor service container and which can be invoked with docker exec -ti onionprobe_tor_1 /usr/local/bin/generate-auth-keys-for-all-onion-services (it also accepts an optional auth name parameter allowing multiple credentials to be deployed).

2. Place the .auth files at the Onion Services authorized_clients folder if you did not created them with the generate-auth-keys-for-all-onion-services script:

   • Prometheus: /var/lib/tor/prometheus/authorized_clients.
   • Alertmanager: /var/lib/tor/alertmanager/authorized_clients.
   • Grafana: /var/lib/tor/grafana/authorized_clients.
   • Onionprobe: /var/lib/tor/onionprobe/authorized_clients.

3. Restart the tor service container from the host to ensure that this new configuration is applied:

    docker compose stop tor
    docker compose up -d
   

Note that the Grafana dashboard also comes with it's own user management system, whose default user and password is admin. You might change this default user and not setup the Client Authorization for Grafana, or maybe use both depending or your security needs.

Managing the monitoring node with systemd

The monitoring node can be managed with systemd. A sample service file is provided and can be adapted..

Using the monitoring node

Once your monitoring node is up and running, you can create your dashboards an visualizations as usual, getting the data compiled by Onionprobe using Prometheus as the data source.

Grafana already comes with a basic default dashboard as it's homepage:

Compiled configurations

Besides the sample config containing sites listed at https://onion.torproject.org, Onionprobe comes also with other example configs:

0. Official Tor Project Onion Service Sites, generated by the tpo.py script.
1. Real-World Onion Sites .onions at real-world-onion-sites.yaml, generated by the real-world-onion-sites.py script.
2. The SecureDrop API .onions at securedrop.yaml, generated by the securedrop.py script.

You can build your own configuration compiler by using the OnionprobeConfigCompiler class.

Folder structure and files

Relevant folders and files in this repository:

• assets: logos and other stuff.
• configs: miscelaneous configurations.
• contrib: folder reserved for storing contributed code and configuration.
• containers: container configurations.
• debian: debian packaging.
• docs: documentation.
• packages: python packages codebase.
• scripts: provisioning and other configuration scripts.
• tests: test procedures.
• vendors: other third-party libraries and helpers.
• kvmxfile: please ignore this if you're not a KVMX user.
• docker-compose.yml: service container configuration.

Tasks

Check the issue tracker.

Acknowledgements

Thanks to:

• @irl for the idea/specs/tasks.
• @hiro for suggestions.
• @arma and @juga for references.
• @anarcat and @georg for Python and Debian packaging guidance and review.

Alternatives

• OnionScan
• Webmon has support for Onion Services monitoring if used along with Orbot.
• BrassHornCommunications/OnionWatch: A GoLang daemon for notifying Tor Relay and Hidden Service admins of status changes
• systemli/prometheus-onion-service-exporter: Prometheus Exporter for Tor Onion Services
• prometheus/blackbox_exporter: Blackbox prober exporter, which could be configured using proxy_url pointing to a Privoxy instance relaying traffic to tor daemon. See this issue for details.

Known issues

From Stem:

• Python 3.9 warning · Issue #105 · torproject/stem
• noisy log: stem: INFO: Error while receiving a control message (SocketClosed): received exception "peek of closed file" · Issue #112 · torproject/stem · GitHub

References

Related software and libraries with useful routines:

• onbasca
• sbws
• Stem
• txtorcon
• Onionbalance
• hs-health

Relevant issues:

• Write a hidden service hsdir health measurer
• Write tool for onion service health assessment

Research questions:

• When an onion service lookup has failed at the first k HSDirs we tried, what are the chances it will still succeed?
• What's the average number of hsdir fetches before we get the hsdesc?