Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(agent): V2 capability pack — survey/doctor/fleet sweep+repair (plan 28)

Juan Denis44892d3314e1
diff --git a/backend/app/api/survey.py b/backend/app/api/survey.py
new file mode 100644
index 00000000..bdfe936f
--- /dev/null
+++ b/backend/app/api/survey.py
@@ -0,0 +1,165 @@
+"""Server survey API — read-only "flights" over a paired agent (plan 27).
+
+Mounted at /api/v1/servers (see app/__init__.py). All routes are admin-only: a
+survey enumerates what's running on a host, and the catalog index is the honest
+"here is what we look at" surface shown verbatim in the UI.
+"""
+from flask import Blueprint, jsonify, request
+
+from app.middleware.rbac import admin_required, get_current_user
+from app.models.server import Server
+from app.services import survey_service
+
+survey_bp = Blueprint('survey', __name__)
+
+
+@survey_bp.route('/survey/catalog', methods=['GET'])
+@admin_required
+def get_catalog():
+ """The operator-facing probe index — exactly what the survey reads."""
+ try:
+ return jsonify(survey_service.probe_index()), 200
+ except survey_service.SurveyError as exc:
+ return jsonify({'error': f'Invalid probe catalog: {exc}'}), 500
+
+
+@survey_bp.route('/<server_id>/survey', methods=['POST'])
+@admin_required
+def run_survey(server_id):
+ """Fly a read-only survey against the server's agent and store the map."""
+ server = Server.query.get(server_id)
+ if server is None:
+ return jsonify({'error': 'Server not found'}), 404
+
+ user = get_current_user()
+ survey, error = survey_service.run_survey(server_id, user_id=getattr(user, 'id', None))
+ if error:
+ return jsonify({'error': error['error'], 'code': error['code']}), error['status']
+ return jsonify(survey), 201
+
+
+@survey_bp.route('/<server_id>/management-mode', methods=['POST'])
+@admin_required
+def set_management_mode(server_id):
+ """Switch a server between 'managed' and 'observed' (plan 27, Decision 1/4).
+
+ An operator confirms mode changes; detection only ever SUGGESTS. Existing
+ managed boxes are never auto-downgraded — this is the explicit, audited flip.
+ """
+ from app import db
+ from app.services.audit_service import AuditService
+
+ server = Server.query.get(server_id)
+ if server is None:
+ return jsonify({'error': 'Server not found'}), 404
+
+ data = request.get_json(silent=True) or {}
+ mode = (data.get('mode') or '').strip().lower()
+ if mode not in Server.MANAGEMENT_MODES:
+ return jsonify({'error': f'mode must be one of {list(Server.MANAGEMENT_MODES)}'}), 400
+
+ previous = server.management_mode or 'managed'
+ server.management_mode = mode
+
+ # Optional break-glass toggle (plan 31 #10, Decision 6): permit agent:update
+ # while observing. Only meaningful for observed boxes but always storable.
+ details = {'from': previous, 'to': mode}
+ if 'allow_agent_update_observed' in data:
+ override = bool(data.get('allow_agent_update_observed'))
+ server.allow_agent_update_observed = override
+ details['allow_agent_update_observed'] = override
+ db.session.commit()
+
+ user = get_current_user()
+ try:
+ AuditService.log(
+ action='server.management_mode',
+ user_id=getattr(user, 'id', None),
+ target_type='server',
+ target_id=server_id,
+ details=details,
+ )
+ except Exception: # audit is best-effort, never blocks the flip
+ pass
+
+ result = server.to_dict()
+ from app.services.agent_registry import agent_registry
+ result['observed_blocked_count'] = agent_registry.observed_blocked_count(server_id)
+ return jsonify(result), 200
+
+
+@survey_bp.route('/<server_id>/observed-status', methods=['GET'])
+@admin_required
+def observed_status(server_id):
+ """Observe-mode status for a server (plan 31 #10/#11).
+
+ Returns the current mode, the agent:update break-glass flag, and how many
+ commands the Observe guard has blocked — the "blocked N commands" counter.
+ """
+ from app.services.agent_registry import agent_registry
+ server = Server.query.get(server_id)
+ if server is None:
+ return jsonify({'error': 'Server not found'}), 404
+ return jsonify({
+ 'management_mode': server.management_mode or 'managed',
+ 'allow_agent_update_observed': bool(server.allow_agent_update_observed),
+ 'observed_blocked_count': agent_registry.observed_blocked_count(server_id),
+ }), 200
+
+
+@survey_bp.route('/<server_id>/surveys', methods=['GET'])
+@admin_required
+def list_surveys(server_id):
+ """List survey snapshots for a server (newest first, without the map blob)."""
+ server = Server.query.get(server_id)
+ if server is None:
+ return jsonify({'error': 'Server not found'}), 404
+ surveys = survey_service.list_surveys(server_id)
+ return jsonify({'surveys': [s.to_dict(include_map=False) for s in surveys]}), 200
+
+
+@survey_bp.route('/<server_id>/surveys/<int:survey_id>', methods=['GET'])
+@admin_required
+def get_survey(server_id, survey_id):
+ """Fetch one survey snapshot including its full Server Map."""
+ from app.models.server_survey import ServerSurvey
+ survey = ServerSurvey.query.filter_by(id=survey_id, server_id=server_id).first()
+ if survey is None:
+ return jsonify({'error': 'Survey not found'}), 404
+ return jsonify(survey.to_dict()), 200
+
+
+@survey_bp.route('/<server_id>/surveys/diff', methods=['GET'])
+@admin_required
+def diff_surveys(server_id):
+ """Diff two survey snapshots (``?from=<id>&to=<id>``).
+
+ Defaults ``to`` to the latest snapshot and ``from`` to the one before it, so
+ a bare call answers "what changed since the last flight".
+ """
+ from app.models.server_survey import ServerSurvey
+
+ surveys = survey_service.list_surveys(server_id)
+ if len(surveys) < 2 and not (request.args.get('from') and request.args.get('to')):
+ return jsonify({'error': 'Need at least two surveys to diff'}), 400
+
+ def _load(arg, default):
+ raw = request.args.get(arg)
+ if raw is None:
+ return default
+ s = ServerSurvey.query.filter_by(id=int(raw), server_id=server_id).first()
+ if s is None:
+ return None
+ return s
+
+ new_survey = _load('to', surveys[0] if surveys else None)
+ old_survey = _load('from', surveys[1] if len(surveys) > 1 else None)
+ if new_survey is None or old_survey is None:
+ return jsonify({'error': 'Survey not found'}), 404
+
+ diff = survey_service.diff_maps(old_survey.get_map(), new_survey.get_map())
+ return jsonify({
+ 'from': old_survey.to_dict(include_map=False),
+ 'to': new_survey.to_dict(include_map=False),
+ 'diff': diff,
+ }), 200
diff --git a/backend/app/data/survey_probe_catalog.yaml b/backend/app/data/survey_probe_catalog.yaml
new file mode 100644
index 00000000..9eea8946
--- /dev/null
+++ b/backend/app/data/survey_probe_catalog.yaml
@@ -0,0 +1,120 @@
+# ServerKit survey probe catalog (plan 27, Decision 2).
+#
+# A VERSIONED, declarative list of every location/service the read-only survey
+# ("flight") looks at on a paired Linux box, and how to read it. The panel ships
+# this file, sends it to the agent per survey run, and shows the index verbatim
+# to the operator so the honest answer to "what will you look at on my server?"
+# is this file.
+#
+# The agent executes each probe with a FIXED allowlist of read-only primitives
+# only (see docs/AGENT_SURVEY_SPEC.md): file-exists, glob, unit-status,
+# socket-list, process-list, and parse-light line extraction. Catalog entries
+# can only COMBINE those primitives — they can never name a shell command. A
+# compromised panel can at worst enumerate paths; it can never execute. Env and
+# credential files are listed by PATH ONLY and never read.
+#
+# Bump `version` whenever the probe set changes; snapshots record the version
+# they were taken with so a diff can note "catalog changed between flights".
+version: 1
+
+probes:
+ - id: nginx
+ kind: service+config
+ title: Nginx web server
+ reads: Service status, listening ports, and enabled vhost files (server_name / root / proxy_pass lines only).
+ detect:
+ ports: [80, 443]
+ units: [nginx]
+ bins: [nginx]
+ map:
+ # server_name -> document root / upstream. Parse-light: only the
+ # server_name, root, and proxy_pass directives are extracted.
+ vhosts: [/etc/nginx/sites-enabled/*, /etc/nginx/conf.d/*.conf]
+
+ - id: apache
+ kind: service+config
+ title: Apache web server
+ reads: Service status and enabled vhost files (ServerName / DocumentRoot / ProxyPass lines only).
+ detect:
+ units: [apache2, httpd]
+ bins: [apache2, httpd]
+ map:
+ vhosts: [/etc/apache2/sites-enabled/*, /etc/httpd/conf.d/*.conf]
+
+ - id: php-fpm
+ kind: service+config
+ title: PHP-FPM runtime
+ reads: Detected PHP-FPM pools and the version directory they live under.
+ detect:
+ units: [php*-fpm, php-fpm]
+ bins: [php-fpm]
+ map:
+ pools: [/etc/php/*/fpm/pool.d/*.conf, /etc/php-fpm.d/*.conf]
+
+ - id: foreign-panel
+ kind: marker
+ title: Other control panel
+ reads: Presence of well-known control-panel marker directories (existence check only — contents are never read).
+ detect:
+ # Marker directories kept as DATA, never as names in code paths
+ # (Decision 8). Detection SUGGESTS Observed mode; it never flips it.
+ paths:
+ - /usr/local/cpanel
+ - /usr/local/directadmin
+ - /usr/local/hestia
+ - /usr/local/vesta
+ - /usr/local/cwp
+ - /usr/local/psa # Plesk
+ - /usr/local/ispconfig
+ - /var/webmin
+
+ - id: docker
+ kind: service
+ title: Docker
+ reads: Docker service status, running containers, their published ports, and compose project labels.
+ detect:
+ units: [docker]
+ bins: [docker]
+ ports: [2375, 2376]
+
+ - id: databases
+ kind: service
+ title: Database engines
+ reads: Database service status and listening sockets (MySQL / MariaDB / PostgreSQL / MongoDB). No database contents are read.
+ detect:
+ units: [mysql, mariadb, postgresql, mongod]
+ bins: [mysqld, mariadbd, postgres, mongod]
+ ports: [3306, 5432, 27017]
+
+ - id: crontabs
+ kind: inventory
+ title: Cron jobs
+ reads: Per-user crontab inventory (the schedule lines). Read-only.
+ detect:
+ paths: [/var/spool/cron, /var/spool/cron/crontabs, /etc/cron.d]
+ map:
+ crontabs: [/var/spool/cron/*, /var/spool/cron/crontabs/*, /etc/cron.d/*]
+
+ - id: certs
+ kind: inventory
+ title: TLS certificates
+ reads: Let's Encrypt live certificate directories (domain names and expiry only — private keys are never read).
+ detect:
+ paths: [/etc/letsencrypt/live]
+ map:
+ certs: [/etc/letsencrypt/live/*]
+
+ - id: mail
+ kind: service
+ title: Mail server
+ reads: Mail service status and SMTP/submission port bindings (25 / 465 / 587). No mailbox contents are read.
+ detect:
+ units: [postfix, dovecot, exim4, opendkim]
+ bins: [postfix, dovecot, exim]
+ ports: [25, 465, 587]
+
+ - id: listeners
+ kind: inventory
+ title: Listening ports
+ reads: Catch-all — every listening TCP/UDP socket mapped to the owning process name (not its command line).
+ detect: {}
diff --git a/backend/app/models/server_survey.py b/backend/app/models/server_survey.py
new file mode 100644
index 00000000..a96f754e
--- /dev/null
+++ b/backend/app/models/server_survey.py
@@ -0,0 +1,57 @@
+import json
+from datetime import datetime
+
+from app import db
+
+
+class ServerSurvey(db.Model):
+ """One read-only survey snapshot ("flight") of a paired server (plan 27,
+ Decision 3: snapshots, not live state).
+
+ The agent flies the probe catalog and returns a structured Server Map; the
+ panel normalizes it and stores it here as a versioned, immutable snapshot.
+ Re-flying is manual (or an optional weekly schedule) and appends a new row,
+ so any two flights of the same server can be diffed ("what changed since
+ last flight").
+
+ ``catalog_version`` records which probe-catalog version produced the map, so
+ a diff can flag that the catalog itself changed between two flights.
+ ``map_json`` holds the normalized Server Map (services / sites / databases /
+ certs / cron / listeners / foreign_panels).
+ """
+
+ __tablename__ = 'server_surveys'
+
+ id = db.Column(db.Integer, primary_key=True)
+ server_id = db.Column(db.String(36), db.ForeignKey('servers.id'), nullable=False, index=True)
+ catalog_version = db.Column(db.Integer, nullable=False, default=1)
+ taken_at = db.Column(db.DateTime, nullable=False, default=datetime.utcnow, index=True)
+
+ # Normalized Server Map, stored as a JSON string for portability across the
+ # SQLite/Postgres split (mirrors how other snapshot blobs are persisted).
+ map_json = db.Column(db.Text, nullable=True)
+
+ def get_map(self):
+ if not self.map_json:
+ return {}
+ try:
+ return json.loads(self.map_json)
+ except (json.JSONDecodeError, TypeError):
+ return {}
+
+ def set_map(self, value):
+ self.map_json = json.dumps(value) if value else None
+
+ def to_dict(self, include_map=True):
+ data = {
+ 'id': self.id,
+ 'server_id': self.server_id,
+ 'catalog_version': self.catalog_version,
+ 'taken_at': self.taken_at.isoformat() + 'Z' if self.taken_at else None,
+ }
+ if include_map:
+ data['map'] = self.get_map()
+ return data
+
+ def __repr__(self):
+ return f'<ServerSurvey server={self.server_id} v{self.catalog_version} at={self.taken_at}>'
diff --git a/backend/app/services/fleet_sweep.py b/backend/app/services/fleet_sweep.py
new file mode 100644
index 00000000..dc078dc5
--- /dev/null
+++ b/backend/app/services/fleet_sweep.py
@@ -0,0 +1,131 @@
+"""Bounded fan-out over connected agents — the one primitive every fleet
+sweep reuses (Fleet Parity Sweep, plan 26, Decision 4).
+
+A "sweep" runs the same per-server probe across every targeted server, with a
+bounded worker pool, a per-agent timeout, and a hard wall-clock budget so a
+single slow (or hung) agent can never stall the panel. A server that doesn't
+finish inside the budget yields a ``timeout`` result row — a partial result,
+never a blocked request thread.
+
+Invariants this enforces so callers don't have to:
+
+* **Runs off the request thread only.** The gateway registry is single-worker
+ and in-memory (CLAUDE.md / ARCHITECTURE / SECURITY), so fan-out must happen
+ inside a job handler, never inline in a request. This helper spins its own
+ bounded pool; call it from a job.
+* **App context per worker.** Worker threads don't inherit the Flask app
+ context, so each ``action_composer`` call is wrapped in one — composers may
+ freely query the DB / registry.
+* **Statuses are uniform.** Every result dict carries a ``status`` of
+ ``ok`` / ``failed`` / ``offline`` / ``unsupported`` / ``timeout`` so the
+ aggregating layer (fleet doctor, KPIs) treats every sweep the same.
+
+See ``docs/FLEET_CONTRACT.md`` for the surrounding contract.
+"""
+import concurrent.futures
+import logging
+import time
+
+from flask import current_app
+
+logger = logging.getLogger(__name__)
+
+# Conservative defaults — the single-worker constraint means a sweep competes
+# with live agent traffic, so keep the pool small and the budget finite.
+DEFAULT_POOL = 4
+DEFAULT_PER_AGENT_TIMEOUT = 20.0
+DEFAULT_BUDGET = 90.0
+
+# The uniform status vocabulary a composer may return (Decision 2). Anything a
+# composer returns without a 'status' key defaults to 'ok'; exceptions and
+# budget overruns are mapped here by the helper itself.
+SWEEP_STATUSES = ('ok', 'failed', 'offline', 'unsupported', 'timeout')
+
+
+def _run_one(app, composer, server_id, per_agent_timeout):
+ """Invoke ``composer(server_id, per_agent_timeout)`` inside an app context,
+ normalising its return value / exceptions into a status-bearing dict."""
+ try:
+ with app.app_context():
+ res = composer(server_id, per_agent_timeout)
+ except Exception as exc: # noqa: BLE001 — one bad agent must not sink the sweep
+ logger.warning("fleet_sweep composer failed for %s: %s", server_id, exc)
+ return {'status': 'failed', 'error': str(exc)}
+ if not isinstance(res, dict):
+ return {'status': 'failed', 'error': 'composer returned a non-dict result'}
+ res.setdefault('status', 'ok')
+ return res
+
+
+def fleet_sweep(action_composer, servers, pool=DEFAULT_POOL,
+ per_agent_timeout=DEFAULT_PER_AGENT_TIMEOUT, budget=DEFAULT_BUDGET):
+ """Run ``action_composer`` across ``servers`` with a bounded pool + budget.
+
+ Args:
+ action_composer: ``callable(server_id: str, per_agent_timeout: float)``
+ returning a dict. Runs on a worker thread inside an app context; may
+ call ``agent_registry.send_command`` and query the DB. Should set a
+ ``status`` from :data:`SWEEP_STATUSES` (defaults to ``ok``). Should
+ use ``per_agent_timeout`` as the ceiling for any ``send_command`` it
+ issues so the per-agent bound is honoured end-to-end.
+ servers: iterable of server-id strings, or objects exposing ``.id``.
+ pool: max agents probed concurrently (kept small — single-worker panel).
+ per_agent_timeout: ceiling passed to each composer for its remote calls.
+ budget: hard wall-clock ceiling for the whole sweep, in seconds. Agents
+ that haven't produced a result by then get a ``timeout`` row.
+
+ Returns:
+ ``{server_id: result_dict}`` — one row per input server, always. Rows
+ never raise: a composer exception → ``failed``; budget overrun →
+ ``timeout``.
+ """
+ ids = []
+ for s in servers:
+ ids.append(s.id if hasattr(s, 'id') else s)
+ # De-dupe while preserving order (a caller may pass overlapping lists).
+ seen = set()
+ ids = [sid for sid in ids if not (sid in seen or seen.add(sid))]
+
+ results = {}
+ if not ids:
+ return results
+
+ app = current_app._get_current_object()
+ # NOT used as a context manager on purpose: ThreadPoolExecutor.__exit__
+ # calls shutdown(wait=True), which would block the caller until a hung
+ # composer finishes — exactly the stall the budget exists to prevent. We
+ # shut down with wait=False so a slow agent's worker is abandoned (it holds
+ # only a bounded send_command, which times out on its own) and the panel
+ # returns immediately with a partial result set.
+ executor = concurrent.futures.ThreadPoolExecutor(max_workers=max(1, int(pool)))
+ try:
+ futures = {
+ executor.submit(_run_one, app, action_composer, sid, per_agent_timeout): sid
+ for sid in ids
+ }
+ try:
+ for future in concurrent.futures.as_completed(futures, timeout=budget):
+ sid = futures[future]
+ try:
+ results[sid] = future.result()
+ except Exception as exc: # noqa: BLE001 — belt & suspenders
+ logger.warning("fleet_sweep future errored for %s: %s", sid, exc)
+ results[sid] = {'status': 'failed', 'error': str(exc)}
+ except concurrent.futures.TimeoutError:
+ # Wall-clock budget hit — everything still pending becomes a partial
+ # 'timeout' row so the panel gets a bounded, complete result set.
+ logger.warning(
+ "fleet_sweep hit its %.0fs wall-clock budget with %d/%d agents done",
+ budget, len(results), len(ids),
+ )
+ for future, sid in futures.items():
+ if sid not in results:
+ future.cancel()
+ results[sid] = {
+ 'status': 'timeout',
+ 'error': 'agent did not respond within the sweep budget',
+ }
+ finally:
+ # Reap finished threads; don't wait on the abandoned slow one.
+ executor.shutdown(wait=False, cancel_futures=True)
+ return results
diff --git a/backend/tests/test_doctor_dns.py b/backend/tests/test_doctor_dns.py
new file mode 100644
index 00000000..2a9a55aa
--- /dev/null
+++ b/backend/tests/test_doctor_dns.py
@@ -0,0 +1,306 @@
+"""Tests for the doctor's site-DNS sweep: detection of domains that no longer
+resolve, one-click repair via a connected provider, and the newly-broken
+admin notification (doctor_service._dns_checks / _repair_dns / run_doctor_job)."""
+import json
+import socket
+
+import pytest
+
+from app.services import doctor_service
+from app.services.doctor_service import (
+ DNS_CHECK_MAX_DOMAINS,
+ DoctorService,
+ LAST_REPORT_KEY,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures / helpers
+# --------------------------------------------------------------------------- #
+
+def site(app):
+ """An Application to hang test Domain rows off."""
+ from werkzeug.security import generate_password_hash
+ from app import db
+ from app.models import User
+ from app.models.application import Application
+
+ user = User(email='[email protected]', username='dnsuser',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.flush()
+ row = Application(name='dnssite', app_type='static', user_id=user.id)
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+
+def add_domain(site, name):
+ from app import db
+ from app.models.domain import Domain
+ db.session.add(Domain(name=name, application_id=site.id))
+ db.session.commit()
+
+
+def add_provider():
+ from app import db
+ from app.models.email import DNSProviderConfig
+ db.session.add(DNSProviderConfig(name='CF', provider='cloudflare', api_key='x'))
+ db.session.commit()
+
+
+def fake_resolver(table):
+ """A _resolve_host_ips stand-in: ``table[host]`` is a list of IPs, or an
+ exception instance to raise."""
+ def resolve(host):
+ result = table[host]
+ if isinstance(result, Exception):
+ raise result
+ return result
+ return resolve
+
+
+def set_server_ip(monkeypatch, ip):
+ from app.services.site_domain_service import SiteDomainService
+ monkeypatch.setattr(SiteDomainService, 'server_ip', classmethod(lambda cls: ip))
+
+
+def checks_by_key(checks):
+ return {c['key']: c for c in checks}
+
+
+# --------------------------------------------------------------------------- #
+# Detection
+# --------------------------------------------------------------------------- #
+
+def test_no_domains_is_a_single_ok_check(app):
+ checks = DoctorService._dns_checks()
+ assert len(checks) == 1
+ assert checks[0]['key'] == 'dns.resolve'
+ assert checks[0]['status'] == 'ok'
+
+
+def test_dev_and_ip_hostnames_are_skipped(app, site, monkeypatch):
+ for name in ('mysite.lvh.me', 'localhost', '10.0.0.5', 'noDotHost',
+ 'box.internal', 'demo.test'):
+ add_domain(site, name)
+ set_server_ip(monkeypatch, None)
+ checks = DoctorService._dns_checks()
+ assert len(checks) == 1
+ assert checks[0]['status'] == 'ok'
+ assert 'No public site domains' in checks[0]['detail']
+
+
+def test_unresolved_with_provider_and_ip_is_repairable(app, site, monkeypatch):
+ add_domain(site, 'gone.example.com')
+ add_provider()
+ set_server_ip(monkeypatch, '203.0.113.7')
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips',
+ fake_resolver({'gone.example.com': socket.gaierror(-2)}))
+
+ checks = checks_by_key(DoctorService._dns_checks())
+ c = checks['dns.resolve.gone.example.com']
+ assert c['status'] == 'fail'
+ assert c['repairable'] is True
+ assert c['repair_ref'] == {'kind': 'dns', 'host': 'gone.example.com'}
+ assert '203.0.113.7' in c['detail']
+
+
+def test_unresolved_without_provider_gives_manual_instructions(app, site, monkeypatch):
+ add_domain(site, 'gone.example.com')
+ set_server_ip(monkeypatch, '203.0.113.7')
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips',
+ fake_resolver({'gone.example.com': socket.gaierror(-2)}))
+
+ c = checks_by_key(DoctorService._dns_checks())['dns.resolve.gone.example.com']
+ assert c['status'] == 'fail'
+ assert c['repairable'] is False
+ assert 'connect a DNS provider' in c['detail']
+ assert 'gone.example.com → 203.0.113.7' in c['detail']
+
+
+def test_unresolved_without_server_ip_points_at_settings(app, site, monkeypatch):
+ add_domain(site, 'gone.example.com')
+ add_provider()
+ set_server_ip(monkeypatch, None)
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips',
+ fake_resolver({'gone.example.com': socket.gaierror(-2)}))
+
+ c = checks_by_key(DoctorService._dns_checks())['dns.resolve.gone.example.com']
+ assert c['status'] == 'fail'
+ assert c['repairable'] is False
+ assert 'server public IP' in c['detail']
+
+
+def test_resolving_domains_ok_or_warn_by_target(app, site, monkeypatch):
+ add_domain(site, 'here.example.com')
+ add_domain(site, 'elsewhere.example.com')
+ set_server_ip(monkeypatch, '203.0.113.7')
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips', fake_resolver({
+ 'here.example.com': ['203.0.113.7'],
+ 'elsewhere.example.com': ['198.51.100.1'],
+ }))
+
+ checks = checks_by_key(DoctorService._dns_checks())
+ assert checks['dns.resolve.here.example.com']['status'] == 'ok'
+ other = checks['dns.resolve.elsewhere.example.com']
+ assert other['status'] == 'warn'
+ assert '198.51.100.1' in other['detail']
+
+
+def test_domain_cap_is_reported(app, site, monkeypatch):
+ for i in range(DNS_CHECK_MAX_DOMAINS + 2):
+ add_domain(site, f'site{i}.example.com')
+ set_server_ip(monkeypatch, None)
+ monkeypatch.setattr(
+ doctor_service, '_resolve_host_ips', lambda host: ['198.51.100.1'])
+
+ checks = DoctorService._dns_checks()
+ assert len(checks) == DNS_CHECK_MAX_DOMAINS + 1
+ cap = [c for c in checks if c['key'] == 'dns.resolve'][0]
+ assert cap['status'] == 'warn'
+ assert '2 more domain(s)' in cap['detail']
+
+
+# --------------------------------------------------------------------------- #
+# Repair
+# --------------------------------------------------------------------------- #
+
+def test_repair_dns_creates_record_via_provider(app, site, monkeypatch):
+ from app.services.dns_provider_service import DNSProviderService
+
+ add_domain(site, 'gone.example.com')
+ set_server_ip(monkeypatch, '203.0.113.7')
+ calls = []
+ monkeypatch.setattr(
+ DNSProviderService, 'ensure_a_record',
+ classmethod(lambda cls, d, ip: calls.append((d, ip)) or
+ {'created': True, 'provider': 'CF',
+ 'record': {'type': 'A', 'name': d, 'value': ip}}))
+
+ results = DoctorService.repair([{'kind': 'dns', 'host': 'gone.example.com'}])
+
+ assert calls == [('gone.example.com', '203.0.113.7')]
+ assert results[0]['success'] is True
+ assert results[0]['record']['name'] == 'gone.example.com'
+
+
+def test_repair_dns_rejects_unmanaged_hostname(app, site, monkeypatch):
+ from app.services.dns_provider_service import DNSProviderService
+
+ add_domain(site, 'gone.example.com')
+ monkeypatch.setattr(
+ DNSProviderService, 'ensure_a_record',
+ classmethod(lambda cls, d, ip: pytest.fail('must not reach the provider')))
+
+ result = DoctorService._repair_dns('attacker.example.net')
+ assert result['success'] is False
+ assert 'Not a managed site domain' in result['error']
+
+
+def test_repair_dns_surfaces_provider_degradation(app, site, monkeypatch):
+ from app.services.dns_provider_service import DNSProviderService
+
+ add_domain(site, 'gone.example.com')
+ set_server_ip(monkeypatch, '203.0.113.7')
+ monkeypatch.setattr(
+ DNSProviderService, 'ensure_a_record',
+ classmethod(lambda cls, d, ip: {
+ 'created': False, 'reason': 'no_provider',
+ 'message': f'No connected DNS provider manages {d} — add this record manually.'}))
+
+ result = DoctorService._repair_dns('gone.example.com')
+ assert result['success'] is False
+ assert 'add this record manually' in result['error']
+
+
+# --------------------------------------------------------------------------- #
+# Notification (job)
+# --------------------------------------------------------------------------- #
+
+class _JobStub:
+ def get_payload(self):
+ return {}
+
+
+def _stub_other_checks(monkeypatch):
+ monkeypatch.setattr(DoctorService, '_drift_checks', classmethod(lambda cls: []))
+ monkeypatch.setattr(DoctorService, '_service_checks', classmethod(lambda cls: []))
+
+
+def test_doctor_job_notifies_only_newly_broken_domains(app, site, monkeypatch):
+ import app.plugins_sdk as sdk
+ from app.services.settings_service import SettingsService
+
+ add_domain(site, 'old-broken.example.com')
+ add_domain(site, 'new-broken.example.com')
+ add_provider()
+ set_server_ip(monkeypatch, '203.0.113.7')
+ _stub_other_checks(monkeypatch)
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips', fake_resolver({
+ 'old-broken.example.com': socket.gaierror(-2),
+ 'new-broken.example.com': socket.gaierror(-2),
+ }))
+
+ # Previous report already knew about old-broken.
+ SettingsService.set(LAST_REPORT_KEY, json.dumps({'checks': [
+ {'key': 'dns.resolve.old-broken.example.com', 'status': 'fail'},
+ ]}))
+
+ sent = []
+ monkeypatch.setattr(sdk.notify, 'send',
+ lambda event, to, data=None, **kw: sent.append((event, to, data)))
+
+ summary = DoctorService.run_doctor_job(_JobStub())
+
+ assert summary['dns_new_failures'] == ['new-broken.example.com']
+ assert len(sent) == 1
+ event, to, data = sent[0]
+ assert event == 'dns.unresolved'
+ assert to == 'admins'
+ assert data['count'] == 1
+ assert data['domains'] == ['new-broken.example.com']
+
+ # Second sweep: nothing new — no re-alert.
+ sent.clear()
+ summary = DoctorService.run_doctor_job(_JobStub())
+ assert summary['dns_new_failures'] == []
+ assert sent == []
+
+
+def test_doctor_job_no_notification_when_all_resolve(app, site, monkeypatch):
+ import app.plugins_sdk as sdk
+
+ add_domain(site, 'fine.example.com')
+ set_server_ip(monkeypatch, '203.0.113.7')
+ _stub_other_checks(monkeypatch)
+ monkeypatch.setattr(doctor_service, '_resolve_host_ips',
+ fake_resolver({'fine.example.com': ['203.0.113.7']}))
+
+ sent = []
+ monkeypatch.setattr(sdk.notify, 'send', lambda *a, **kw: sent.append(a))
+
+ DoctorService.run_doctor_job(_JobStub())
+ assert sent == []
+
+
+def test_dns_event_in_notification_catalog():
+ from app.notifications import catalog
+ entry = catalog.get('dns.unresolved')
+ assert entry is not None
+ assert entry['severity'] == 'warning'
+ assert entry['category'] == 'system'
+
+
+def test_doctor_schedule_is_seeded(app):
+ from app.jobs.builtin_handlers import seed_builtin_schedules
+ from app.jobs.models import ScheduledJob
+ from app.services.doctor_service import DOCTOR_JOB_KIND, DOCTOR_SCHEDULE_NAME
+
+ seed_builtin_schedules()
+ row = ScheduledJob.query.filter_by(name=DOCTOR_SCHEDULE_NAME).first()
+ assert row is not None
+ assert row.kind == DOCTOR_JOB_KIND
+ assert row.interval_seconds == 86400
diff --git a/backend/tests/test_survey_service.py b/backend/tests/test_survey_service.py
new file mode 100644
index 00000000..a365841c
--- /dev/null
+++ b/backend/tests/test_survey_service.py
@@ -0,0 +1,128 @@
+"""Survey normalization, snapshot storage + diff (plan 27 Phase 2, #5/#6)."""
+from app.services import survey_service
+
+
+# A representative raw agent survey payload (see docs/AGENT_SURVEY_SPEC.md).
+FIXTURE_PAYLOAD = {
+ 'catalog_version': 1,
+ 'probes': {
+ 'nginx': {
+ 'detected': True,
+ 'service': {'active': True, 'ports': [80, 443]},
+ 'vhosts': [
+ {'server_name': 'example.com', 'root': '/var/www/example', 'upstream': None},
+ {'server_name': 'api.example.com', 'root': None, 'upstream': 'http://127.0.0.1:8001'},
+ ],
+ },
+ 'apache': {'detected': False},
+ 'php-fpm': {'detected': True, 'service': {'active': True}},
+ 'foreign-panel': {'detected': True, 'markers': ['/usr/local/cpanel']},
+ 'databases': {'detected': True, 'engines': [{'name': 'mysql', 'active': True, 'port': 3306}]},
+ 'crontabs': {'crontabs': [{'user': 'root', 'lines': ['0 3 * * * /usr/bin/backup']}]},
+ 'certs': {'certs': [{'domain': 'example.com', 'expires_at': '2026-10-01T00:00:00Z'}]},
+ 'listeners': {'listeners': [{'port': 80, 'proto': 'tcp', 'process': 'nginx'}]},
+ },
+}
+
+
+def test_normalize_produces_canonical_shape():
+ m = survey_service.normalize_map(FIXTURE_PAYLOAD)
+
+ assert m['catalog_version'] == 1
+ # Services: nginx, php-fpm, databases were detected; apache was not.
+ svc_ids = {s['id'] for s in m['services']}
+ assert svc_ids == {'nginx', 'php-fpm', 'databases'}
+
+ # Sites come from nginx vhosts, tagged managed_by other-panel (foreign present).
+ domains = {s['domain'] for s in m['sites']}
+ assert domains == {'example.com', 'api.example.com'}
+ api_site = next(s for s in m['sites'] if s['domain'] == 'api.example.com')
+ assert api_site['upstream'] == 'http://127.0.0.1:8001'
+ assert api_site['managed_by'] == 'other-panel'
+
+ assert m['foreign_panel_detected'] is True
+ assert m['foreign_panels'] == [{'marker': '/usr/local/cpanel'}]
+ assert m['databases'][0]['engine'] == 'mysql'
+ assert m['certs'][0]['domain'] == 'example.com'
+ assert m['cron'][0]['user'] == 'root'
+ assert m['listeners'][0]['port'] == 80
+ assert 'nginx' in m['probes_run']
+
+
+def test_normalize_is_defensive_on_empty_and_partial():
+ assert survey_service.normalize_map({})['services'] == []
+ assert survey_service.normalize_map(None)['sites'] == []
+ partial = survey_service.normalize_map({'probes': {'nginx': {'detected': True}}})
+ assert partial['services'][0]['id'] == 'nginx'
+ assert partial['sites'] == []
+ assert partial['foreign_panel_detected'] is False
+
+
+def test_normalize_managed_by_is_stack_when_no_foreign_panel():
+ payload = {
+ 'probes': {
+ 'nginx': {'detected': True, 'vhosts': [{'server_name': 'a.com', 'root': '/srv/a'}]},
+ }
+ }
+ m = survey_service.normalize_map(payload)
+ assert m['sites'][0]['managed_by'] == 'nginx'
+
+
+def test_diff_maps_detects_added_removed_changed():
+ old = survey_service.normalize_map(FIXTURE_PAYLOAD)
+
+ payload2 = {
+ 'catalog_version': 1,
+ 'probes': {
+ 'nginx': {
+ 'detected': True,
+ 'service': {'active': True, 'ports': [80, 443]},
+ 'vhosts': [
+ # example.com doc root changed
+ {'server_name': 'example.com', 'root': '/var/www/new', 'upstream': None},
+ # api.example.com removed; shop.example.com added
+ {'server_name': 'shop.example.com', 'root': '/var/www/shop', 'upstream': None},
+ ],
+ },
+ 'foreign-panel': {'detected': True, 'markers': ['/usr/local/cpanel']},
+ },
+ }
+ new = survey_service.normalize_map(payload2)
+ diff = survey_service.diff_maps(old, new)
+
+ added = {s['domain'] for s in diff['sites']['added']}
+ removed = {s['domain'] for s in diff['sites']['removed']}
+ changed = {c['key'] for c in diff['sites']['changed']}
+ assert added == {'shop.example.com'}
+ assert removed == {'api.example.com'}
+ assert changed == {'example.com'}
+ assert diff['catalog_changed'] is False
+
+
+def test_diff_flags_catalog_change():
+ old = {'catalog_version': 1, 'sites': []}
+ new = {'catalog_version': 2, 'sites': []}
+ assert survey_service.diff_maps(old, new)['catalog_changed'] is True
+
+
+def test_record_and_list_snapshots(app):
+ from app import db
+ from app.models.server import Server
+
+ with app.app_context():
+ server = Server(name='obs-box', permissions=['survey:read'])
+ db.session.add(server)
+ db.session.commit()
+ sid = server.id
+
+ m1 = survey_service.normalize_map(FIXTURE_PAYLOAD)
+ s1 = survey_service.record_survey(sid, m1)
+ s2 = survey_service.record_survey(sid, m1)
+
+ surveys = survey_service.list_surveys(sid)
+ assert len(surveys) == 2
+ # Newest first.
+ assert surveys[0].id == s2.id
+ assert survey_service.latest_survey(sid).id == s2.id
+ # Round-trips the map.
+ assert s1.get_map()['foreign_panel_detected'] is True
diff --git a/docs/AGENT_DOCTOR_PROBE_SPEC.md b/docs/AGENT_DOCTOR_PROBE_SPEC.md
new file mode 100644
index 00000000..4072f160
--- /dev/null
+++ b/docs/AGENT_DOCTOR_PROBE_SPEC.md
@@ -0,0 +1,105 @@
+# Agent probe pack v2 — `doctor:probe` + `systemd:restart`
+
+> Status: SPEC (plan 26 Phase 4). The panel side is implemented and negotiates
+> to these commands when an agent advertises them; the agent-side handlers land
+> in the Go agent component (`agent/`, not in this checkout) and reach boxes via
+> the AgentVersion / staged-rollout rails, capability-gated.
+
+The fleet doctor v1 composes only commands every already-deployed agent
+understands (`systemd:status` per unit + `system:metrics`). That is correct but
+chatty: N units = N round trips per server per sweep. v2 adds one batched probe
+so a sweep is a single round trip per server, plus the restart command the
+allowlisted repair path needs. Both are **optimisations gated on a capability** —
+the composed v1 path stays as the permanent fallback (Fleet Contract, rule 5).
+
+## Capabilities advertised
+
+An agent that implements these adds them to its `capabilities` map on connect:
+
+```json
+{ "capabilities": { "doctor.probe": true, "systemd.restart": true } }
+```
+
+Older agents simply never advertise them and keep working on the v1 composed
+path forever (rule 2).
+
+## `doctor:probe` (read; capability `doctor.probe`)
+
+One round trip returning the batched health facts the fleet doctor needs.
+
+**Request params**
+
+```json
+{ "units": ["nginx", "docker"] }
+```
+
+`units` is the list of systemd service names to report. The agent MUST ignore
+unknown units (report them absent rather than erroring the whole probe).
+
+**Response `data`**
+
+```json
+{
+ "units": {
+ "nginx": { "active": true, "state": "active" },
+ "docker": { "active": false, "state": "inactive" }
+ },
+ "disk": { "percent": 61.0, "path": "/" },
+ "listening": [ { "port": 80, "proc": "nginx" }, { "port": 443, "proc": "nginx" } ]
+}
+```
+
+- `units[name].active` — boolean; the panel keys off this. `state` is the raw
+ systemd `ActiveState` for display and is optional.
+- `disk.percent` — used-percent of the root filesystem (0–100). The panel
+ computes headroom as `100 - percent`.
+- `listening` — optional summary of listening ports; informational, not yet a
+ check in v1 of the panel consumer (reserved).
+
+**Permission scope:** read-only; gate under the agent's existing system-read
+scope. No state is changed.
+
+## `systemd:restart` (write; capability `systemd.restart`)
+
+Restart one systemd unit. This is the target of the allowlisted `fleet.service`
+repair (Fleet Contract, rule 6); the panel refuses any unit not on its
+allowlist (`nginx`, `docker`) before dispatch, and `send_command` enforces the
+`systemd:restart` permission scope server-side.
+
+**Request params**
+
+```json
+{ "unit": "nginx" }
+```
+
+**Response `data`**
+
+```json
+{ "restarted": true, "unit": "nginx" }
+```
+
+On failure the agent returns `{"success": false, "error": "<systemctl stderr>"}`.
+
+**Permission scope:** `systemd:restart` (a write scope; must be explicitly
+granted to the server — it is not implied by the read scopes).
+
+## Panel negotiation (implemented)
+
+`FleetDoctorService._compose_server_checks` negotiates per server:
+
+```
+if connected and capabilities.doctor.probe:
+ rows = _probe_checks(server_id) # one doctor:probe round trip
+ if rows is None: # probe errored / unusable payload
+ rows = compose_v1() # fall back to systemd:status + system:metrics
+else:
+ rows = compose_v1()
+```
+
+Both paths emit **identical** check rows (`service.<name>`, `disk.headroom`), so
+the report/UI/repair layers don't care which path produced them. A stopped core
+service is `repairable` only when the agent also advertises `systemd.restart`.
+
+This is the canonical shape for adding a new agent command as an optimisation:
+ship it capability-gated, keep the composed path as the fallback, and make both
+produce the same rows.
diff --git a/docs/AGENT_SURVEY_SPEC.md b/docs/AGENT_SURVEY_SPEC.md
new file mode 100644
index 00000000..78cfac04
--- /dev/null
+++ b/docs/AGENT_SURVEY_SPEC.md
@@ -0,0 +1,123 @@
+# Agent survey executor — `survey:read` (read-only "flight")
+
+> Status: SPEC (plan 27 Phase 2). The panel side is implemented (catalog,
+> dispatch, normalization, snapshots, diff, API). The agent-side executor lands
+> in the Go agent component (`agent/`, not in this checkout) and reaches boxes
+> via the AgentVersion / staged-rollout rails, capability-gated. This document
+> is the contract between the two.
+
+Observe mode's heart is a **read-only survey**: install the agent on any Linux
+box — including one still managed by another control panel — and it flies a
+single pass that answers "what is running here, and what serves what?" without
+touching anything. The panel ships a declarative **probe catalog**, sends it per
+run, and stores the returned **Server Map** as an immutable snapshot.
+
+## Trust boundary — the agent enforces it, not the panel (Decision 2)
+
+This is the load-bearing security property. The panel is UNTRUSTED for the
+purposes of the survey: a compromised panel must not be able to make the agent
+execute arbitrary work or exfiltrate secrets.
+
+- The agent implements a **FIXED allowlist of read-only primitives**. Catalog
+ entries can only *combine* those primitives; a catalog can never name a shell
+ command, a binary to run, or a file whose *contents* leave the box wholesale.
+- The allowed primitives are exactly:
+ 1. **file-exists** — does a path exist (and is it a file/dir)?
+ 2. **glob** — expand a shell glob to a list of paths.
+ 3. **parse-light** — read a text file and extract only whitelisted directive
+ lines (e.g. `server_name`, `root`, `proxy_pass`, `ServerName`,
+ `DocumentRoot`, `ProxyPass`, cron schedule lines). Never returns the whole
+ file; never returns comments or secrets.
+ 4. **unit-status** — is a systemd unit active? (`ActiveState` only.)
+ 5. **socket-list** — listening sockets → `{port, proto, process-name}` (the
+ process *name*, never its full command line or environment).
+ 6. **process-list** — running process names (names only).
+ 7. **cert-meta** — for a cert path, the subject/SAN domains and `notAfter`
+ expiry. Private keys are **never** read.
+- **Env / credential files are listed by PATH ONLY, never read.** No file
+ contents leave the box beyond the parse-light directive extractions above.
+- If a catalog entry asks for anything outside this set, the agent MUST refuse
+ that entry (skip it, note it) rather than execute it.
+
+Panel-side, dispatch is gated by the `survey:read` permission scope (enforced by
+`send_command` before it reaches the agent) plus the `survey` capability. Old
+agents that never advertise `survey` degrade cleanly to "unsupported" (rule 2) —
+they are never errored.
+
+## Capability advertised
+
+```json
+{ "capabilities": { "survey": true } }
+```
+
+## `survey:read` (read; capability `survey`)
+
+**Request params** — the whole catalog, verbatim, so the agent needs no built-in
+knowledge of what to check and new probes ship as panel data:
+
+```json
+{ "catalog": { "version": 1, "probes": [ /* see survey_probe_catalog.yaml */ ] } }
+```
+
+Each probe entry carries `id`, `kind`, and a `detect` block (`ports` / `units` /
+`bins` / `paths`) and an optional `map` block (globs whose matched files are
+parse-light-extracted). The agent iterates probes, runs `detect` with the
+primitives above, and — when a probe is detected — fills its result.
+
+**Response `data`** — keyed by probe id. Every field is optional; the panel
+normalizes defensively (`normalize_map` in `survey_service.py`), so a partial
+payload from a partially-implemented agent still yields a valid (sparse) map:
+
+```json
+{
+ "catalog_version": 1,
+ "probes": {
+ "nginx": {
+ "detected": true,
+ "service": { "active": true, "ports": [80, 443] },
+ "vhosts": [
+ { "server_name": "example.com", "root": "/var/www/example", "upstream": null },
+ { "server_name": "api.example.com", "root": null, "upstream": "http://127.0.0.1:8001" }
+ ]
+ },
+ "apache": { "detected": false },
+ "php-fpm": { "detected": true, "service": { "active": true } },
+ "foreign-panel": { "detected": true, "markers": ["/usr/local/cpanel"] },
+ "docker": { "detected": true, "service": { "active": true },
+ "containers": [ { "name": "site1", "image": "wordpress:6", "ports": ["8001->80"] } ] },
+ "databases": { "detected": true,
+ "engines": [ { "name": "mysql", "active": true, "port": 3306 } ] },
+ "crontabs": { "crontabs": [ { "user": "root", "lines": ["0 3 * * * /usr/bin/backup"] } ] },
+ "certs": { "certs": [ { "domain": "example.com", "expires_at": "2026-10-01T00:00:00Z" } ] },
+ "mail": { "detected": false },
+ "listeners":{ "listeners": [ { "port": 80, "proto": "tcp", "process": "nginx" } ] }
+ }
+}
+```
+
+Field notes:
+
+- `probes.<id>.detected` — boolean; the panel adds a service row when true.
+- `vhosts[].server_name` / `root` / `upstream` — parse-light only. `upstream`
+ (or `proxy_pass`) present + no `root` ⇒ the panel treats the site as a reverse
+ proxy. The panel maps each vhost to a **site** row (`domain → stack → doc_root
+ → upstream → managed_by`).
+- `foreign-panel.markers` — the marker directories that existed. The panel
+ raises the **foreign-panel badge** and the "switch to Observed" suggestion
+ from this (Decision 4 — it SUGGESTS, never flips).
+- `certs[].expires_at` — ISO-8601; from `cert-meta` (`notAfter`). No key bytes.
+- Unknown/absent units MUST be reported absent, never error the whole survey.
+
+## Normalized Server Map (what the panel stores)
+
+`normalize_map` collapses the per-probe payload into stable top-level
+collections: `services`, `sites`, `databases`, `certs`, `cron`, `listeners`,
+`foreign_panels`, plus `foreign_panel_detected` and `probes_run`. Snapshots are
+immutable rows (`server_surveys`); any two are diffable by identity (site by
+domain, service by id, db by engine, cert by domain).
+
+## Rollout
+
+Ships like every agent feature: staged rollout via AgentVersion, capability
+negotiated. The panel works against agents that don't have it yet (they show
+"survey unsupported"), so there is no flag day.
diff --git a/frontend/src/services/api/doctor.js b/frontend/src/services/api/doctor.js
index 7c691ea3..913daf2b 100644
--- a/frontend/src/services/api/doctor.js
+++ b/frontend/src/services/api/doctor.js
@@ -16,6 +16,63 @@ export async function repairDoctorItems(items) {
});
}
+// Fleet doctor (plan 26) — the per-server health sweep merged across every
+// connected agent. getFleetDoctorReport returns { report: { ran_at, servers } };
+// runFleetSweep enqueues the sweep job (fan-out runs off the request thread)
+// and returns { job_id }.
+export async function getFleetDoctorReport() {
+ return this.request('/doctor/fleet');
+}
+
+export async function runFleetSweep() {
+ return this.request('/doctor/fleet/run', { method: 'POST' });
+}
+
+// Setup Health — "how set-up is this panel" (server IP / base domain / DNS
+// provider / cert / email / backups). Admin-only; cheap DB/settings probes.
+export async function getSetupHealth() {
+ return this.request('/setup-health');
+}
+
+// The requesting user's own setup-health items (e.g. the "secure your account"
+// nudge). Any authenticated user, about themselves.
+export async function getAccountSecurity() {
+ return this.request('/setup-health/account');
+}
+
+// Snooze / un-snooze a setup item (mutes it; it still renders, just quietly).
+export async function snoozeSetupItem(key, days = 30) {
+ return this.request('/setup-health/snooze', {
+ method: 'POST',
+ body: JSON.stringify({ key, days }),
+ });
+}
+
+export async function unsnoozeSetupItem(key) {
+ return this.request('/setup-health/snooze', {
+ method: 'DELETE',
+ body: JSON.stringify({ key }),
+ });
+}
+
+// Reconcile-on-connect (Phase 3): preview is a synchronous dry-run; apply
+// enqueues the job and returns { job_id }.
+export async function previewDnsBackfill() {
+ return this.request('/setup-health/reconcile/dns/preview', { method: 'POST' });
+}
+
+export async function applyDnsBackfill() {
+ return this.request('/setup-health/reconcile/dns/apply', { method: 'POST' });
+}
+
+export async function previewUrlFix() {
+ return this.request('/setup-health/reconcile/url-fix/preview', { method: 'POST' });
+}
+
+export async function applyUrlFix() {
+ return this.request('/setup-health/reconcile/url-fix/apply', { method: 'POST' });
+}
+
export async function getDriftReport() {
return this.request('/doctor/drift');
}
diff --git a/frontend/src/services/api/survey.js b/frontend/src/services/api/survey.js
new file mode 100644
index 00000000..7de6ae72
--- /dev/null
+++ b/frontend/src/services/api/survey.js
@@ -0,0 +1,52 @@
+// Server survey ("flight") — read-only Observe-mode survey over a paired agent.
+// Backs the Survey tab on server detail (/api/v1/servers/...).
+
+// The operator-facing probe index: exactly what the survey reads.
+export async function getSurveyCatalog() {
+ return this.request('/servers/survey/catalog');
+}
+
+// Fly a new survey against the server's agent; returns the stored snapshot.
+export async function runServerSurvey(serverId) {
+ return this.request(`/servers/${serverId}/survey`, { method: 'POST' });
+}
+
+// Switch a server between 'managed' and 'observed' adoption modes. Optionally
+// toggle the observed-mode agent:update break-glass (plan 31 #10). The response
+// carries `observed_blocked_count` — how many commands the Observe guard has
+// refused on this server (plan 31 #11).
+export async function setServerManagementMode(serverId, mode, allowAgentUpdateObserved = undefined) {
+ const body = { mode };
+ if (allowAgentUpdateObserved !== undefined) {
+ body.allow_agent_update_observed = allowAgentUpdateObserved;
+ }
+ return this.request(`/servers/${serverId}/management-mode`, {
+ method: 'POST',
+ body,
+ });
+}
+
+// Observe-mode status: current mode, the agent:update break-glass flag, and the
+// count of commands the Observe guard has blocked (plan 31 #10/#11).
+export async function getServerObservedStatus(serverId) {
+ return this.request(`/servers/${serverId}/observed-status`);
+}
+
+// List survey snapshots (newest first, without the map blob).
+export async function getServerSurveys(serverId) {
+ return this.request(`/servers/${serverId}/surveys`);
+}
+
+// Fetch one survey snapshot including its full Server Map.
+export async function getServerSurvey(serverId, surveyId) {
+ return this.request(`/servers/${serverId}/surveys/${surveyId}`);
+}
+
+// Diff two survey snapshots (defaults to the latest two).
+export async function diffServerSurveys(serverId, fromId = null, toId = null) {
+ const qs = new URLSearchParams();
+ if (fromId) qs.set('from', fromId);
+ if (toId) qs.set('to', toId);
+ const suffix = qs.toString() ? `?${qs.toString()}` : '';
+ return this.request(`/servers/${serverId}/surveys/diff${suffix}`);
+}
diff --git a/frontend/src/styles/pages/_doctor.scss b/frontend/src/styles/pages/_doctor.scss
index 90242b71..601db103 100644
--- a/frontend/src/styles/pages/_doctor.scss
+++ b/frontend/src/styles/pages/_doctor.scss
@@ -108,3 +108,132 @@
margin-top: $space-4;
}
}
+
+// Setup Health section — the setup.* checks rendered above the health sweep,
+// each with a "why it matters" line and a deep-link/repair fix.
+.doctor-setup {
+ margin-bottom: $space-5;
+
+ &__heading {
+ margin: 0 0 $space-3;
+ font-size: 12px;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ color: var(--text-faint);
+ }
+}
+
+.doctor-check__why {
+ margin-top: 2px;
+ font-size: 11.5px;
+ line-height: 1.45;
+ color: var(--text-faint);
+}
+
+.doctor-setup__head {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ flex-wrap: wrap;
+}
+
+.doctor-setup__actions {
+ display: flex;
+ gap: $space-2;
+}
+
+// Reconcile dry-run list (DNS backfill / URL fix preview).
+.doctor-reconcile-list {
+ list-style: none;
+ margin: $space-2 0 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: $space-1;
+ max-height: 240px;
+ overflow: auto;
+ font-size: 12.5px;
+ color: var(--text-dim);
+
+ code {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ }
+
+ &__warn {
+ color: var(--warning, #f5b342);
+ }
+}
+
+// A snoozed setup item — still rendered, just muted.
+.doctor-check--snoozed {
+ opacity: 0.6;
+
+ .doctor-check__title { font-weight: 500; }
+}
+
+.doctor-check__snooze {
+ flex-shrink: 0;
+}
+
+// ============================================
+// Fleet doctor (plan 26) — per-server sweep switcher + server groups.
+// ============================================
+
+.doctor-panel__switcher {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-2;
+ margin-right: $space-2;
+
+ &-label {
+ font-size: 11.5px;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ color: var(--text-faint);
+ }
+
+ &-select {
+ appearance: none;
+ background: var(--surface-2);
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ color: var(--text);
+ font-size: 12.5px;
+ padding: $space-1 $space-3;
+ cursor: pointer;
+
+ &:hover { border-color: var(--border); }
+ }
+}
+
+.doctor-fleet-group {
+ margin-bottom: $space-4;
+
+ &__head {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ padding: $space-2 0;
+ margin-bottom: $space-2;
+ border-bottom: 1px solid var(--border-soft);
+ }
+
+ &__name {
+ font-weight: $font-weight-semibold;
+ font-size: 13.5px;
+ color: var(--text);
+ }
+
+ &__counts {
+ display: flex;
+ gap: $space-2;
+ margin-left: auto;
+ font-size: 11.5px;
+ color: var(--text-faint);
+ }
+
+ &__count { white-space: nowrap; }
+}
diff --git a/frontend/src/styles/pages/_server-survey.scss b/frontend/src/styles/pages/_server-survey.scss
new file mode 100644
index 00000000..550f0223
--- /dev/null
+++ b/frontend/src/styles/pages/_server-survey.scss
@@ -0,0 +1,327 @@
+// Survey tab (plan 27) — the read-only Server Map on server detail.
+
+.survey-tab {
+ display: flex;
+ flex-direction: column;
+ gap: $space-5;
+
+ &__toolbar {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-4;
+ flex-wrap: wrap;
+ }
+
+ &__toolbar-info {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ flex-wrap: wrap;
+ }
+
+ &__toolbar-actions {
+ display: flex;
+ gap: $space-2;
+ }
+
+ &__muted {
+ color: $text-tertiary;
+ font-size: $font-size-sm;
+ }
+
+ &__mono {
+ font-family: $font-mono;
+ font-size: $font-size-sm;
+ }
+
+ &__section {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+ }
+
+ &__section-title {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+ margin: 0;
+ font-size: $font-size-sm;
+ font-weight: $font-weight-semibold;
+ color: $text-secondary;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ }
+
+ &__count {
+ margin-left: auto;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: $text-tertiary;
+ text-transform: none;
+ letter-spacing: 0;
+ }
+
+ &__site-action {
+ text-align: right;
+ white-space: nowrap;
+ }
+
+ &__migrated {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ font-size: $font-size-xs;
+ color: $success;
+
+ svg { color: $success; }
+ }
+
+ // Services — small chips grid
+ &__services {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+ gap: $space-2;
+ }
+
+ &__service {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+ padding: $space-2 $space-3;
+ background: $bg-card;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-md;
+
+ svg { color: $text-tertiary; flex-shrink: 0; }
+ }
+
+ &__service-name {
+ font-weight: $font-weight-medium;
+ margin-right: auto;
+ }
+
+ &__service-ports {
+ font-family: $font-mono;
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ }
+
+ // Sites table
+ &__table-wrap {
+ overflow-x: auto;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-lg;
+ }
+
+ &__table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: $font-size-sm;
+
+ th, td {
+ padding: $space-2 $space-3;
+ text-align: left;
+ border-bottom: 1px solid $border-subtle;
+ }
+
+ th {
+ color: $text-tertiary;
+ font-weight: $font-weight-medium;
+ background: $bg-secondary;
+ }
+
+ tr:last-child td { border-bottom: none; }
+ }
+
+ &__list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: $space-1;
+
+ li {
+ padding: $space-1 0;
+ font-size: $font-size-sm;
+ }
+ }
+
+ // Diff summary
+ &__diff {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-wrap: wrap;
+ gap: $space-2;
+
+ li { display: flex; gap: $space-1; }
+ }
+
+ // Probe index ("what we check")
+ &__catalog {
+ padding: $space-4;
+ background: $bg-secondary;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-lg;
+ }
+
+ &__catalog-list {
+ list-style: none;
+ margin: $space-3 0 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+
+ li { font-size: $font-size-sm; }
+ }
+
+ &__catalog-locs {
+ display: flex;
+ flex-wrap: wrap;
+ gap: $space-1;
+ margin-top: $space-1;
+
+ code {
+ font-family: $font-mono;
+ font-size: $font-size-xs;
+ padding: 1px 6px;
+ background: $bg-card;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-sm;
+ color: $text-tertiary;
+ }
+ }
+
+ .spin { animation: spin 1s linear infinite; }
+
+ // Decommission checklist — shown once all surveyed sites are migrated.
+ &__decommission {
+ padding: $space-4;
+ background: rgba($success, 0.06);
+ border: 1px solid rgba($success, 0.3);
+ border-radius: $radius-lg;
+
+ .survey-tab__section-title { color: $success; }
+ .survey-tab__section-title svg { color: $success; }
+ }
+
+ &__checklist {
+ margin: $space-3 0 0;
+ padding-left: $space-5;
+ display: flex;
+ flex-direction: column;
+ gap: $space-2;
+
+ li {
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ line-height: 1.5;
+ }
+
+ strong { color: $text-primary; }
+ }
+
+ // "This box looks like it's run by another panel — switch to Observed"
+ &__suggest {
+ display: flex;
+ align-items: flex-start;
+ gap: $space-3;
+ padding: $space-4;
+ background: $warning-bg;
+ border: 1px solid $warning-border;
+ border-radius: $radius-lg;
+
+ > svg { color: $warning; flex-shrink: 0; margin-top: 2px; }
+
+ button { flex-shrink: 0; }
+ }
+
+ &__suggest-body {
+ flex: 1;
+
+ strong { display: block; margin-bottom: 2px; }
+
+ p {
+ margin: 0;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ line-height: 1.5;
+ }
+ }
+
+ // Observed-mode panel: break-glass toggle + blocked-command counter (#10/#11).
+ &__observed {
+ margin-bottom: $space-4;
+ padding: $space-4;
+ background: $warning-bg;
+ border: 1px solid $warning-border;
+ border-radius: $radius-lg;
+
+ p { margin: $space-2 0; }
+ }
+
+ &__observed-head {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ }
+
+ &__observed-toggle {
+ display: flex;
+ align-items: flex-start;
+ gap: $space-2;
+ font-size: $font-size-sm;
+ color: $text-primary;
+ cursor: pointer;
+
+ input { margin-top: 3px; flex-shrink: 0; }
+
+ code {
+ padding: 1px 4px;
+ border-radius: $radius-sm;
+ background: rgba(0, 0, 0, 0.06);
+ }
+ }
+}
+
+// Observed read-only banner on the server detail page.
+.server-observed-banner {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-4;
+ margin-bottom: $space-4;
+ padding: $space-3 $space-4;
+ background: $warning-bg;
+ border: 1px solid $warning-border;
+ border-radius: $radius-lg;
+
+ &__text {
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ line-height: 1.5;
+
+ strong { color: $warning; }
+ }
+
+ a { flex-shrink: 0; }
+}
+
+// Observed-mode chip on the server list rows.
+.server-row__mode-chip {
+ display: inline-block;
+ margin-left: $space-2;
+ padding: 1px 8px;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ color: $warning;
+ background: $warning-bg;
+ border: 1px solid $warning-border;
+ border-radius: $radius-full;
+ vertical-align: middle;
+}