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(cli): API-backed operator verbs and diagnostic support bundle

Juan Denisc3f356b6fbf3
diff --git a/backend/app/api/support_bundle.py b/backend/app/api/support_bundle.py
new file mode 100644
index 00000000..a71d9b12
--- /dev/null
+++ b/backend/app/api/support_bundle.py
@@ -0,0 +1,37 @@
+"""Support bundle API: build and download a scrubbed diagnostic zip.
+
+Registration (app/__init__.py):
+ from app.api.support_bundle import support_bundle_bp
+ app.register_blueprint(support_bundle_bp, url_prefix='/api/v1/support-bundle')
+"""
+import os
+from datetime import datetime
+
+from flask import Blueprint, jsonify, send_file
+
+from app.middleware.rbac import admin_required
+from app.services import support_bundle_service
+
+support_bundle_bp = Blueprint('support_bundle', __name__)
+
+
+@support_bundle_bp.route('', methods=['POST'])
+@admin_required
+def build_support_bundle():
+ """Build a diagnostic support bundle and return it as a zip download."""
+ try:
+ path = support_bundle_service.build()
+ except Exception as exc: # noqa: BLE001 - surface as a JSON error, not a 500 page
+ return jsonify({'error': f'Failed to build support bundle: {exc}'}), 500
+
+ if not os.path.isfile(path):
+ return jsonify({'error': 'Support bundle was not created'}), 500
+
+ filename = f"serverkit-support-{datetime.utcnow().strftime('%Y-%m-%d')}.zip"
+ return send_file(
+ path,
+ mimetype='application/zip',
+ as_attachment=True,
+ download_name=filename,
+ max_age=0,
+ )
diff --git a/backend/app/services/cli_api_client.py b/backend/app/services/cli_api_client.py
new file mode 100644
index 00000000..a58ea658
--- /dev/null
+++ b/backend/app/services/cli_api_client.py
@@ -0,0 +1,150 @@
+"""Helpers for CLI commands that talk to the local panel API.
+
+Two pieces:
+
+* ``mint_breakglass_token()`` — runs in-process (create_app + app_context) and
+ mints a short-lived JWT for the first active admin user. Possession of
+ root/shell on the box already implies full control of the panel, so this is
+ a convenience, not an escalation; every mint is audit-logged.
+* ``ApiClient`` — a tiny requests wrapper pointed at the local panel
+ (``http://127.0.0.1:<port>/api/v1``) with a bearer token, short timeouts and
+ a helpful message when the panel isn't running.
+"""
+import os
+from datetime import timedelta
+
+DEFAULT_PORT = 5000
+DEFAULT_TIMEOUT = 5
+
+BREAKGLASS_TTL = timedelta(minutes=10)
+BREAKGLASS_AUDIT_ACTION = 'cli.breakglass'
+
+
+class CliApiError(Exception):
+ """Raised for any CLI-facing API failure; str(e) is user-presentable."""
+
+
+def resolve_port():
+ """Panel port: PORT env first (run.py contract), then SERVERKIT_PORT,
+ then the config default 5000."""
+ for var in ('PORT', 'SERVERKIT_PORT'):
+ raw = os.environ.get(var, '').strip()
+ if raw:
+ try:
+ return int(raw)
+ except ValueError:
+ continue
+ return DEFAULT_PORT
+
+
+def base_url(port=None):
+ return f"http://127.0.0.1:{port or resolve_port()}/api/v1"
+
+
+def find_breakglass_admin():
+ """First active admin user, or None. Requires an app context."""
+ from app.models import User
+ return (
+ User.query
+ .filter_by(role='admin', is_active=True)
+ .order_by(User.id.asc())
+ .first()
+ )
+
+
+def mint_breakglass_token(app=None):
+ """Mint a short-lived admin access token for local CLI use.
+
+ Returns ``(token, user)``. Raises ``CliApiError`` when no active admin
+ exists. Creates its own app/app-context unless one is supplied or already
+ active.
+ """
+ from flask import current_app
+
+ if app is None:
+ try:
+ current_app._get_current_object() # noqa: SLF001 - presence probe
+ return _mint_in_context()
+ except RuntimeError:
+ from app import create_app
+ app = create_app()
+
+ with app.app_context():
+ return _mint_in_context()
+
+
+def _mint_in_context():
+ from flask_jwt_extended import create_access_token
+
+ user = find_breakglass_admin()
+ if user is None:
+ raise CliApiError('No active admin user found — create one with "serverkit create-admin".')
+
+ token = create_access_token(identity=user.id, expires_delta=BREAKGLASS_TTL)
+
+ try:
+ from app.services.audit_service import AuditService
+ AuditService.log(
+ action=BREAKGLASS_AUDIT_ACTION,
+ user_id=user.id,
+ target_type='user',
+ target_id=user.id,
+ details={'source': 'cli', 'ttl_minutes': int(BREAKGLASS_TTL.total_seconds() // 60)},
+ )
+ except Exception: # noqa: BLE001 - auditing must never block break-glass access
+ pass
+
+ return token, user
+
+
+class ApiClient:
+ """Minimal JSON client for the local panel API."""
+
+ def __init__(self, token=None, port=None, session=None, timeout=DEFAULT_TIMEOUT):
+ import requests
+
+ self.base = base_url(port)
+ self.token = token
+ self.timeout = timeout
+ self.session = session or requests.Session()
+
+ def _headers(self):
+ headers = {'Accept': 'application/json'}
+ if self.token:
+ headers['Authorization'] = f'Bearer {self.token}'
+ return headers
+
+ def request(self, method, path, json_body=None):
+ """Issue a request; returns parsed JSON. Raises CliApiError on failure."""
+ import requests
+
+ url = self.base + path
+ try:
+ resp = self.session.request(
+ method, url, json=json_body, headers=self._headers(), timeout=self.timeout
+ )
+ except requests.exceptions.ConnectionError:
+ raise CliApiError(
+ 'Could not reach the panel API at '
+ f'{self.base} — panel not running? Try: systemctl status serverkit'
+ )
+ except requests.exceptions.Timeout:
+ raise CliApiError(f'Panel API timed out after {self.timeout}s ({url}).')
+ except requests.exceptions.RequestException as exc:
+ raise CliApiError(f'Panel API request failed: {exc}')
+
+ try:
+ data = resp.json()
+ except ValueError:
+ data = {}
+
+ if resp.status_code >= 400:
+ message = data.get('error') or data.get('message') or f'HTTP {resp.status_code}'
+ raise CliApiError(f'{message} ({method} {path})')
+ return data
+
+ def get(self, path):
+ return self.request('GET', path)
+
+ def post(self, path, json_body=None):
+ return self.request('POST', path, json_body=json_body)
diff --git a/backend/app/services/support_bundle_service.py b/backend/app/services/support_bundle_service.py
new file mode 100644
index 00000000..323784ab
--- /dev/null
+++ b/backend/app/services/support_bundle_service.py
@@ -0,0 +1,236 @@
+"""Diagnostic support bundle: gather panel state into a shareable zip.
+
+Everything collected here is meant to leave the box (attached to a bug report),
+so the collectors are shape-over-content by design:
+
+* settings are exported as **keys + declared types only** — never values; keys
+ in ``SettingsService.SECRET_KEYS`` are additionally flagged as secrets.
+* every piece of free text (logs, job errors, doctor details) passes through
+ ``_scrub()`` which redacts anything that looks like a token / password /
+ secret / key assignment or a bearer header.
+
+Encryption: ``pyzipper`` is NOT in requirements.txt and we deliberately add no
+new dependency, so bundles are plain ``zipfile`` zips. When a passphrase is
+requested we record the limitation in the bundle README and advise encrypting
+with the operator's own tooling (e.g. ``gpg -c serverkit-support-*.zip``).
+"""
+import json
+import logging
+import os
+import platform
+import re
+import sys
+import tempfile
+import zipfile
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+LOG_TAIL_LINES = 200
+RECENT_JOB_FAILURES = 20
+
+# Candidate panel log files, best-effort — the systemd deployment logs to the
+# journal (no file), so absence is normal.
+LOG_FILE_CANDIDATES = (
+ os.environ.get('SERVERKIT_LOG_FILE') or '',
+ '/var/log/serverkit/serverkit.log',
+ '/var/log/serverkit.log',
+)
+
+# key = value / "key": "value" pairs whose key smells secret-ish.
+_SECRETY_KEY = r'[\w.-]*(?:token|secret|passw(?:or)?d|api[_-]?key|private[_-]?key|access[_-]?key|credential|authorization)[\w.-]*'
+_ASSIGNMENT_RE = re.compile(
+ r'(?i)(["\']?' + _SECRETY_KEY + r'["\']?\s*[:=]\s*)(["\']?)([^\s"\',;}]+)'
+)
+_BEARER_RE = re.compile(r'(?i)\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}')
+# Standalone JWTs (three dot-separated base64url segments).
+_JWT_RE = re.compile(r'\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b')
+
+
+def _scrub(text):
+ """Redact secret-looking material from free text. Idempotent."""
+ if not text:
+ return text
+ if not isinstance(text, str):
+ text = str(text)
+ # Order matters: catch "Bearer <token>" / bare JWTs before the assignment
+ # pattern, so "Authorization: Bearer x" never leaves the raw token behind.
+ text = _JWT_RE.sub('[REDACTED-JWT]', text)
+ text = _BEARER_RE.sub(lambda m: f'{m.group(1)} [REDACTED]', text)
+ text = _ASSIGNMENT_RE.sub(lambda m: f'{m.group(1)}{m.group(2)}[REDACTED]', text)
+ return text
+
+
+def _safe(section_name, fn, default=None):
+ """Run a collector; a broken collector must never sink the whole bundle."""
+ try:
+ return fn()
+ except Exception as exc: # noqa: BLE001 - diagnostics are best-effort
+ logger.warning(f'support bundle: {section_name} collector failed: {exc}')
+ return {'error': f'collector failed: {exc.__class__.__name__}'} if default is None else default
+
+
+def _collect_meta():
+ from app.utils.version import get_panel_version, get_install_dir
+ return {
+ 'generated_at': datetime.utcnow().isoformat() + 'Z',
+ 'panel_version': get_panel_version(),
+ 'install_dir': get_install_dir(),
+ 'python_version': sys.version,
+ 'platform': platform.platform(),
+ 'os_name': os.name,
+ }
+
+
+def _collect_db():
+ from app import db
+ info = {'engine': db.engine.url.get_backend_name()}
+ try:
+ from app.services.migration_service import MigrationService
+ status = MigrationService.get_status()
+ info['migration_current'] = status.get('current_revision')
+ info['migration_head'] = status.get('head_revision')
+ info['migration_pending'] = status.get('pending_count')
+ except Exception as exc: # noqa: BLE001
+ info['migration_error'] = exc.__class__.__name__
+ return info
+
+
+def _collect_counts():
+ from app.models import Application, Domain, Server, User
+ from app.jobs.models import Job
+ return {
+ 'applications': Application.query.count(),
+ 'domains': Domain.query.count(),
+ 'servers': Server.query.count(),
+ 'users': User.query.count(),
+ 'jobs': Job.query.count(),
+ }
+
+
+def _collect_services():
+ if os.name == 'nt':
+ return {'skipped': 'service states are Linux-only'}
+ from app.services.process_service import ProcessService
+ return {'services': ProcessService.get_services_status()}
+
+
+def _collect_settings_shapes():
+ """Setting keys + declared types ONLY. Values are never exported; secret
+ keys are only reported as set/empty."""
+ from app.models import SystemSettings
+ from app.services.settings_service import SettingsService
+
+ shapes = []
+ for row in SystemSettings.query.order_by(SystemSettings.key.asc()).all():
+ is_secret = row.key in SettingsService.SECRET_KEYS
+ shapes.append({
+ 'key': row.key,
+ 'value_type': 'secret' if is_secret else (row.value_type or 'string'),
+ 'is_set': bool(row.value),
+ })
+ return {'settings': shapes}
+
+
+def _collect_job_failures():
+ from app.jobs.models import Job
+ rows = (
+ Job.query
+ .filter_by(status=Job.STATUS_FAILED)
+ .order_by(Job.created_at.desc())
+ .limit(RECENT_JOB_FAILURES)
+ .all()
+ )
+ failures = []
+ for job in rows:
+ failures.append({
+ 'id': job.id,
+ 'kind': job.kind,
+ 'attempts': job.attempts,
+ 'created_at': job.created_at.isoformat() if job.created_at else None,
+ 'completed_at': job.completed_at.isoformat() if job.completed_at else None,
+ 'error_message': _scrub(job.error_message or ''),
+ })
+ return {'recent_failures': failures}
+
+
+def _collect_doctor():
+ """Last doctor report, if the doctor service (built separately) exposes one."""
+ try:
+ from app.services import doctor_service
+ except Exception: # noqa: BLE001 - module may not exist yet
+ return {'skipped': 'doctor service not available'}
+ for attr in ('get_last_report', 'last_report'):
+ candidate = getattr(doctor_service, attr, None)
+ if candidate is None:
+ continue
+ try:
+ report = candidate() if callable(candidate) else candidate
+ return {'report': json.loads(_scrub(json.dumps(report, default=str)))}
+ except Exception as exc: # noqa: BLE001
+ return {'error': f'doctor report unavailable: {exc.__class__.__name__}'}
+ return {'skipped': 'doctor service exposes no last report'}
+
+
+def _collect_log_tail():
+ for candidate in LOG_FILE_CANDIDATES:
+ if not candidate or not os.path.isfile(candidate):
+ continue
+ try:
+ with open(candidate, 'r', encoding='utf-8', errors='replace') as fh:
+ lines = fh.readlines()[-LOG_TAIL_LINES:]
+ return f'# source: {candidate}\n' + _scrub(''.join(lines))
+ except OSError:
+ continue
+ return '# no panel log file found (systemd deployments log to the journal)\n'
+
+
+def build(out_path=None, passphrase=None):
+ """Build the support bundle zip. Returns the absolute path to the zip.
+
+ Must run inside an app context. ``passphrase`` is accepted for forward
+ compatibility but zip encryption is unavailable without pyzipper (not a
+ dependency) — the limitation is recorded in the bundle README.
+ """
+ stamp = datetime.utcnow().strftime('%Y%m%d-%H%M%S')
+ if not out_path:
+ out_path = os.path.join(tempfile.gettempdir(), f'serverkit-support-{stamp}.zip')
+ out_path = os.path.abspath(out_path)
+ os.makedirs(os.path.dirname(out_path) or '.', exist_ok=True)
+
+ sections = {
+ 'meta.json': _safe('meta', _collect_meta),
+ 'db.json': _safe('db', _collect_db),
+ 'counts.json': _safe('counts', _collect_counts),
+ 'services.json': _safe('services', _collect_services),
+ 'settings_shapes.json': _safe('settings_shapes', _collect_settings_shapes),
+ 'jobs.json': _safe('jobs', _collect_job_failures),
+ 'doctor.json': _safe('doctor', _collect_doctor),
+ }
+ log_tail = _safe('log_tail', _collect_log_tail, default='# log collection failed\n')
+
+ readme_lines = [
+ 'ServerKit support bundle',
+ f'Generated: {sections["meta.json"].get("generated_at", "unknown")}',
+ '',
+ 'Contents are diagnostic shapes only: setting VALUES are never included,',
+ 'and all collected text is scrubbed for token/password/secret/key material.',
+ ]
+ if passphrase:
+ readme_lines += [
+ '',
+ 'NOTE: a passphrase was requested, but built-in zip encryption requires',
+ 'pyzipper, which is not a ServerKit dependency. This bundle is NOT',
+ 'encrypted — encrypt it yourself before sharing, e.g.:',
+ ' gpg -c ' + os.path.basename(out_path),
+ ]
+ logger.warning('support bundle: passphrase requested but pyzipper is not installed; wrote plain zip')
+
+ with zipfile.ZipFile(out_path, 'w', compression=zipfile.ZIP_DEFLATED) as zf:
+ zf.writestr('README.txt', '\n'.join(readme_lines) + '\n')
+ for name, payload in sections.items():
+ serialized = json.dumps(payload, indent=2, default=str)
+ zf.writestr(name, _scrub(serialized))
+ zf.writestr('log_tail.txt', log_tail)
+
+ return out_path
diff --git a/backend/cli.py b/backend/cli.py
index 6c667541..885433e3 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -747,5 +747,307 @@ def deployment_status(job_id, logs):
click.echo('')
+# ─────────────────────────────────────────────────────────────────────────────
+# API-backed commands: talk to the running panel over the local HTTP API using
+# a short-lived break-glass admin token (root/shell on the box already implies
+# full control; every mint is audit-logged as 'cli.breakglass').
+# ─────────────────────────────────────────────────────────────────────────────
+
+STATUS_SYMBOLS = {
+ 'ok': ('✓', 'green'),
+ 'pass': ('✓', 'green'),
+ 'healthy': ('✓', 'green'),
+ 'warn': ('!', 'yellow'),
+ 'warning': ('!', 'yellow'),
+}
+
+
+def _api_client(with_token=True):
+ """Build an ApiClient for the local panel, minting a break-glass token."""
+ from app.services.cli_api_client import ApiClient, mint_breakglass_token
+
+ token = None
+ if with_token:
+ token, _user = mint_breakglass_token()
+ return ApiClient(token=token)
+
+
+def _fail(message):
+ click.echo(click.style(f'Error: {message}', fg='red'), err=True)
+ sys.exit(1)
+
+
+def _echo_table(headers, rows):
+ """Plain fixed-width table via click.echo (no extra deps)."""
+ rows = [[('' if cell is None else str(cell)) for cell in row] for row in rows]
+ widths = [len(h) for h in headers]
+ for row in rows:
+ for i, cell in enumerate(row):
+ widths[i] = max(widths[i], len(cell))
+ fmt = ' '.join(f'{{:<{w}}}' for w in widths)
+ click.echo(fmt.format(*headers))
+ click.echo('-' * (sum(widths) + 2 * (len(widths) - 1)))
+ for row in rows:
+ click.echo(fmt.format(*row))
+
+
+def status():
+ """Show panel health and version."""
+ from app.utils.version import get_panel_version
+ from app.services.cli_api_client import CliApiError
+
+ version = get_panel_version()
+ try:
+ # /system/health is unauthenticated by design.
+ health = _api_client(with_token=False).get('/system/health')
+ except CliApiError as exc:
+ _fail(str(exc))
+
+ rows = [
+ ('Panel version', version),
+ ('API status', health.get('status', 'unknown')),
+ ('Service', health.get('service', '-')),
+ ('Canonical domain', health.get('canonical_domain') or '-'),
+ ('HTTPS enabled', 'yes' if health.get('canonical_https_enabled') else 'no'),
+ ('Encryption configured', 'yes' if health.get('encryption_configured') else 'no'),
+ ]
+ _echo_table(['Field', 'Value'], rows)
+
+
+def services():
+ """Inspect and control system services via the panel API."""
+
+
+def services_list():
+ """List monitored system services."""
+ from app.services.cli_api_client import CliApiError
+
+ try:
+ data = _api_client().get('/processes/services')
+ except CliApiError as exc:
+ _fail(str(exc))
+
+ entries = data.get('services', [])
+ if not entries:
+ click.echo('No services reported.')
+ return
+ rows = [(s.get('name', '-'), s.get('status', '-'), s.get('pid', '-')) for s in entries]
+ _echo_table(['Service', 'Status', 'PID'], rows)
+
+
+def services_restart(name):
+ """Restart a system service."""
+ from app.services.cli_api_client import CliApiError
+
+ try:
+ result = _api_client().post(f'/processes/services/{name}', {'action': 'restart'})
+ except CliApiError as exc:
+ _fail(str(exc))
+ click.echo(click.style(result.get('message', f'Service "{name}" restarted.'), fg='green'))
+
+
+def apps():
+ """Inspect applications via the panel API."""
+
+
+def apps_list():
+ """List applications known to the panel."""
+ from app.services.cli_api_client import CliApiError
+
+ try:
+ data = _api_client().get('/apps')
+ except CliApiError as exc:
+ _fail(str(exc))
+
+ entries = data.get('apps', [])
+ if not entries:
+ click.echo('No applications found.')
+ return
+ rows = [(a.get('name', '-'), a.get('app_type', '-'), a.get('status', '-')) for a in entries]
+ _echo_table(['Name', 'Type', 'Status'], rows)
+
+
[email protected]('login-url')
[email protected]('--ttl', default=15, show_default=True, help='Link lifetime in minutes')
[email protected]('--ip', default=None, help='Bind the link to this client IP address')
[email protected]('--user', 'user_ref', default=None, help='Username or email (default: first active admin)')
+def login_url(ttl, ip, user_ref):
+ """Mint a one-time login link for the panel."""
+ app = create_app()
+ with app.app_context():
+ from app.services import login_link_service
+ from app.services.cli_api_client import find_breakglass_admin, resolve_port
+
+ if user_ref:
+ user = User.query.filter(
+ (User.username == user_ref) | (User.email == user_ref)
+ ).first()
+ if not user:
+ _fail(f'User "{user_ref}" not found.')
+ if not user.is_active:
+ _fail(f'User "{user.username}" is not active.')
+ else:
+ user = find_breakglass_admin()
+ if not user:
+ _fail('No active admin user found — create one with "serverkit create-admin".')
+
+ token, link = login_link_service.mint(user.id, ttl_minutes=ttl, bound_ip=ip)
+
+ origin = None
+ try:
+ from app.services.site_domain_service import SiteDomainService
+ origin = SiteDomainService.panel_origin()
+ except Exception:
+ origin = None
+ if not origin:
+ origin = f'http://localhost:{resolve_port()}'
+
+ click.echo(f'{origin}/login?link={token}')
+ click.echo(
+ f'Single-use link for "{user.username}", expires {link.expires_at.isoformat()}Z'
+ + (f', bound to {ip}' if ip else ''),
+ err=True,
+ )
+
+
[email protected]('--repair', 'do_repair', is_flag=True, help='Repair all repairable findings')
[email protected]('--yes', is_flag=True, help='Skip the repair confirmation prompt')
+def doctor(do_repair, yes):
+ """Run panel diagnostics (and optionally repair findings)."""
+ from app.services.cli_api_client import CliApiError
+
+ try:
+ client = _api_client()
+ data = client.post('/doctor/run')
+ except CliApiError as exc:
+ _fail(str(exc))
+
+ checks = (data.get('report') or {}).get('checks', [])
+ if not checks:
+ click.echo('Doctor reported no checks.')
+ return
+
+ rows = []
+ for check in checks:
+ raw_status = str(check.get('status', '')).lower()
+ symbol, color = STATUS_SYMBOLS.get(raw_status, ('✗', 'red'))
+ rows.append((
+ click.style(symbol, fg=color),
+ check.get('title') or check.get('key', '-'),
+ raw_status or '-',
+ check.get('detail') or '',
+ ))
+ _echo_table(['', 'Check', 'Status', 'Detail'], rows)
+
+ if not do_repair:
+ return
+
+ repairable = [
+ c for c in checks
+ if c.get('repairable') and str(c.get('status', '')).lower() not in ('ok', 'pass', 'healthy')
+ ]
+ if not repairable:
+ click.echo('Nothing repairable.')
+ return
+
+ click.echo(f'\n{len(repairable)} repairable finding(s): '
+ + ', '.join(c.get('key', '?') for c in repairable))
+ if not yes and not click.confirm('Repair all of these?', default=False):
+ click.echo('Aborted.')
+ return
+
+ # The repair endpoint takes the repair_ref dicts the report carries
+ # ({'kind': 'drift', 'type', 'id'} / {'kind': 'service', 'name'}).
+ items = [c.get('repair_ref') for c in repairable if c.get('repair_ref')]
+ if not items:
+ click.echo('Nothing repairable.')
+ return
+ try:
+ result = client.post('/doctor/repair', {'items': items})
+ except CliApiError as exc:
+ _fail(str(exc))
+ results = result.get('results', [])
+ ok = sum(1 for r in results if r.get('success'))
+ for r in results:
+ mark = click.style('OK', fg='green') if r.get('success') else click.style('FAIL', fg='red')
+ detail = r.get('error') or ''
+ click.echo(f" [{mark}] {r.get('item')} {detail}".rstrip())
+ click.echo(click.style(f'{ok}/{len(results)} repairs succeeded.',
+ fg='green' if ok == len(results) else 'yellow'))
+
+
[email protected]('drift_type')
[email protected]('drift_id')
+def repair(drift_type, drift_id):
+ """Repair a single drift finding (e.g. serverkit repair nginx <id>)."""
+ from app.services.cli_api_client import CliApiError
+
+ try:
+ result = _api_client().post(
+ f'/doctor/drift/{drift_type}/{drift_id}/repair', {'confirm': True}
+ )
+ except CliApiError as exc:
+ _fail(str(exc))
+ click.echo(click.style(result.get('message', 'Repair triggered.'), fg='green'))
+
+
[email protected]('--yes', is_flag=True, help='Skip the confirmation prompt')
+def update(yes):
+ """Update ServerKit via the bundled update script (Linux only)."""
+ import subprocess
+
+ if os.name == 'nt':
+ _fail('serverkit update is Linux-only — run scripts/update.sh on the server itself.')
+
+ from app.utils.version import get_install_dir
+ candidates = [
+ os.path.join(get_install_dir(), 'scripts', 'update.sh'),
+ str(Path(__file__).resolve().parent.parent / 'scripts' / 'update.sh'),
+ '/opt/serverkit/scripts/update.sh',
+ ]
+ script = next((c for c in candidates if os.path.isfile(c)), None)
+ if not script:
+ _fail('update.sh not found (looked in: ' + ', '.join(candidates) + ')')
+
+ click.echo(f'This will run: bash {script}')
+ if not yes and not click.confirm('Update ServerKit now?', default=False):
+ click.echo('Aborted.')
+ return
+
+ # Inherit stdio so the operator sees the updater output live.
+ proc = subprocess.Popen(['bash', script])
+ sys.exit(proc.wait())
+
+
[email protected]('support-bundle')
[email protected]('--out', 'out_path', default=None, help='Output path for the zip')
[email protected]('--passphrase', default=None,
+ help='Requested bundle passphrase (see output: encryption needs external tooling)')
+def support_bundle(out_path, passphrase):
+ """Build a scrubbed diagnostic support bundle zip."""
+ app = create_app()
+ with app.app_context():
+ from app.services import support_bundle_service
+ path = support_bundle_service.build(out_path=out_path, passphrase=passphrase)
+
+ if passphrase:
+ click.echo(click.style(
+ 'Note: built-in zip encryption is unavailable (pyzipper not installed); '
+ 'the bundle is NOT encrypted. Encrypt before sharing, e.g. gpg -c ' + path,
+ fg='yellow',
+ ))
+ click.echo(click.style(f'Support bundle written: {path}', fg='green'))
+
+
if __name__ == '__main__':
cli()
diff --git a/backend/tests/test_cli_api.py b/backend/tests/test_cli_api.py
new file mode 100644
index 00000000..d39d6a3a
--- /dev/null
+++ b/backend/tests/test_cli_api.py
@@ -0,0 +1,242 @@
+"""Tests for the API-backed CLI verbs (#12/#13): break-glass token minting,
+login-url, doctor/repair against a stubbed client, and the update guard."""
+import os
+
+import pytest
+from click.testing import CliRunner
+
+import cli as serverkit_cli
+
+
+def _all_output(result):
+ """stdout + stderr regardless of the installed click version."""
+ out = result.output
+ try:
+ out += result.stderr
+ except (ValueError, AttributeError):
+ pass
+ return out
+
+
+def _make_admin(username='cliadmin', email='[email protected]', role='admin', active=True):
+ from app import db
+ from app.models import User
+
+ user = User(email=email, username=username, role=role, is_active=active)
+ user.set_password('cli-test-pass')
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+# ── break-glass token ────────────────────────────────────────────────────────
+
+def test_breakglass_token_mints_and_is_accepted(app, client):
+ admin = _make_admin()
+ from app.services.cli_api_client import mint_breakglass_token
+
+ token, minted_user = mint_breakglass_token()
+ assert minted_user.id == admin.id
+
+ resp = client.get('/api/v1/system/version',
+ headers={'Authorization': f'Bearer {token}'})
+ assert resp.status_code == 200
+ assert 'version' in resp.get_json()
+
+ from app.models import AuditLog
+ rows = AuditLog.query.filter_by(action='cli.breakglass').all()
+ assert len(rows) == 1
+ assert rows[0].user_id == admin.id
+
+
+def test_breakglass_requires_an_active_admin(app):
+ from app.services.cli_api_client import CliApiError, mint_breakglass_token
+
+ _make_admin(username='inactive', email='[email protected]', active=False)
+ _make_admin(username='pleb', email='[email protected]', role='user')
+ with pytest.raises(CliApiError):
+ mint_breakglass_token()
+
+
+# ── login-url ────────────────────────────────────────────────────────────────
+
+def test_login_url_prints_a_redeemable_link(app, client):
+ _make_admin()
+ runner = CliRunner()
+ result = runner.invoke(serverkit_cli.cli, ['login-url', '--ttl', '5'])
+ assert result.exit_code == 0, _all_output(result)
+
+ url_lines = [l for l in result.output.splitlines() if '/login?link=' in l]
+ assert url_lines, _all_output(result)
+ token = url_lines[0].split('link=', 1)[1].strip()
+ assert token
+
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['access_token']
+ assert body['user']['username'] == 'cliadmin'
+
+ # single use: a second redeem must fail
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 401
+
+
+def test_login_url_unknown_user_fails(app):
+ _make_admin()
+ runner = CliRunner()
+ result = runner.invoke(serverkit_cli.cli, ['login-url', '--user', 'nobody@nowhere'])
+ assert result.exit_code == 1
+ assert 'not found' in _all_output(result)
+
+
+# ── stubbed-API verbs ────────────────────────────────────────────────────────
+
+class FakeClient:
+ def __init__(self, responses):
+ self.responses = responses
+ self.calls = []
+
+ def get(self, path):
+ self.calls.append(('GET', path, None))
+ return self.responses[path]
+
+ def post(self, path, json_body=None):
+ self.calls.append(('POST', path, json_body))
+ return self.responses[path]
+
+
+def fake_api(monkeypatch):
+ def _install(responses):
+ fake = FakeClient(responses)
+ monkeypatch.setattr(serverkit_cli, '_api_client', lambda with_token=True: fake)
+ return fake
+ return _install
+
+
+def test_doctor_renders_report_table(fake_api):
+ fake_api({
+ '/doctor/run': {'report': {'checks': [
+ {'key': 'nginx', 'title': 'Nginx config', 'status': 'ok',
+ 'detail': '', 'repairable': False},
+ {'key': 'ssl', 'title': 'SSL cert', 'status': 'fail',
+ 'detail': 'certificate expired', 'repairable': True},
+ ]}},
+ })
+ result = CliRunner().invoke(serverkit_cli.cli, ['doctor'])
+ assert result.exit_code == 0, _all_output(result)
+ assert 'Nginx config' in result.output
+ assert 'SSL cert' in result.output
+ assert 'certificate expired' in result.output
+
+
+def test_doctor_repair_posts_all_repairable_items(fake_api):
+ ref_a = {'kind': 'drift', 'type': 'nginx_vhost', 'id': 'a'}
+ ref_b = {'kind': 'service', 'name': 'nginx'}
+ fake = fake_api({
+ '/doctor/run': {'report': {'checks': [
+ {'key': 'ok-check', 'title': 'Fine', 'status': 'ok',
+ 'detail': '', 'repairable': True,
+ 'repair_ref': {'kind': 'service', 'name': 'docker'}},
+ {'key': 'broken-a', 'title': 'Broken A', 'status': 'fail',
+ 'detail': '', 'repairable': True, 'repair_ref': ref_a},
+ {'key': 'broken-b', 'title': 'Broken B', 'status': 'warn',
+ 'detail': '', 'repairable': True, 'repair_ref': ref_b},
+ {'key': 'manual', 'title': 'Manual only', 'status': 'fail',
+ 'detail': '', 'repairable': False},
+ ]}},
+ '/doctor/repair': {'results': [
+ {'item': ref_a, 'success': True},
+ {'item': ref_b, 'success': True},
+ ]},
+ })
+ result = CliRunner().invoke(serverkit_cli.cli, ['doctor', '--repair', '--yes'])
+ assert result.exit_code == 0, _all_output(result)
+
+ repair_calls = [c for c in fake.calls if c[1] == '/doctor/repair']
+ assert repair_calls == [('POST', '/doctor/repair', {'items': [ref_a, ref_b]})]
+ assert '2/2 repairs succeeded' in result.output
+
+
+def test_repair_verb_posts_confirmed_drift_repair(fake_api):
+ fake = fake_api({
+ '/doctor/drift/nginx/12/repair': {'message': 'Repaired nginx 12'},
+ })
+ result = CliRunner().invoke(serverkit_cli.cli, ['repair', 'nginx', '12'])
+ assert result.exit_code == 0, _all_output(result)
+ assert fake.calls == [('POST', '/doctor/drift/nginx/12/repair', {'confirm': True})]
+ assert 'Repaired nginx 12' in result.output
+
+
+def test_services_list_and_restart(fake_api):
+ fake = fake_api({
+ '/processes/services': {'services': [
+ {'name': 'nginx', 'status': 'running', 'pid': 123},
+ {'name': 'mysql', 'status': 'stopped', 'pid': None},
+ ]},
+ '/processes/services/nginx': {'success': True, 'message': 'nginx restarted'},
+ })
+ result = CliRunner().invoke(serverkit_cli.cli, ['services', 'list'])
+ assert result.exit_code == 0, _all_output(result)
+ assert 'nginx' in result.output and 'stopped' in result.output
+
+ result = CliRunner().invoke(serverkit_cli.cli, ['services', 'restart', 'nginx'])
+ assert result.exit_code == 0, _all_output(result)
+ assert ('POST', '/processes/services/nginx', {'action': 'restart'}) in fake.calls
+
+
+def test_apps_list(fake_api):
+ fake_api({
+ '/apps': {'apps': [
+ {'name': 'blog', 'app_type': 'wordpress', 'status': 'running'},
+ ]},
+ })
+ result = CliRunner().invoke(serverkit_cli.cli, ['apps', 'list'])
+ assert result.exit_code == 0, _all_output(result)
+ assert 'blog' in result.output and 'wordpress' in result.output
+
+
+# ── update guard ─────────────────────────────────────────────────────────────
+
+def test_update_refuses_on_windows(monkeypatch):
+ monkeypatch.setattr(os, 'name', 'nt')
+ result = CliRunner().invoke(serverkit_cli.cli, ['update', '--yes'])
+ assert result.exit_code == 1
+ assert 'Linux-only' in _all_output(result)
+
+
+# ── ApiClient error surface ──────────────────────────────────────────────────
+
+def test_api_client_connection_refused_is_helpful():
+ import requests
+
+ class BoomSession:
+ def request(self, *args, **kwargs):
+ raise requests.exceptions.ConnectionError('boom')
+
+ from app.services.cli_api_client import ApiClient, CliApiError
+
+ client = ApiClient(token='t', session=BoomSession())
+ with pytest.raises(CliApiError) as excinfo:
+ client.get('/system/health')
+ assert 'systemctl status serverkit' in str(excinfo.value)
+
+
+def test_api_client_surfaces_json_errors():
+ class Resp:
+ status_code = 403
+
+ def json(self):
+ return {'error': 'Admin access required'}
+
+ class Session:
+ def request(self, *args, **kwargs):
+ return Resp()
+
+ from app.services.cli_api_client import ApiClient, CliApiError
+
+ client = ApiClient(token='t', session=Session())
+ with pytest.raises(CliApiError) as excinfo:
+ client.post('/doctor/run')
+ assert 'Admin access required' in str(excinfo.value)
diff --git a/backend/tests/test_support_bundle.py b/backend/tests/test_support_bundle.py
new file mode 100644
index 00000000..e9416308
--- /dev/null
+++ b/backend/tests/test_support_bundle.py
@@ -0,0 +1,171 @@
+"""Tests for the diagnostic support bundle (#25): build, secret scrubbing,
+and the admin-only download API."""
+import io
+import json
+import zipfile
+
+import pytest
+
+from app.services import support_bundle_service
+
+
+EXPECTED_MEMBERS = {
+ 'README.txt', 'meta.json', 'db.json', 'counts.json', 'services.json',
+ 'settings_shapes.json', 'jobs.json', 'doctor.json', 'log_tail.txt',
+}
+
+
+def _read_all(zip_path_or_bytes):
+ """{member: text} for every file in the zip."""
+ if isinstance(zip_path_or_bytes, bytes):
+ zf = zipfile.ZipFile(io.BytesIO(zip_path_or_bytes))
+ else:
+ zf = zipfile.ZipFile(zip_path_or_bytes)
+ with zf:
+ return {name: zf.read(name).decode('utf-8') for name in zf.namelist()}
+
+
+def _seed_secrets(tmp_path, monkeypatch):
+ """Seed a SECRET_KEYS setting, a leaky job failure, and a leaky log file."""
+ from app import db
+ from app.models import SystemSettings
+ from app.jobs.models import Job
+ from app.services.settings_service import SettingsService
+
+ secret_key = 'sso_google_client_secret'
+ assert secret_key in SettingsService.SECRET_KEYS
+ SystemSettings.set(secret_key, 'supersecretvalue123')
+ SystemSettings.set('canonical_domain', 'panel.example.com')
+
+ job = Job(kind='backup.policy.run', status=Job.STATUS_FAILED,
+ error_message='upload failed: token=abc123LEAKYTOKEN for bucket x')
+ db.session.add(job)
+ db.session.commit()
+
+ log_file = tmp_path / 'panel.log'
+ log_file.write_text(
+ 'INFO booting\n'
+ 'DEBUG auth header Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.c2lnbmF0dXJlLXNlZ21lbnQ\n'
+ 'ERROR db password=hunter2 rejected\n',
+ encoding='utf-8',
+ )
+ monkeypatch.setattr(support_bundle_service, 'LOG_FILE_CANDIDATES', (str(log_file),))
+
+
+def test_bundle_builds_with_expected_members(app, tmp_path):
+ out = tmp_path / 'bundle.zip'
+ path = support_bundle_service.build(out_path=str(out))
+ assert path == str(out.resolve()) or path == str(out)
+
+ members = _read_all(str(out))
+ assert EXPECTED_MEMBERS <= set(members)
+
+ meta = json.loads(members['meta.json'])
+ assert meta['panel_version']
+ assert meta['python_version']
+
+ dbinfo = json.loads(members['db.json'])
+ assert dbinfo['engine'] == 'sqlite'
+
+ counts = json.loads(members['counts.json'])
+ for key in ('applications', 'domains', 'servers', 'users', 'jobs'):
+ assert isinstance(counts[key], int)
+
+
+def test_bundle_scrubs_secrets(app, tmp_path, monkeypatch):
+ _seed_secrets(tmp_path, monkeypatch)
+
+ out = tmp_path / 'bundle.zip'
+ support_bundle_service.build(out_path=str(out))
+ members = _read_all(str(out))
+ everything = '\n'.join(members.values())
+
+ # Secret setting VALUE must never appear; the key may (shape-only export).
+ assert 'supersecretvalue123' not in everything
+ # Leaky job error and log lines must be redacted.
+ assert 'abc123LEAKYTOKEN' not in everything
+ assert 'hunter2' not in everything
+ assert 'eyJhbGciOiJIUzI1NiJ9' not in everything
+ assert '[REDACTED' in everything
+
+ shapes = json.loads(members['settings_shapes.json'])['settings']
+ by_key = {s['key']: s for s in shapes}
+ assert by_key['sso_google_client_secret']['value_type'] == 'secret'
+ assert by_key['sso_google_client_secret']['is_set'] is True
+ assert 'value' not in by_key['canonical_domain']
+
+ jobs = json.loads(members['jobs.json'])['recent_failures']
+ assert len(jobs) == 1
+ assert 'token' in jobs[0]['error_message'] # key survives
+ assert 'abc123LEAKYTOKEN' not in jobs[0]['error_message']
+
+
+def test_scrub_helper_patterns():
+ scrub = support_bundle_service._scrub
+ assert 'hunter2' not in scrub('password=hunter2')
+ assert 'sk-live-123' not in scrub('"api_key": "sk-live-123"')
+ assert 'topsecret' not in scrub("JWT_SECRET_KEY: topsecret")
+ assert 'Bearer abcdefgh12345678' not in scrub('Authorization: Bearer abcdefgh12345678')
+ # plain text passes through
+ assert scrub('nginx reloaded ok') == 'nginx reloaded ok'
+
+
+def test_passphrase_is_documented_not_silently_ignored(app, tmp_path):
+ out = tmp_path / 'bundle.zip'
+ support_bundle_service.build(out_path=str(out), passphrase='hunter2')
+ members = _read_all(str(out))
+ assert 'NOT' in members['README.txt']
+ assert 'gpg' in members['README.txt']
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def bundle_app(app):
+ """conftest app + the support-bundle blueprint (registered in
+ app/__init__.py in the real app; that file is owned by another change)."""
+ from app.api.support_bundle import support_bundle_bp
+ if 'support_bundle' not in app.blueprints:
+ app.register_blueprint(support_bundle_bp, url_prefix='/api/v1/support-bundle')
+ return app
+
+
+def _token_for(role):
+ from app import db
+ from app.models import User
+ from flask_jwt_extended import create_access_token
+
+ user = User(email=f'{role}@test.local', username=f'bundle-{role}',
+ role=role, is_active=True)
+ user.set_password('x')
+ db.session.add(user)
+ db.session.commit()
+ return create_access_token(identity=user.id)
+
+
+def test_api_download_requires_auth(bundle_app):
+ client = bundle_app.test_client()
+ resp = client.post('/api/v1/support-bundle')
+ assert resp.status_code == 401
+
+
+def test_api_download_rejects_non_admin(bundle_app):
+ client = bundle_app.test_client()
+ token = _token_for('user')
+ resp = client.post('/api/v1/support-bundle',
+ headers={'Authorization': f'Bearer {token}'})
+ assert resp.status_code == 403
+ assert resp.get_json()['error']
+
+
+def test_api_download_returns_zip_for_admin(bundle_app):
+ client = bundle_app.test_client()
+ token = _token_for('admin')
+ resp = client.post('/api/v1/support-bundle',
+ headers={'Authorization': f'Bearer {token}'})
+ assert resp.status_code == 200
+ assert resp.mimetype == 'application/zip'
+ assert 'serverkit-support-' in resp.headers.get('Content-Disposition', '')
+
+ members = _read_all(resp.data)
+ assert EXPECTED_MEMBERS <= set(members)