Skip to content
WatchTower15Docs

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 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 agent on servers you choose, from inside your network 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,         │                         │
  │    service checks)                       │                         │
  │                                          ▼                         │
  │                              telemetry ─▶ database                 │
  │                              logs ──────▶ object store ─▶ log store │
  └──────────────────────────────────────────────────────────────────┘
                                             │
                                             ▼
  ┌──────────────────────────────────────────────────────────────────┐
  │  OUTSIDE-IN  (public internet)                                     │
  │                                                                    │
  │   Scheduler ─▶ queue ─▶ scanner workers ─▶ results ─▶ database     │
  │   (DNS, SSL, expiry, domain reachability)                          │
  └──────────────────────────────────────────────────────────────────┘
                                             │
                          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 15 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. The servers you choose as a service’s collectors also check that service from inside your network and send the results the same way.

Outside-in. A scheduler enqueues due checks every minute; a fleet of independent scanner workers resolves DNS, inspects certificates, checks domain expiry, and probes your domains’ reachability. Services are not checked from outside: your own servers check them. 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 least-privilege principle

Section titled “The least-privilege principle”

The single most important architectural decision in WatchTower15 is that the server agent runs with as little privilege as its job needs. The installer needs root once; after that the agent runs as an unprivileged service user, never as root, and cannot escalate or change the host, apart from asking for its own removal when its server is deleted. It holds exactly two read capabilities, CAP_SYS_PTRACE and CAP_DAC_READ_SEARCH, for per-process metrics and for reading log files. Anything that would need more (filesystem integrity monitoring, raw packet capture) is out of the default agent and, where offered, will be 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 and what each capability allows.

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”