Repolode
Submit
quyxishi

quyxishi/whitebox

A Prometheus exporter that probes external VPN services over VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks and Hysteria2 to report their availability.

View on GitHubWebsite
Stars
162
Forks
14
Open issues
1
Last commit
6 days ago

What is it?

whitebox is a Prometheus exporter for checking whether external VPN services are reachable and working. You pass it a VPN connection URI and a target URL; it builds a tunnel through that VPN, fetches the target, and returns the result as Prometheus metrics covering success, HTTP status, timing by phase, and response size.

Supported protocols include VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks and Hysteria2. Probes can be run on demand through a REST endpoint, scheduled from Prometheus using the multi-target exporter pattern, or called from a cron job with curl. A YAML configuration file adds named scopes, timeouts, request bodies, custom headers and fail_if validation rules, and reloads on SIGHUP.

The exporter reuses started xray instances across probes to keep memory bounded, and exposes its own cache statistics on /metrics. It ships as a Docker image and includes an example stack with Prometheus, blackbox_exporter and Grafana.

Key features

  • 01Probes tunnels over VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks and Hysteria2.
  • 02Exposes probe results as Prometheus metrics, including success, status code and per-phase timing.
  • 03Provides a REST /probe endpoint for on-demand or scheduled checks.
  • 04Supports YAML scopes with timeouts, request bodies, headers and response validation rules.
  • 05Reloads configuration on SIGHUP without restarting.
  • 06Reuses xray instances across probes and exposes cache metrics.

Use cases

  • Monitoring the availability of self-hosted or third-party VPN nodes in Prometheus and Grafana.
  • Running scheduled reachability checks for a fleet of VPN connection URIs.
  • Quick one-off testing of whether a VPN connection can reach a given URL.

Quick start

  1. 1

    Run the prebuilt Docker image

    docker run --rm -d --name whitebox -p 9116:9116 rxyvea/whitebox:latest
  2. 2

    Probe a target through a VPN connection URI

    curl -sG http://localhost:9116/probe --data-urlencode 'ctx=vless://c9f5228c-8870-47bd-a92f-9b38c7c02b08@1.2.3.4:443?type=tcp&encryption=none&security=reality&pbk=DF-3KL2W4RuNB2HgsEDmLqHLvvTTN4_QfwUCUn8Uhy0&fp=firefox&sni=ce-cdn.icloud-content.com&sid=620352b7&spx=%2F&flow=xtls-rprx-vision' --data-urlencode 'target=https://google.com'

Things to know

  • Probing requires a working VPN connection URI for each target, so you must supply your own VPN server details.
  • Memory can grow without bounds unless the xray instance cache is enabled or the container has a memory cap.

Topics

#prometheus#exporter#monitoring#vpn#uptime#wireguard#xray#probe#amnezia-wg#checker

FAQ

What is whitebox?
A Prometheus exporter that probes external VPN services over VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks and Hysteria2 to report their availability. whitebox is a Prometheus exporter for checking whether external VPN services are reachable and working. You pass it a VPN connection URI and a target URL; it builds a tunnel through that VPN, fetches the target, and returns the result as Prometheus metrics covering success, HTTP status, timing by phase, and response size.
Is whitebox free to use? What license does it have?
whitebox is open source under the MIT license. Check the license terms before using it in commercial products.
Is whitebox still maintained?
Actively maintained. The last commit to whitebox was on Oct 14, 2026.
What can I use whitebox for?
Monitoring the availability of self-hosted or third-party VPN nodes in Prometheus and Grafana. Running scheduled reachability checks for a fleet of VPN connection URIs. Quick one-off testing of whether a VPN connection can reach a given URL.
How do I install whitebox?
Run the prebuilt Docker image: docker run --rm -d --name whitebox -p 9116:9116 rxyvea/whitebox:latest Probe a target through a VPN connection URI: curl -sG http://localhost:9116/probe --data-urlencode 'ctx=vless://c9f5228c-8870-47bd-a92f-9b38c7c02b08@1.2.3.4:443?type=tcp&encryption=none&security=reality&pbk=DF-3KL2W4RuNB2HgsEDmLqHLvvTTN4_QfwUCUn8Uhy0&fp=firefox&sni=ce-cdn.icloud-content.com&sid=620352b7&spx=%2F&flow=xtls-rprx-vision' --data-urlencode 'target=https://google.com'
Where can I get whitebox?
The source code and installation instructions are on GitHub: https://github.com/quyxishi/whitebox

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects