netprobe

module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2026 License: Apache-2.0

README

netprobe

Network probing for a fleet of machines. Edges measure the network from where they are; a central assigns their checks, stores the results, alerts, and shows them in a web UI.

  • Checks: ICMP, TCP, UDP, HTTP(S), DNS, NTP, path MTU, Paris traceroute with AS paths.
  • Edges only dial out (mutual TLS, private CA), no configuration on them.
  • TimescaleDB, data kept until you delete it. Alerts to signed webhooks.

All in one

One machine: database, central, one edge, Prometheus, Grafana with the netprobe dashboard, and Caddy for HTTPS. The edge enrolls by itself.

cd deploy/compose/all-in-one
cp .env.example .env          # secrets, SITE, TLS, PUBLIC_BIND, PUBLIC_URL
docker compose up -d --build
printf '%s\n' 'A-LONG-PASSWORD' | docker compose exec -T central netprobe-central user add --username admin --role admin

UI on https://SITE/, Grafana on https://SITE/grafana/ (admin, GRAFANA_ADMIN_PASSWORD). By default everything listens on 127.0.0.1 with SITE=localhost. On a server exposed to the internet:

  • PUBLIC_BIND=0.0.0.0: opens 80 and 443 (Caddy), 8443/tcp and 3478/udp (edges). Nothing else is published; Prometheus and the plain UI stay on 127.0.0.1.
  • SITE and TLS: a domain name with TLS=you@example.com for Let's Encrypt. With only a public IP, SITE=203-0-113-5.sslip.io (a name resolving to the IP) gets a Let's Encrypt certificate too; or SITE=203.0.113.5 with TLS=internal, a certificate from Caddy's own CA that browsers warn about.
  • PUBLIC_URL=https://203.0.113.5:8443: how remote edges reach the gateway. An IP is fine: edges pin the CA, they need no public certificate.

docker compose down -v removes everything.

Run

cd deploy/compose/central
cp .env.example .env          # DB_PASSWORD, PUBLIC_URL
docker compose up -d --build
docker compose exec central netprobe-central user add --username alice --role admin

UI on http://127.0.0.1:8080 (outside localhost: behind a TLS proxy, the session cookie is Secure; give the proxy address to NETPROBE_TRUSTED_PROXIES). Enroll an edge from the Edges page, then on the machine:

cd deploy/compose/edge
printf '%s' 'TOKEN' | docker compose run --rm -T edge enroll --central https://central.example.com:8443 --ca-hash sha256:... --token -
docker compose up -d

Ports: 8443/tcp and 3478/udp from the edges, 8080/tcp for the UI. AS numbers: put dbip-asn-lite.mmdb (db-ip.com, monthly) in deploy/compose/central/asn/. Without containers: make build, then the units in deploy/systemd/.

Commands (central)

netprobe-central serve                 run (flags: -h, each has a NETPROBE_* variable)
netprobe-central token --name N        enrollment token for an edge (--replace: reinstall)
netprobe-central user add|passwd|list|delete
netprobe-central data stats|export|delete --from 2026-01-01 --to 2026-04-01 [--yes]
netprobe-central audit                 who changed what
netprobe-central healthcheck           also GET /healthz

Back up the database (pg_dump -Fc) and the central volume: the CA (without it every edge must be enrolled again) and secrets.key (without it webhook secrets must be set again).

Grafana and Prometheus

  • GET /metrics on the admin port, Prometheus format, for scrapers sending Authorization: Bearer $NETPROBE_METRICS_TOKEN (16+ characters; unset, the endpoint does not exist): edges, last cycle of every check, AS paths, alerts.
  • NETPROBE_GRAFANA_PASSWORD creates the SQL login grafana: read-only, 30 s per query, limited to the views of the grafana schema (results, hourly results, traces, alerts, checks, edges), never users or secrets. The database user of the central needs CREATEROLE; without it, create the login by hand and GRANT netprobe_grafana TO grafana.
  • Dashboard and provisioning: deploy/compose/all-in-one/grafana/.

Webhooks

JSON POST on alert.firing / alert.resolved, with a text field for Slack and Mattermost. Check X-Netprobe-Signature = sha256= + hex(HMAC-SHA256(secret, X-Netprobe-Timestamp + "." + body)).

Develop

make dev-db tools       # local TimescaleDB, generators and linters
make build test-db      # binaries, all tests
make lint               # as in CI
make help               # everything else

API contracts: api/proto. Releases: tag vX.Y.Z with a CHANGELOG section; CI publishes signed images to GHCR.

CI runs what a change touches (Go, web, proto, images). A tag in the commit message forces a part: [ci go], [ci web], [ci proto], [ci images], [ci full]; [skip ci] runs nothing.

License: Apache 2.0.

Directories

Path Synopsis
cmd
netprobe-central command
Command netprobe-central runs the central: the gateway edges dial, the STUN server, the admin API and the UI.
 Command netprobe-central runs the central: the gateway edges dial, the STUN server, the admin API and the UI.
