Skip to content
WatchTower15 Docs

Core concepts & architecture

WatchTower15 is deliberately small in vocabulary and opinionated in design. Once you understand a handful of concepts and how data flows through the platform, every feature in these docs becomes predictable.

The object model

Section titled “The object model”

Everything you monitor is a resource. There are three kinds, and they map to the three ways the platform observes the world:

Resource type Observed by Examples
Server the agent running on the host (inside-out) a VM, a bare-metal box, a cloud instance
Domain the scanner fleet from the outside (outside-in) example.com, a public zone
Service the scanner fleet probing an endpoint an HTTP API, a TCP port, a UDP service

Resources are grouped and targeted with tags, which live in tag groups (the tag’s key/category). Alarms attach to resources and open incidents when their conditions are met. That’s the whole model.

How it works — data flow

Section titled “How it works — data flow”

WatchTower15 has two independent observation paths that converge in the same dashboard.

  ┌──────────────────────────────────────────────────────────────────┐
  │  INSIDE-OUT  (your hosts)                                          │
  │                                                                    │
  │   wt15-server-agent ──HMAC/HTTPS──▶  Ingest API                    │
  │   (telemetry, system info, logs)         │                         │
  │                                          ▼                         │
  │                              telemetry ─▶ database                 │
  │                              logs ──────▶ object store ─▶ log store │
  └──────────────────────────────────────────────────────────────────┘
                                             │
                                             ▼
  ┌──────────────────────────────────────────────────────────────────┐
  │  OUTSIDE-IN  (public internet)                                     │
  │                                                                    │
  │   Scheduler ─▶ queue ─▶ scanner workers ─▶ results ─▶ database     │
  │   (DNS, SSL, expiry, reachability, response)                       │
  └──────────────────────────────────────────────────────────────────┘
                                             │
                          scan/telemetry ────▶ Alarm evaluation
                                             │        │
                                             ▼        ▼
                                        Dashboard   Incidents ─▶ Channels
                                                    (email/Slack/Teams/webhook)

Inside-out. The server agent reads standard /proc and /sys paths, pushes telemetry every 60 seconds and a fuller system-information snapshot every 300 seconds, and (optionally) ships logs. It authenticates every request with an HMAC signature derived from a per-agent secret — there are no inbound ports on your host.

Outside-in. A scheduler enqueues due checks every minute; a fleet of independent scanner workers resolves DNS, inspects certificates, checks domain expiry, and probes reachability and response. Heavy scan payloads are archived to object storage; only the extracted fields and a pointer live in the database.

Convergence. Both paths feed alarm evaluation, which opens or resolves incidents and dispatches notifications. The dashboard reads from the same store, so servers, domains and services sit side by side.

Checks, scans and outcomes

Section titled “Checks, scans and outcomes”

External checks record two independent axes, which keeps transient errors from becoming false alarms:

  • Status — the execution health of the check itself: queued, running, completed, failed, timeout.
  • Outcome — the finding: data_found, no_data, target_not_found, blocked, lookup_unavailable.

Outcomes of blocked (e.g. a firewall refused the probe) and lookup_unavailable (e.g. a resolver timed out) are deliberately excluded from change detection and alarm evaluation — a flaky network hiccup never pages you.

The zero-privilege principle

Section titled “The zero-privilege principle”

The single most important architectural decision in WatchTower15 is that the server agent needs no privilege. It installs as an unprivileged service user, holds zero Linux capabilities, and reads only world-readable kernel interfaces. Anything that would require elevated privilege (filesystem integrity monitoring, raw packet capture) is explicitly out of the default agent and, where offered, delivered as a separate, narrowly-scoped helper — never by widening the agent.

This is why WatchTower15 can be approved for hosts where a root-level agent would never pass review. See the privilege model for the exact systemd hardening.

Data residency

Section titled “Data residency”

Your monitoring data — telemetry, scan results, archived logs — is stored in the region your account is provisioned in. Region selection is part of provisioning, so data stays where you expect it rather than being scattered across a global mesh you don’t control.

Multi-tenancy & isolation

Section titled “Multi-tenancy & isolation”

Every resource, tag, log line and audit record is scoped to your organisation. Access within an organisation is governed by roles & permissions; cross-organisation access is not possible. Log queries are always constrained to your organisation before they ever reach the log store.

Where to next

Section titled “Where to next”