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(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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_pathdiff --git a/backend/cli.py b/backend/cli.pyindex 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."""++[email protected]('list')+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)++[email protected]('restart')[email protected]('name')+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."""++[email protected]('list')+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.pynew file mode 100644index 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.pynew file mode 100644index 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)