netprobe-edge command
Command netprobe-edge enrolls a machine with the central, then runs the checks the central assigns and reports their results.
 Command netprobe-edge enrolls a machine with the central, then runs the checks the central assigns and reports their results.
gen
netprobe/v1
netprobe/v1/netprobev1connect
internal
central
Package central is the composition root of the central: it reads the configuration, builds every part and serves the three listeners (edge gateway, STUN, API and UI).
 Package central is the composition root of the central: it reads the configuration, builds every part and serves the three listeners (edge gateway, STUN, API and UI).
central/alerting
Package alerting turns rules into alerts and alerts into signed webhooks.
 Package alerting turns rules into alerts and alerts into signed webhooks.
central/api
Package api implements the API used by the UI: edges, targets, results, traceroutes, data lifecycle, accounts and alerting.
 Package api implements the API used by the UI: edges, targets, results, traceroutes, data lifecycle, accounts and alerting.
central/asn
Package asn looks up the autonomous system of an address in a MaxMind DB file (DB-IP ASN Lite or GeoLite2-ASN).
 Package asn looks up the autonomous system of an address in a MaxMind DB file (DB-IP ASN Lite or GeoLite2-ASN).
central/audit
Package audit records every change made through the admin API.
 Package audit records every change made through the admin API.
central/auth
Package auth handles UI accounts: password login and cookie sessions.
 Package auth handles UI accounts: password login and cookie sessions.
central/enroll
Package enroll owns the enrollment token: its format, how it is made and read back, and the command an operator runs on a new edge.
 Package enroll owns the enrollment token: its format, how it is made and read back, and the command an operator runs on a new edge.
central/export
Package export writes measurements as CSV, for archives and spreadsheets.
 Package export writes measurements as CSV, for archives and spreadsheets.
central/fleet
Package fleet holds the live state of the edges: sessions, assignments and observed addresses.
 Package fleet holds the live state of the edges: sessions, assignments and observed addresses.
central/gateway
Package gateway implements the internet facing side of the central: enrollment, certificate renewal, edge sessions, result reports and STUN.
 Package gateway implements the internet facing side of the central: enrollment, certificate renewal, edge sessions, result reports and STUN.
central/realip
Package realip recovers the client address behind a reverse proxy.
 Package realip recovers the client address behind a reverse proxy.
central/secrets
Package secrets seals values kept in the database, the webhook signing secrets, with a key stored next to the CA: a copy of the database alone is not enough to forge signatures.
 Package secrets seals values kept in the database, the webhook signing secrets, with a key stored next to the CA: a copy of the database alone is not enough to forge signatures.
central/store
Package store keeps everything the central knows in PostgreSQL with TimescaleDB.
 Package store keeps everything the central knows in PostgreSQL with TimescaleDB.
central/store/storetest
Package storetest gives tests a fresh database, created from NETPROBE_TEST_DATABASE_URL and dropped at the end.
 Package storetest gives tests a fresh database, created from NETPROBE_TEST_DATABASE_URL and dropped at the end.
check
Package check owns what a check is: its protocols, its settings, the rules a valid check follows and its options.
 Package check owns what a check is: its protocols, its settings, the rules a valid check follows and its options.
edge
Package edge is the agent: enrollment, the session with the central, the check scheduler and the local result buffer.
 Package edge is the agent: enrollment, the session with the central, the check scheduler and the local result buffer.
pki
Package pki is the private certificate authority of the central: server and edge certificates, and the fingerprint edges pin.
 Package pki is the private certificate authority of the central: server and edge certificates, and the fingerprint edges pin.
probe
Package probe measures the network: ICMP, TCP and UDP round trips, and Paris traceroutes.
 Package probe measures the network: ICMP, TCP and UDP round trips, and Paris traceroutes.
ratelimit
Package ratelimit limits events per key (an address, a user name) with a bounded memory: past the maximum, keys back to their initial state are dropped first (nothing is lost), then the least recently seen.
 Package ratelimit limits events per key (an address, a user name) with a bounded memory: past the maximum, keys back to their initial state are dropped first (nothing is lost), then the least recently seen.
stats
Package stats summarizes round-trip samples: min, average, max, standard deviation, RFC 3550 jitter, loss and voice quality (MOS).
 Package stats summarizes round-trip samples: min, average, max, standard deviation, RFC 3550 jitter, loss and voice quality (MOS).
stunclient
Package stunclient asks the STUN server of the central for the public address of the edge, with short-term credentials.
 Package stunclient asks the STUN server of the central for the public address of the edge, with short-term credentials.
version
Package version holds the build information, set at link time:
 Package version holds the build information, set at link time:
Package web embeds the built UI (web/dist) into the central binary.
 Package web embeds the built UI (web/dist) into the central binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.