Repolode
Enviar
quyxishi

quyxishi/whitebox

Exporter de Prometheus que prueba servicios VPN externos mediante VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks e Hysteria2 para informar de su disponibilidad.

Ver en GitHubSitio web
Estrellas
162
Forks
14
Issues abiertos
1
Último commit
hace 6 días

¿Qué es?

whitebox es un exporter de Prometheus que comprueba si se puede acceder a servicios VPN externos y si funcionan correctamente. Se le proporciona un URI de conexión VPN y una URL de destino; crea un túnel a través de esa VPN, solicita el recurso de destino y devuelve el resultado como métricas de Prometheus sobre el éxito, el estado HTTP, el tiempo de cada fase y el tamaño de la respuesta.

Admite los protocolos VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks e Hysteria2. Las pruebas se pueden ejecutar bajo demanda mediante un endpoint REST, programar desde Prometheus con el patrón de exporter multiobjetivo o invocar desde una tarea cron con curl. Un archivo de configuración YAML permite definir ámbitos con nombre, tiempos de espera, cuerpos de solicitud, encabezados personalizados y reglas de validación fail_if; se vuelve a cargar al recibir SIGHUP.

El exporter reutiliza instancias de xray ya iniciadas entre las pruebas para mantener acotado el uso de memoria y expone estadísticas de su propia caché en /metrics. Se distribuye como imagen de Docker e incluye un stack de ejemplo con Prometheus, blackbox_exporter y Grafana.

Funciones clave

  • 01Prueba túneles mediante VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks e Hysteria2.
  • 02Expone los resultados de las pruebas como métricas de Prometheus, incluidos el éxito, el código de estado y el tiempo de cada fase.
  • 03Ofrece un endpoint REST /probe para ejecutar comprobaciones bajo demanda o programadas.
  • 04Admite ámbitos YAML con tiempos de espera, cuerpos de solicitud, encabezados y reglas de validación de respuestas.
  • 05Vuelve a cargar la configuración al recibir SIGHUP, sin necesidad de reiniciar.
  • 06Reutiliza instancias de xray entre pruebas y expone métricas de caché.

Casos de uso

  • Supervisar en Prometheus y Grafana la disponibilidad de nodos VPN propios o de terceros.
  • Ejecutar comprobaciones programadas de accesibilidad para un conjunto de URI de conexión VPN.
  • Probar rápidamente si una conexión VPN puede acceder a una URL determinada.

Inicio rápido

  1. 1

    Ejecuta la imagen de Docker precompilada

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

    Sondea un objetivo mediante un URI de conexión VPN

    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'

Antes de usarlo

  • Para sondear cada objetivo se necesita un URI de conexión VPN operativo, por lo que debes proporcionar los datos de tu propio servidor VPN.
  • El uso de memoria puede crecer sin límite si no se habilita la caché de instancias de xray o se establece un límite de memoria para el contenedor.

Temas

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

Preguntas frecuentes

¿Qué es whitebox?
Exporter de Prometheus que prueba servicios VPN externos mediante VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks e Hysteria2 para informar de su disponibilidad. whitebox es un exporter de Prometheus que comprueba si se puede acceder a servicios VPN externos y si funcionan correctamente. Se le proporciona un URI de conexión VPN y una URL de destino; crea un túnel a través de esa VPN, solicita el recurso de destino y devuelve el resultado como métricas de Prometheus sobre el éxito, el estado HTTP, el tiempo de cada fase y el tamaño de la respuesta.
¿whitebox es gratuito? ¿Qué licencia tiene?
whitebox es open source bajo la licencia MIT. Revisa los términos de la licencia antes de usarlo en productos comerciales.
¿whitebox sigue mantenido?
Mantenimiento activo. El último commit de whitebox fue el 14 oct 2026.
¿Para qué puedo usar whitebox?
Supervisar en Prometheus y Grafana la disponibilidad de nodos VPN propios o de terceros. Ejecutar comprobaciones programadas de accesibilidad para un conjunto de URI de conexión VPN. Probar rápidamente si una conexión VPN puede acceder a una URL determinada.
¿Cómo se instala whitebox?
Ejecuta la imagen de Docker precompilada: docker run --rm -d --name whitebox -p 9116:9116 rxyvea/whitebox:latest Sondea un objetivo mediante un URI de conexión VPN: 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'
¿Dónde consigo whitebox?
El código fuente y las instrucciones de instalación están en GitHub: https://github.com/quyxishi/whitebox

Resumen generado por IA a partir del README del proyecto. Las estadísticas de GitHub se actualizan a diario.

Proyectos relacionados