Hyrule Prober

Internal multi-vantage probe service for Hyrule Cloud's paid /v1/path/* diagnostics — the execution backend of the AS215932 "x402-payable looking glass". Runs on the noc VM; executes real ping/traceroute/dig locally and over SSH from configured vantage points (e.g. cr1-nl1, cr1-de1, rtr).

hyrule-cloud verifies and settles x402 payments; this service accepts only authenticated internal requests from hyrule-cloud. It is not a public service and must not be exposed to the Internet (same posture as hyrule-network-proxy).

Internal API

All /v1/* endpoints require:

Authorization: Bearer <HYRULE_PROBER_AUTH_TOKEN>

GET /v1/health

{
  "status": "ok",
  "service": "hyrule-prober",
  "version": "0.1.0",
  "vantages": {"noc": {"ok": true, "checked_at": "…", "latency_ms": 3, "error": null}}
}

status is degraded unless every configured vantage passed its last background check (HYRULE_PROBER_HEALTH_INTERVAL_S, default 60s).

POST /v1/probe

{
  "target": "example.com",
  "kind": "ping",            // ping | traceroute | dig
  "family": "any",           // any | ipv4 | ipv6 (any prefers IPv6)
  "count": 4,                 // ping only, <=10
  "max_hops": 20,             // traceroute only, <=30
  "record_type": "AAAA",     // dig only
  "vantages": [],             // empty = all configured
  "timeout_s": 10
}

Response carries per-vantage structured results (ping.rtt_ms, ping.loss_pct, traceroute.hops, dig.answers) plus a bounded raw_excerpt; a ping with 100% loss is a successful measurement (ok=true, loss recorded), not an error.

Safety

• Targets must be bare hostnames/IPs resolving only to globally-routable addresses — loopback, RFC1918/ULA, link-local, and multicast are refused with 400 before any command runs (hyrule-cloud validates too; this is defense in depth).
• Commands are fixed argv templates — no shell interpolation of caller data.
• Sliding-window rate limits: per-target (default 6/min) and global (default 60/min) → 429.
• Fail-closed auth: an empty HYRULE_PROBER_AUTH_TOKEN refuses every request.

Configuration (env, prefix HYRULE_PROBER_)

Variable	Default	Meaning
AUTH_TOKEN	(empty = refuse all)	bearer token shared with hyrule-cloud (Vault)
HOST / PORT	:: / 8460	bind address
VANTAGES	[{"name":"noc","address":"local"}]	JSON array; address:"local" = subprocess, else SSH (user, key, os: linux|freebsd, tools)
COMMAND_TIMEOUT_S	20	hard per-command budget
RATE_LIMIT_PER_TARGET_PER_MINUTE	6
RATE_LIMIT_GLOBAL_PER_MINUTE	60
HEALTH_INTERVAL_S	60	vantage health refresh cadence

FreeBSD vantages (cr1-*) typically set "tools": ["ping", "traceroute"] (no dig) and get traceroute6/traceroute selected by family automatically.

Run

python -m venv .venv && .venv/bin/pip install -e '.[dev]'
HYRULE_PROBER_AUTH_TOKEN=dev .venv/bin/uvicorn hyrule_prober.app:app --host :: --port 8460
.venv/bin/pytest -q

Deployment (systemd unit, Vault-sourced token, firewall flows api→noc:8460, Icinga health check) lives in network-operations.