Pulsar

The satellite: a disposable container that scans from where it runs and keeps working when Polaris is away.

Pulsar is a Python 3 asyncio process with nmap, traceroute and ping in one container. It has no database and no access to Polaris’ data: it gets plans and targets, runs checks, and reports results. It does not know or care whether it serves one tenant or all.

Tasks inside one Pulsar container and what they exchange with Polaris and the /data volume.

Life of a satellite

Register — once at start: sends its instance id, version, hostname, capabilities (checks, nmap version, raw sockets, traceroute, websocket) and tags. Polaris binds the credentials to this instance; another instance with the same credentials is refused (HTTP 409). Retries with backoff up to 10 minutes.
Heartbeat every 30 s (POLARIS_HEARTBEAT_INTERVAL): ICMP and HTTPS round-trip time to Polaris, IPv4/IPv6 connectivity (rechecked every 15 minutes), websocket state, size of the upload queue, plan version, load sample and the runs it still works on. The answer tells the satellite its public address and place as Polaris sees them (shown on its status page); the satellite asks no geolocation service itself.
Sync every 60 s (POLARIS_SYNC_INTERVAL), or at once on plans.updated: the plan bundle with schedules, options and resolved targets, stored on disk. A failed sync keeps the cached plans.
Scheduler every minute: which schedules fire in this minute (catching up at most 5 missed minutes), which checks of a plan are due given their minimum intervals, and which are still running from an earlier slot (not started twice).
Runner: up to PULSAR_MAX_PARALLEL_RUNS (4) runs at the same time, each over up to PULSAR_MAX_PARALLEL_TARGETS (4) targets in parallel. Checks with different minimum intervals run as separate jobs, so a long port scan does not hold back a ping.
Progress: finished parts are reported while the run goes on.
Upload: every finished run is written to /data/queue and uploaded in batches of up to 20 runs or 16 MiB. Polaris answers with the accepted run ids; only those are deleted. On failure the delay doubles up to 5 minutes.
Logs are shipped every 20 seconds; the traceroute to Polaris runs hourly.

Immediate jobs

With a websocket connection Polaris can push job.run: the satellite runs it at once, pushes the result directly and never stores it on disk. plans.updated triggers a sync, console.update grants or revokes the web console.

When Polaris is unreachable

Nothing is lost: plans keep running from the cached copy, results wait in /data/queue, logs wait in a buffer. When Polaris is back, the queue is uploaded. Runs that were in progress during a restart of the satellite are ended by Polaris as interrupted (see lost runs).

Checks Every check a satellite runs: what it does, on which targets, and every parameter with its default. Protocol and security How Polaris and Pulsar authenticate every message, and what each side refuses. Status page and web console What a satellite shows on port 8080, and how the detailed console is unlocked.