UpHeron
View as Markdown

Port scans, route traces and IPv6

Port scans

On the Business plan, a network or website monitor can scan its host's common TCP ports every week and alert its contacts when a port opens that was closed in the scan before. Open ports that usually should not be reachable from the internet (databases, Redis, Memcached, Elasticsearch, the Docker and Kubernetes APIs, remote desktop, file sharing) are flagged on the monitor's page and in the alert.

What a scan does

  • Ports: a fixed list of about 100 TCP ports where servers most often listen: web, mail, SSH, databases, caches, search engines, message brokers, container and cluster APIs, remote access and monitoring tools. GET /api/v1/monitors/{id}/ports lists what each found port usually runs.
  • How: one ordinary TCP connection per port, closed as soon as it opens, with nothing sent on it. A few connections run at a time, so a scan takes from a few seconds to about a minute per address. It never sends anything else and never tries to log in.
  • From where: one UpHeron monitoring location, one the monitor checks from where it can. The file verification request identifies itself as UpHeron-PortScan/1.0.
  • When: every week, and when you press Scan now on the monitor's page (at most once an hour).
  • Which addresses: the host's public addresses that you have proved you control (below): IPv4, and IPv6 when the scanning location has IPv6. Private and reserved addresses are never scanned, whatever the host resolves to.

The first scan records what is open; later scans alert on ports that were closed before.

Proving you control each address

UpHeron scans only addresses whose owner asked for it, and proves each address on its own: anyone can point a domain at someone else's server, so proving the domain is not enough. On the monitor's page, Open ports shows a token and lists the host's addresses with what covers each. An address is covered in one of two ways:

  • It serves a file: http://<host>/.well-known/upheron-verification.txt (or https), containing only the token, answered by that address. A host given as an IP address can only use the file.
  • Its reverse DNS is under the host: publish a DNS TXT record at _upheron-verification.<host> with the value upheron-verification=<token>, and set the address's reverse DNS (PTR record, at the provider that owns the address) to the host or a name under it, such as db.example.com for example.com. That name must resolve back to the address. This suits servers that run no web server, such as a database host.

The TXT record alone covers no address. Press Verify now after publishing; addresses that are not covered are listed with what to do, and are not scanned.

Keep the proof in place: it is checked again before every scan, and an address whose proof is gone is left out (a scan with none runs no connections). To stop the scans, turn off New open ports on the host in the monitor's settings, or remove the file, record or reverse DNS.

Through the API, send "port_scan": true with the monitor, then POST /api/v1/monitors/{id}/ports/verify and POST /api/v1/monitors/{id}/ports/scan. MCP clients have get_ports, verify_host and scan_ports.

Route traces

On the Pro and Business plans, when a network or website check fails at a location, that location traces the route to the host: each hop's address, name, loss and round trips over three rounds, like mtr. It connects to the check's TCP port where the check uses TCP, so the trace takes the same path through firewalls as the check; other checks are traced with ICMP echoes (or UDP).

A trace tells a network problem (the path stops at a router before the host) from a server that is down (the path reaches the host, which does not answer). It shows with the failed check under Recent checks, under Route traces on the monitor's page, and in the incident's timeline.

Each monitor and location is traced at most once an hour, and once per incident; a workspace gets at most 20 traces an hour. Traces are kept 30 days; an incident's timeline keeps its own. Through the API, GET /api/v1/monitors/{id} returns them as traces, and incidents carry them as traceroute events.

IPv4 and IPv6

Every network and website monitor has an IP version, on every plan:

  • Automatic (auto, the default) connects over IPv4, or over IPv6 when the host has no IPv4 address.
  • IPv4 only (ipv4) and IPv6 only (ipv6) check only that address, for example to watch a site's IPv6 separately from its IPv4.

A host given as an IP address decides the version. IPv6-only monitors run only from locations with working IPv6, which the monitor form and GET /api/v1/locations ("ipv6": true) show; each location's agents test their IPv6 every ten minutes.