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(connect): report this server's policy facts to ServerKit Cloud

Juan Denis7ebc2aba342a
diff --git a/backend/app/services/connect_client.py b/backend/app/services/connect_client.py
index 93620f63..099f1a91 100644
--- a/backend/app/services/connect_client.py
+++ b/backend/app/services/connect_client.py
@@ -37,7 +37,7 @@ import requests
from app import paths
from app.services import connect_keys
-from app.services import connect_commands, connect_storage
+from app.services import connect_commands, connect_policy, connect_storage
from app.services.connect_metrics import MetricsPublisher
from app.services.connect_updates import UpdateCheck, check_and_apply, fetch_jwks
@@ -57,6 +57,10 @@ POLL_INTERVAL_S = 3.0
# Backup destinations change when a backup runs, not every minute; Cloud can
# ask for one immediately with the storage.report command.
STORAGE_INTERVAL_S = 300.0
+# How often the policy facts document goes out unasked. Six
+# hours is the plan's own number and the abuse control that goes with it;
+# "Check now" is the policy.report command, not a shorter interval.
+POLICY_INTERVAL_S = 6 * 3600.0
def _peek_command_id(token) -> str:
@@ -624,6 +628,8 @@ class RelayClient:
self._jwks = None
self._storage_stream = 0
self._storage_next_at = 0.0
+ self._policy_stream = 0
+ self._policy_next_at = 0.0
# -- lifecycle -----------------------------------------------------
@@ -750,6 +756,7 @@ class RelayClient:
self._check_for_update(cfg)
self._load_jwks(cfg)
self._publish_storage(ws)
+ self._publish_policy(ws)
while self.running:
try:
raw = ws.recv(timeout=PING_INTERVAL_S)
@@ -757,10 +764,12 @@ class RelayClient:
ws.send('{"t":"ping"}')
self._publish_metrics(ws)
self._publish_storage(ws)
+ self._publish_policy(ws)
continue
self._handle_frame(ws, raw)
self._publish_metrics(ws)
self._publish_storage(ws)
+ self._publish_policy(ws)
return 'stopped'
except Exception as exc:
from websockets.exceptions import ConnectionClosed
@@ -966,6 +975,31 @@ class RelayClient:
return self._send(ws, connect_storage.status_frame(
f'sto{self._storage_stream}', snapshot))
+ # -- the policy stream --------------------------------
+
+ def publish_policy(self, facts=None) -> bool:
+ """Send one facts document now. Used by the policy.report command."""
+ ws = self._ws
+ if ws is None:
+ return False
+ facts = facts if facts is not None else connect_policy.build_facts(self.app)
+ self._policy_stream += 1
+ return self._send(ws, connect_policy.facts_frame(
+ f'pol{self._policy_stream}', facts))
+
+ def _publish_policy(self, ws):
+ now = time.monotonic()
+ if now < self._policy_next_at:
+ return
+ self._policy_next_at = now + POLICY_INTERVAL_S
+ try:
+ facts = connect_policy.build_facts(self.app)
+ except Exception:
+ logger.debug('Connect policy: could not build facts', exc_info=True)
+ return
+ self._policy_stream += 1
+ self._send(ws, connect_policy.facts_frame(f'pol{self._policy_stream}', facts))
+
def _publish_storage(self, ws):
"""Where backups go and how they went, on its own slow cadence: this
changes when a backup runs, not every minute."""
diff --git a/backend/app/services/connect_commands.py b/backend/app/services/connect_commands.py
index 880d5da0..39b24bbe 100644
--- a/backend/app/services/connect_commands.py
+++ b/backend/app/services/connect_commands.py
@@ -42,6 +42,14 @@ ACTION_SCOPES = {
'storage.unassign': 'storage.manage',
'storage.test': 'storage.manage',
'storage.report': 'storage.manage',
+ # Policy repairs, bundled as the consent screen groups them:
+ # agreeing to "turn the firewall back on" is not agreeing to "install
+ # operating system packages".
+ 'security.firewall.enable': 'security.remediate',
+ 'security.fail2ban.enable': 'security.remediate',
+ 'security.2fa.require': 'security.remediate',
+ 'packages.security_upgrade': 'packages.upgrade',
+ 'backup.verify': 'backup.run',
}
@@ -180,4 +188,4 @@ def result_frame(cmd_id: str, state: str, result: dict = None, stream: str = Non
# Importing the handler modules is what registers them. Kept at the bottom so
# a handler module may import this one for @handler.
-from app.services import connect_storage # noqa: E402,F401
+from app.services import connect_policy, connect_storage # noqa: E402,F401
diff --git a/backend/app/services/connect_policy.py b/backend/app/services/connect_policy.py
new file mode 100644
index 00000000..b3f16898
--- /dev/null
+++ b/backend/app/services/connect_policy.py
@@ -0,0 +1,293 @@
+"""The panel half of fleet policies.
+
+Two jobs, and neither of them is deciding anything. ServerKit Cloud holds the
+policy; this panel reports what is true and, when asked with a consent the
+operator granted, changes it.
+
+**Facts.** `build_facts()` assembles one document from services that already
+exist — the firewall, fail2ban, the 2FA policy, the panel updater, backup
+policies, the storage destination — and it advertises a `capabilities` list
+naming only the bundles it could actually read. That list is the whole of the
+capability gate: a rule Cloud cannot get facts for reads "not checkable here"
+rather than "failing", which is FLEET_CONTRACT rule 2 and the difference
+between a useful compliance page and a wall of red on servers that are fine.
+
+**Repairs.** Four handlers, each calling the panel's own path — the same code
+an operator pressing the button in this panel would run. A repair this install
+cannot perform says so in a sentence rather than failing obscurely; Cloud shows
+that sentence next to the finding.
+"""
+import logging
+from datetime import datetime, timezone
+
+from app.services.connect_commands import handler
+
+logger = logging.getLogger(__name__)
+
+FACTS_VERSION = 1
+
+
+def _iso(value):
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ if isinstance(value, datetime):
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.isoformat()
+ return None
+
+
+# ==================== facts ====================
+
+
+def build_facts(app=None) -> dict:
+ """One document describing this server. Never raises: a probe that fails
+ leaves its bundle out of `capabilities`, which is the honest answer."""
+ facts = {
+ "facts_version": FACTS_VERSION,
+ "reported_at": datetime.now(timezone.utc).isoformat(),
+ "capabilities": [],
+ }
+
+ security = _security_facts()
+ if security:
+ facts["security"] = security
+ facts["capabilities"].append("security")
+
+ updates = _update_facts()
+ if updates:
+ facts["updates"] = updates
+ facts["capabilities"].append("updates")
+
+ backups = _backup_facts(app)
+ if backups is not None:
+ facts["backups"] = backups
+ facts["capabilities"].append("backups")
+
+ return facts
+
+
+def _security_facts() -> dict:
+ out = {}
+ try:
+ from app.services.firewall_service import FirewallService
+ status = FirewallService.get_status() or {}
+ out["firewall_enabled"] = bool(status.get("any_active"))
+ except Exception:
+ logger.debug("Connect policy: no firewall status", exc_info=True)
+ try:
+ from app.services.firewall_service import FirewallService
+ ports = FirewallService.ssh_ports()
+ if ports:
+ # One number is what the rule compares; the lowest configured port
+ # is the one an untargeted scan finds first.
+ out["ssh_port"] = int(min(ports))
+ except Exception:
+ logger.debug("Connect policy: no ssh port", exc_info=True)
+ try:
+ from app.services.fail2ban_jail_service import Fail2banJailService
+ status = Fail2banJailService.get_fail2ban_status() or {}
+ out["fail2ban_running"] = bool(status.get("installed")
+ and status.get("service_running"))
+ except Exception:
+ logger.debug("Connect policy: no fail2ban status", exc_info=True)
+ try:
+ from app.services.security_policy_service import SecurityPolicyService
+ out["panel_2fa_required"] = bool(SecurityPolicyService.require_2fa_enabled())
+ except Exception:
+ logger.debug("Connect policy: no 2FA policy", exc_info=True)
+ return out
+
+
+def _update_facts() -> dict:
+ out = {}
+ try:
+ from app.services import panel_update_service
+ out["panel_version"] = panel_update_service.get_status().get("version")
+ except Exception:
+ logger.debug("Connect policy: no panel version", exc_info=True)
+ # Pending operating-system security updates are not probed by this panel
+ # yet, so `packages` is deliberately absent from capabilities and Cloud
+ # reads that rule as "not checkable here" rather than "no updates pending".
+ return out
+
+
+def _backup_facts(app=None) -> dict | None:
+ """Backups need an app context to read policy rows; the destination does
+ not. A panel with no backup engine returns None and is not judged on it."""
+ out = {}
+ try:
+ from app.services.storage_provider_service import StorageProviderService
+ config = StorageProviderService.get_config()
+ out["destination_configured"] = (config.get("provider") or "local") != "local"
+ except Exception:
+ logger.debug("Connect policy: no storage config", exc_info=True)
+
+ rows = _backup_policy_rows(app)
+ if rows is None and not out:
+ return None
+ if rows is not None:
+ newest_success = newest_verify = None
+ for row in rows:
+ if row.get("last_status") == "success" and row.get("last_run_at"):
+ at = row["last_run_at"]
+ newest_success = at if newest_success is None or at > newest_success else newest_success
+ if row.get("last_drill_at"):
+ at = row["last_drill_at"]
+ newest_verify = at if newest_verify is None or at > newest_verify else newest_verify
+ # The keys are always present when policies could be read, so Cloud can
+ # tell "never succeeded" apart from "did not report".
+ out["last_success_at"] = _iso(newest_success)
+ out["last_verified_at"] = _iso(newest_verify)
+ return out
+
+
+def _backup_policy_rows(app=None):
+ try:
+ from app.models.backup_policy import BackupPolicy
+ except Exception:
+ return None
+
+ def collect():
+ return [{"last_status": p.last_status, "last_run_at": p.last_run_at,
+ "last_drill_at": p.last_drill_at} for p in BackupPolicy.query.all()]
+
+ try:
+ if app is not None:
+ with app.app_context():
+ return collect()
+ return collect()
+ except Exception:
+ logger.debug("Connect policy: could not read backup policies", exc_info=True)
+ return None
+
+
+def facts_frame(stream_id: str, facts: dict) -> dict:
+ return {"s": stream_id, "t": "open", "k": "policy", "p": {"facts": facts}}
+
+
+# ==================== commands ====================
+
+
+@handler('policy.report')
+def report(args: dict, app=None) -> dict:
+ """"Check now". Build a document and push it up the policy stream."""
+ facts = build_facts(app)
+ client = _relay_client()
+ if client is None or not client.publish_policy(facts):
+ return {'ok': False, 'summary': 'The panel is not connected to ServerKit Cloud right '
+ 'now, so the check could not be sent. It goes out on '
+ 'the next connection.'}
+ return {'ok': True, 'summary': f'Reported {len(facts.get("capabilities") or [])} fact '
+ f'bundles.'}
+
+
+@handler('security.firewall.enable')
+def enable_firewall(args: dict, app=None) -> dict:
+ """Turn the host firewall on, through the panel's own path — including its
+ refusal to lock SSH out, which is exactly the check we want here."""
+ try:
+ from app.services.firewall_service import FirewallService
+ except Exception as exc:
+ return {'ok': False, 'summary': f'This install has no firewall management ({exc}).'}
+ result = FirewallService.enable() or {}
+ if result.get('success') is False or result.get('error'):
+ return {'ok': False, 'summary': result.get('error') or 'The firewall did not come up.'}
+ return {'ok': True, 'summary': 'The host firewall is on.'}
+
+
+@handler('security.2fa.require')
+def require_2fa(args: dict, app=None) -> dict:
+ """Turn on the panel's require-2FA policy. Its grace window starts now, so
+ nobody is locked out by a policy that arrived while they were asleep."""
+ try:
+ from app.services.security_policy_service import SecurityPolicyService
+ except Exception as exc:
+ return {'ok': False, 'summary': f'This install has no 2FA policy ({exc}).'}
+
+ def go():
+ SecurityPolicyService.set_require_2fa(True)
+ if app is not None:
+ with app.app_context():
+ go()
+ else:
+ go()
+ return {'ok': True, 'summary': 'The panel now requires two-factor authentication, with its '
+ 'usual grace window for people who have not set it up yet.'}
+
+
+@handler('security.fail2ban.enable')
+def enable_fail2ban(args: dict, app=None) -> dict:
+ """Start fail2ban if this host manages its own services."""
+ try:
+ from app.services.fail2ban_jail_service import Fail2banJailService
+ status = Fail2banJailService.get_fail2ban_status() or {}
+ except Exception as exc:
+ return {'ok': False, 'summary': f'This install cannot manage fail2ban ({exc}).'}
+ if not status.get('installed'):
+ return {'ok': False, 'summary': 'fail2ban is not installed on this host. Install it and '
+ 'ServerKit Cloud will see it on the next check.'}
+ started = _systemctl('start', 'fail2ban')
+ if started is not True:
+ return {'ok': False, 'summary': f'fail2ban would not start: {started}'}
+ return {'ok': True, 'summary': 'fail2ban is running.'}
+
+
+@handler('backup.verify')
+def verify_backup(args: dict, app=None) -> dict:
+ try:
+ from app.services.backup_offsite_service import BackupOffsiteService
+ except Exception as exc:
+ return {'ok': False, 'summary': f'This install has no offsite verification ({exc}).'}
+
+ def go():
+ return BackupOffsiteService.run_offsite_verify()
+ result = (go() if app is None else _in_app(app, go)) or {}
+ if result.get('success') is False or result.get('error'):
+ return {'ok': False, 'summary': result.get('error') or 'The verification did not pass.'}
+ return {'ok': True, 'summary': 'The most recent backup was read back from its destination.'}
+
+
+@handler('packages.security_upgrade')
+def security_upgrade(args: dict, app=None) -> dict:
+ """Not implemented on the panel yet, and it says so rather than pretending.
+
+ Cloud shows this sentence next to the finding, which is the truth: the rule
+ that produced it evaluates `unsupported` anyway, because `_update_facts`
+ does not advertise the `packages` bundle.
+ """
+ return {'ok': False,
+ 'summary': 'This version of ServerKit does not install operating-system security '
+ 'updates from ServerKit Cloud. Run them on the host, or update ServerKit '
+ 'and try again.'}
+
+
+def _in_app(app, fn):
+ with app.app_context():
+ return fn()
+
+
+def _systemctl(action: str, unit: str):
+ """True, or the reason it did not work. Never raises."""
+ import shutil
+ import subprocess
+ if shutil.which('systemctl') is None:
+ return 'this host does not use systemd'
+ try:
+ out = subprocess.run(['systemctl', action, unit], capture_output=True,
+ text=True, timeout=60)
+ except Exception as exc:
+ return str(exc)
+ if out.returncode == 0:
+ return True
+ return (out.stderr or out.stdout or f'systemctl {action} {unit} exited {out.returncode}').strip()
+
+
+def _relay_client():
+ try:
+ from app.services import connect_client
+ return connect_client.get_client()
+ except Exception:
+ return None
diff --git a/backend/tests/test_connect_policy.py b/backend/tests/test_connect_policy.py
new file mode 100644
index 00000000..54a7a8a2
--- /dev/null
+++ b/backend/tests/test_connect_policy.py
@@ -0,0 +1,250 @@
+"""The panel half of fleet policies.
+
+What matters here is the capability gate: a probe that cannot answer must
+leave its bundle out of `capabilities`, because that is what makes ServerKit
+Cloud show "not checkable here" instead of marking a healthy server
+non-compliant. Every probe is replaced by the test, so nothing touches the
+host.
+"""
+import pytest
+
+from app.services import connect_policy
+
+
+class _Firewall:
+ active = True
+ ports = [2222]
+
+ @classmethod
+ def get_status(cls):
+ return {"any_active": cls.active}
+
+ @classmethod
+ def ssh_ports(cls):
+ return list(cls.ports)
+
+ @classmethod
+ def enable(cls, firewall=None, force=False):
+ cls.active = True
+ return {"success": True}
+
+
+class _Fail2ban:
+ installed = True
+ running = True
+
+ @classmethod
+ def get_fail2ban_status(cls):
+ return {"installed": cls.installed, "service_running": cls.running}
+
+
+class _SecurityPolicy:
+ required = False
+
+ @classmethod
+ def require_2fa_enabled(cls):
+ return cls.required
+
+ @classmethod
+ def set_require_2fa(cls, enabled, user_id=None):
+ cls.required = bool(enabled)
+ return cls.required
+
+
[email protected](autouse=True)
+def probes(monkeypatch):
+ """Point every probe at an in-memory host."""
+ import app.services.firewall_service as fw
+ import app.services.fail2ban_jail_service as f2b
+ import app.services.security_policy_service as sp
+ import app.services.panel_update_service as pu
+
+ _Firewall.active = True
+ _Firewall.ports = [2222]
+ _Fail2ban.installed = True
+ _Fail2ban.running = True
+ _SecurityPolicy.required = False
+
+ monkeypatch.setattr(fw, "FirewallService", _Firewall)
+ monkeypatch.setattr(f2b, "Fail2banJailService", _Fail2ban)
+ monkeypatch.setattr(sp, "SecurityPolicyService", _SecurityPolicy)
+ monkeypatch.setattr(pu, "get_status", lambda: {"version": "1.9.22"})
+ monkeypatch.setattr(connect_policy, "_backup_policy_rows", lambda app=None: [])
+ return True
+
+
+# ---------- facts ----------
+
+
+def test_a_healthy_host_reports_every_bundle_it_can():
+ facts = connect_policy.build_facts()
+ assert facts["facts_version"] == 1
+ assert facts["security"]["firewall_enabled"] is True
+ assert facts["security"]["fail2ban_running"] is True
+ assert facts["security"]["ssh_port"] == 2222
+ assert facts["security"]["panel_2fa_required"] is False
+ assert facts["updates"]["panel_version"] == "1.9.22"
+ assert "security" in facts["capabilities"]
+ assert "updates" in facts["capabilities"]
+
+
+def test_packages_are_never_advertised_because_nothing_probes_them():
+ """The rule Cloud has for pending security updates must read as
+ "not checkable here", not as "no updates pending"."""
+ facts = connect_policy.build_facts()
+ assert "packages" not in facts["capabilities"]
+ assert "os_security_pending" not in facts["updates"]
+
+
+def test_a_firewall_that_is_off_is_reported_as_off():
+ _Firewall.active = False
+ assert connect_policy.build_facts()["security"]["firewall_enabled"] is False
+
+
+def test_fail2ban_installed_but_stopped_is_not_running():
+ _Fail2ban.running = False
+ assert connect_policy.build_facts()["security"]["fail2ban_running"] is False
+
+
+def test_a_probe_that_raises_leaves_its_fact_out_rather_than_guessing(monkeypatch):
+ import app.services.firewall_service as fw
+
+ class Broken:
+ @staticmethod
+ def get_status():
+ raise RuntimeError("no ufw here")
+
+ @staticmethod
+ def ssh_ports():
+ raise RuntimeError("no sshd_config")
+ monkeypatch.setattr(fw, "FirewallService", Broken)
+ facts = connect_policy.build_facts()
+ assert "firewall_enabled" not in facts["security"]
+ assert "ssh_port" not in facts["security"]
+ # The bundle is still advertised: 2FA and fail2ban answered.
+ assert "security" in facts["capabilities"]
+
+
+def test_a_panel_with_no_backup_engine_is_not_judged_on_backups(monkeypatch):
+ monkeypatch.setattr(connect_policy, "_backup_policy_rows", lambda app=None: None)
+
+ import app.services.storage_provider_service as sps
+
+ class NoStorage:
+ @staticmethod
+ def get_config():
+ raise RuntimeError("no storage.json")
+ monkeypatch.setattr(sps, "StorageProviderService", NoStorage)
+ facts = connect_policy.build_facts()
+ assert "backups" not in facts["capabilities"]
+ assert "backups" not in facts
+
+
+def test_the_newest_successful_backup_is_the_one_reported(monkeypatch):
+ from datetime import datetime, timedelta, timezone
+ now = datetime.now(timezone.utc)
+ monkeypatch.setattr(connect_policy, "_backup_policy_rows", lambda app=None: [
+ {"last_status": "success", "last_run_at": now - timedelta(hours=9),
+ "last_drill_at": None},
+ {"last_status": "success", "last_run_at": now - timedelta(hours=2),
+ "last_drill_at": now - timedelta(days=3)},
+ {"last_status": "failed", "last_run_at": now, "last_drill_at": None},
+ ])
+ facts = connect_policy.build_facts()
+ assert facts["backups"]["last_success_at"].startswith(
+ (now - timedelta(hours=2)).isoformat()[:13])
+ assert facts["backups"]["last_verified_at"] is not None
+ assert "backups" in facts["capabilities"]
+
+
+def test_a_backup_that_never_succeeded_reports_the_key_as_null(monkeypatch):
+ """Null, not absent: Cloud tells "never succeeded" apart from "did not
+ report" by whether the key is there."""
+ monkeypatch.setattr(connect_policy, "_backup_policy_rows", lambda app=None: [
+ {"last_status": "failed", "last_run_at": None, "last_drill_at": None},
+ ])
+ facts = connect_policy.build_facts()
+ assert facts["backups"]["last_success_at"] is None
+ assert "last_success_at" in facts["backups"]
+
+
+def test_the_facts_frame_is_the_policy_stream():
+ frame = connect_policy.facts_frame("pol1", {"facts_version": 1})
+ assert frame == {"s": "pol1", "t": "open", "k": "policy",
+ "p": {"facts": {"facts_version": 1}}}
+
+
+# ---------- repairs ----------
+
+
+def test_turning_the_firewall_on_uses_the_panels_own_path():
+ _Firewall.active = False
+ out = connect_policy.enable_firewall({})
+ assert out["ok"] is True
+ assert _Firewall.active is True
+
+
+def test_a_firewall_that_refuses_to_come_up_says_why(monkeypatch):
+ import app.services.firewall_service as fw
+
+ class Refuses(_Firewall):
+ @classmethod
+ def enable(cls, firewall=None, force=False):
+ return {"success": False, "error": "enabling this would lock SSH out"}
+ monkeypatch.setattr(fw, "FirewallService", Refuses)
+ out = connect_policy.enable_firewall({})
+ assert out["ok"] is False
+ assert "lock SSH out" in out["summary"]
+
+
+def test_requiring_two_factor_turns_the_policy_on():
+ out = connect_policy.require_2fa({})
+ assert out["ok"] is True
+ assert _SecurityPolicy.required is True
+ assert "grace window" in out["summary"]
+
+
+def test_fail2ban_that_is_not_installed_is_refused_with_what_to_do():
+ _Fail2ban.installed = False
+ out = connect_policy.enable_fail2ban({})
+ assert out["ok"] is False
+ assert "not installed" in out["summary"]
+
+
+def test_security_updates_are_refused_honestly_rather_than_faked():
+ out = connect_policy.security_upgrade({})
+ assert out["ok"] is False
+ assert "does not install operating-system security updates" in out["summary"]
+
+
+def test_check_now_without_a_relay_connection_says_so(monkeypatch):
+ monkeypatch.setattr(connect_policy, "_relay_client", lambda: None)
+ out = connect_policy.report({})
+ assert out["ok"] is False
+ assert "not connected to ServerKit Cloud" in out["summary"]
+
+
+def test_check_now_publishes_the_document(monkeypatch):
+ sent = []
+
+ class Client:
+ def publish_policy(self, facts):
+ sent.append(facts)
+ return True
+ monkeypatch.setattr(connect_policy, "_relay_client", lambda: Client())
+ out = connect_policy.report({})
+ assert out["ok"] is True
+ assert sent and sent[0]["facts_version"] == 1
+
+
+def test_every_policy_action_is_registered_with_its_consent_scope():
+ from app.services import connect_commands
+ for action in ("policy.report", "security.firewall.enable", "security.fail2ban.enable",
+ "security.2fa.require", "packages.security_upgrade", "backup.verify"):
+ assert action in connect_commands.HANDLERS
+ assert connect_commands.scope_for("security.firewall.enable") == "security.remediate"
+ assert connect_commands.scope_for("packages.security_upgrade") == "packages.upgrade"
+ assert connect_commands.scope_for("backup.verify") == "backup.run"
+ # policy.report has no entry, so its scope is its own name — the Observe
+ # bundle every paired panel already grants.
+ assert connect_commands.scope_for("policy.report") == "policy.report"