zonescope

zonescope

Properties1
tagszonescope, operator, ssot

2 min read

zonescope is the zero-runtime-dependency Bun and TypeScript topology truth engine for the loca.zone operator hub. It reads the host from independent angles, joins the observations into one Snapshot, and reports contradictions instead of treating any one inventory as authoritative.

Seven sources

  • nginx configuration from /etc/nginx/sites-enabled
  • listening TCP sockets from ss -ltnpH
  • system and user systemd service units
  • running Docker containers from sudo -n docker ps
  • the port_convention: registry in /home/loca/AGENTS.md
  • live TLS handshakes at the local HTTPS edge
  • live HTTPS responses at the local edge

One-command usage

From /home/loca/dev/wild:

./bin/zonescope

The default command prints a terminal report. JSON and a self-contained HTML dashboard are additional renderings of the same snapshot.

Guide

  • Architecture — module boundaries, the snapshot contract, probes, and bounded concurrency.
  • Modelling decisions — the five rules that keep cross-source verdicts truthful.
  • Finding codes — all 17 codes, fixed severities, and process exit status.
  • Dashboard — the public static surface and how to read it.
  • Operations — local scans, flags, tests, rule changes, and publication commands.
  • Scan records — dated evidence that remains historical rather than silently becoming current.
  • 2026-09-03 baseline scan — the initial host-wide inventory and findings.

Data flow

flowchart LR
  N["nginx site files"] --> J["judge"]
  S["listening sockets"] --> J
  U["systemd units"] --> J
  C["Docker containers"] --> J
  R["port registry"] --> J
  T["TLS probes"] --> J
  H["HTTPS probes"] --> J
  J --> X["terminal report"]
  J --> Y["snapshot JSON"]
  J --> Z["HTML dashboard"]

scan owns collection and probe orchestration, judge emits generic findings, and the three reporters consume the completed snapshot.

Graph View