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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
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.pyindex 93620f63..099f1a91 100644--- a/backend/app/services/connect_client.py+++ b/backend/app/services/connect_client.py@@ -37,7 +37,7 @@ import requestsfrom app import pathsfrom app.services import connect_keys-from app.services import connect_commands, connect_storage+from app.services import connect_commands, connect_policy, connect_storagefrom app.services.connect_metrics import MetricsPublisherfrom 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.0def _peek_command_id(token) -> str:@@ -624,6 +628,8 @@ class RelayClient:self._jwks = Noneself._storage_stream = 0self._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)continueself._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: thischanges when a backup runs, not every minute."""diff --git a/backend/app/services/connect_commands.py b/backend/app/services/connect_commands.pyindex 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,F401diff --git a/backend/app/services/connect_policy.py b/backend/app/services/connect_policy.pynew file mode 100644index 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 Nonediff --git a/backend/tests/test_connect_policy.py b/backend/tests/test_connect_policy.pynew file mode 100644index 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"