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(extensions): observe permission use, and say which permissions we can't see
Juan Denisbb20db70db9a
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.pyindex 4383fd22..9c48b4ad 100644--- a/backend/app/api/plugins.py+++ b/backend/app/api/plugins.py@@ -536,6 +536,34 @@ def get_manifest_spec():})+@plugins_bp.route('/<int:plugin_id>/permissions', methods=['GET'])+@jwt_required()+def get_plugin_permissions(plugin_id):+ """Declared vs actually-observed permission use for one extension (plan 55).++ Admin-only: it describes what a piece of third-party code has been reaching+ for, which is operator information.++ The response is deliberately explicit about its own blind spot. Only+ permissions whose every use must pass through the SDK capability gate are+ observable — today that is ``agent.command:<action>`` and nothing else.+ For the declaration-only capabilities (docker, shell, filesystem, network,+ db) the panel exposes no helper to gate, so an extension reaches the host+ module directly and no in-process check can see it. ``observable: false``+ on a row means "no evidence either way", never "unused".+ """+ user = get_current_user()+ if not user or not user.is_admin:+ return jsonify({'error': 'Admin access required'}), 403++ from app.services.plugin_service import get_plugin+ from app.plugins_sdk import permissions as perms+ plugin = get_plugin(plugin_id)+ if not plugin:+ return jsonify({'error': 'Plugin not found'}), 404+ return jsonify(perms.usage_report(plugin.slug))++@plugins_bp.route('/<int:plugin_id>/config', methods=['GET'])@jwt_required()def get_plugin_config(plugin_id):diff --git a/backend/app/plugins_sdk/permissions.py b/backend/app/plugins_sdk/permissions.pyindex 21c050df..42173bc2 100644--- a/backend/app/plugins_sdk/permissions.py+++ b/backend/app/plugins_sdk/permissions.py@@ -14,6 +14,8 @@ makes honest plugins verifiable and gives the host a single choke point to tightlater."""import logging+import threading+from datetime import datetimelogger = logging.getLogger(__name__)@@ -21,11 +23,139 @@ logger = logging.getLogger(__name__)# use the namespaced form ``agent.command:<action>`` and are matched verbatim.KNOWN_PERMISSIONS = {'docker', 'filesystem', 'shell', 'network', 'db'}+# Which declared permissions the panel can actually *observe* being used.+#+# This distinction is the whole honesty story (D2), so it is data rather than+# prose. A permission is observable only when every use of the capability has+# to pass through a gate this module owns. Today exactly one does:+# ``agent.command:<action>``, gated in ``plugins_sdk/agents_sdk.py`` — the SDK+# is the only way to run a command on an agent.+#+# The five KNOWN_PERMISSIONS are NOT observable. The SDK exposes no shell,+# docker, filesystem or network helper at all, and ``db`` is handed out as raw+# SQLAlchemy, so an extension that wants any of them imports the host module+# directly and no in-process gate ever sees it. Declaring them is a consent+# signal to the operator, not an enforced boundary — and the UI must not imply+# otherwise by showing "never used" for something it simply cannot watch.+OBSERVABLE_PREFIXES = ('agent.command:',)+++def is_observable(permission):+ """True when a use of *permission* necessarily passes through our gate."""+ return str(permission or '').startswith(OBSERVABLE_PREFIXES)+class PermissionDenied(PermissionError):"""Raised when a plugin uses a capability it did not declare."""+# ---------------------------------------------------------------------------+# Usage observation (plan 55 task 7)+#+# In-memory and per-process on purpose: this answers "what has this extension+# actually done since the panel started", which is a live-process question. It+# is deliberately not persisted — a durable claim would outlive the evidence and+# start reading like an audit trail, which this is not.+# ---------------------------------------------------------------------------+_observations = {}+_observations_lock = threading.Lock()+++def record_use(slug, capability, allowed=True):+ """Note that *slug* reached for *capability*; first use per process is logged.++ Called from the gate itself, so both the allowed and the denied paths are+ recorded — a denial is the more interesting of the two.+ """+ slug = str(slug or '')+ capability = str(capability or '')+ if not slug or not capability:+ return+ key = (slug, capability)+ with _observations_lock:+ entry = _observations.get(key)+ first = entry is None+ if first:+ entry = {'slug': slug, 'permission': capability, 'uses': 0,+ 'denied': 0, 'first_used_at': datetime.utcnow().isoformat(),+ 'last_used_at': None}+ _observations[key] = entry+ entry['uses'] += 1+ if not allowed:+ entry['denied'] += 1+ entry['last_used_at'] = datetime.utcnow().isoformat()+ if first:+ logger.info('extension=%s permission=%s first-use allowed=%s',+ slug, capability, allowed)+++def observed_permissions(slug):+ """Everything *slug* has reached for this process, newest field values."""+ with _observations_lock:+ return [dict(v) for k, v in _observations.items() if k[0] == str(slug or '')]+++def reset_observations():+ """Drop all recorded usage (tests)."""+ with _observations_lock:+ _observations.clear()+++def usage_report(slug):+ """Declared vs observed for one extension, honest about what it can see.++ Every declared permission gets a row. ``observable`` says whether absence+ of use means anything at all: for a declaration-only capability it does+ not, and the row says so instead of implying the extension is over-asking.+ Anything observed but never declared is reported too — it cannot happen+ through the gate, which refuses it, but a denial is exactly what an+ operator wants to see.+ """+ declared = sorted(declared_permissions(slug))+ observed = {o['permission']: o for o in observed_permissions(slug)}++ rows = []+ for perm in declared:+ seen = observed.get(perm)+ rows.append({+ 'permission': perm,+ 'declared': True,+ 'observable': is_observable(perm),+ 'used': bool(seen and seen['uses'] > seen['denied']),+ 'uses': seen['uses'] if seen else 0,+ 'first_used_at': seen['first_used_at'] if seen else None,+ 'last_used_at': seen['last_used_at'] if seen else None,+ })+ for perm, seen in sorted(observed.items()):+ if perm in declared:+ continue+ rows.append({+ 'permission': perm,+ 'declared': False,+ 'observable': is_observable(perm),+ 'used': False, # refused at the gate — it never happened+ 'uses': seen['uses'],+ 'denied': seen['denied'],+ 'first_used_at': seen['first_used_at'],+ 'last_used_at': seen['last_used_at'],+ })++ observable_declared = [r for r in rows if r['declared'] and r['observable']]+ return {+ 'slug': slug,+ 'permissions': rows,+ # Only meaningful for observable rows; stated separately so the UI does+ # not have to re-derive the caveat.+ 'unused_observable': sorted(r['permission'] for r in observable_declared+ if not r['used']),+ 'undeclared_attempts': sorted(r['permission'] for r in rows+ if not r['declared']),+ 'observable_count': len(observable_declared),+ 'declaration_only_count': len([r for r in rows+ if r['declared'] and not r['observable']]),+ }++def declared_permissions(slug):"""The set of permissions the installed plugin `slug` declared (empty if theplugin is unknown)."""@@ -45,8 +175,15 @@ def has(slug, capability):def require(slug, capability):- """Assert plugin `slug` declared `capability`, else raise PermissionDenied."""- if not has(slug, capability):+ """Assert plugin `slug` declared `capability`, else raise PermissionDenied.++ Every call through this gate is recorded — including the refusals, which+ are the ones worth surfacing — so the extension detail page can show what a+ plugin has actually reached for rather than only what it claimed.+ """+ allowed = has(slug, capability)+ record_use(slug, capability, allowed=allowed)+ if not allowed:raise PermissionDenied(f"Plugin '{slug}' has not declared the '{capability}' permission. "f"Add it to the plugin.json \"permissions\" array."diff --git a/backend/tests/test_extension_permission_observation.py b/backend/tests/test_extension_permission_observation.pynew file mode 100644index 00000000..611183fd--- /dev/null+++ b/backend/tests/test_extension_permission_observation.py@@ -0,0 +1,200 @@+"""Plan 55 task 7 — declared-vs-observed extension permissions, honestly.++The manifest's ``permissions`` array was declaration-only: the install dialog+showed it, and nothing ever compared it against what the extension actually+did. These tests pin both halves of the answer — the usage the gate can see,+and the much larger set it cannot.++That second half is the point. The SDK exposes no shell, docker, filesystem or+network helper, and hands out ``db`` as raw SQLAlchemy, so those declarations+are consent signals rather than enforced boundaries. A UI that showed them as+"never used" would be inventing evidence, so the report marks them+``observable: false`` instead.+"""+import pytest++from app.plugins_sdk import permissions as perms+++SLUG = 'demo-ext'+AGENT_PERM = 'agent.command:restart'++[email protected](autouse=True)+def _clean_observations():+ perms.reset_observations()+ yield+ perms.reset_observations()+++def installed(app):+ """An installed extension declaring one observable and one declaration-only+ permission."""+ from app import db+ from app.models.plugin import InstalledPlugin++ row = InstalledPlugin(+ slug=SLUG, name='Demo', display_name='Demo', version='1.0.0',+ status='active', manifest={'permissions': [AGENT_PERM, 'shell']},+ )+ db.session.add(row)+ db.session.commit()+ return row+++# --------------------------------------------------------------------------- #+# What the gate can see+# --------------------------------------------------------------------------- #+class TestObservation:++ def test_a_declared_use_is_recorded(self, app, installed):+ perms.require(SLUG, AGENT_PERM)+ report = perms.usage_report(SLUG)++ row = next(r for r in report['permissions'] if r['permission'] == AGENT_PERM)+ assert row['declared'] is True+ assert row['observable'] is True+ assert row['used'] is True+ assert row['uses'] == 1+ assert row['first_used_at']++ def test_repeated_use_counts_but_keeps_the_first_timestamp(self, app, installed):+ perms.require(SLUG, AGENT_PERM)+ first = perms.usage_report(SLUG)['permissions'][0]['first_used_at']+ perms.require(SLUG, AGENT_PERM)+ row = next(r for r in perms.usage_report(SLUG)['permissions']+ if r['permission'] == AGENT_PERM)++ assert row['uses'] == 2+ assert row['first_used_at'] == first++ def test_an_unused_observable_permission_is_reported_as_unused(self, app, installed):+ """Nothing was called — for an observable permission that absence IS+ evidence, and over-declaration is worth showing."""+ report = perms.usage_report(SLUG)++ assert report['unused_observable'] == [AGENT_PERM]++ def test_a_refusal_is_recorded_and_still_raises(self, app, installed):+ """The denial is the interesting one: something reached for a+ capability it never declared."""+ with pytest.raises(perms.PermissionDenied):+ perms.require(SLUG, 'agent.command:rm-rf')++ report = perms.usage_report(SLUG)+ assert report['undeclared_attempts'] == ['agent.command:rm-rf']+ row = next(r for r in report['permissions']+ if r['permission'] == 'agent.command:rm-rf')+ assert row['declared'] is False+ # It was refused, so it did not happen — 'used' must not claim it did.+ assert row['used'] is False+ assert row['denied'] == 1++ def test_observations_are_per_extension(self, app, installed):+ perms.require(SLUG, AGENT_PERM)++ assert perms.observed_permissions('someone-else') == []++ def test_has_does_not_record(self, app, installed):+ """`has` is a question, not a use — recording it would fabricate+ activity for callers that only checked."""+ perms.has(SLUG, AGENT_PERM)++ assert perms.observed_permissions(SLUG) == []+++# --------------------------------------------------------------------------- #+# What the gate CANNOT see — the honesty requirement+# --------------------------------------------------------------------------- #+class TestDeclarationOnlyCapabilities:++ @pytest.mark.parametrize('permission', sorted(perms.KNOWN_PERMISSIONS))+ def test_host_capabilities_are_not_observable(self, permission):+ """docker/shell/filesystem/network/db have no gated seam: the SDK+ exposes no helper for them, so a plugin reaches the host module+ directly and nothing in-process sees it."""+ assert perms.is_observable(permission) is False++ def test_agent_commands_are_observable(self):+ """The SDK is the only way to run a command on an agent, so every use+ must pass the gate."""+ assert perms.is_observable(AGENT_PERM) is True++ def test_an_unused_declaration_only_permission_is_never_called_unused(self, app, installed):+ """'shell' is declared and never seen — but absence of evidence is not+ evidence of absence here, and reporting it as unused would be a claim+ the panel cannot support."""+ report = perms.usage_report(SLUG)++ row = next(r for r in report['permissions'] if r['permission'] == 'shell')+ assert row['declared'] is True+ assert row['observable'] is False+ assert 'shell' not in report['unused_observable']++ def test_the_report_counts_both_kinds(self, app, installed):+ report = perms.usage_report(SLUG)++ assert report['observable_count'] == 1 # agent.command:restart+ assert report['declaration_only_count'] == 1 # shell+++# --------------------------------------------------------------------------- #+# API surface+# --------------------------------------------------------------------------- #+def admin_headers(app):+ from flask_jwt_extended import create_access_token+ from werkzeug.security import generate_password_hash+ from app import db+ from app.models import User++ user = User(email='[email protected]', username='permadmin',+ password_hash=generate_password_hash('x'),+ role=User.ROLE_ADMIN, is_active=True)+ db.session.add(user)+ db.session.commit()+ return {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}+++def viewer_headers(app):+ from flask_jwt_extended import create_access_token+ from werkzeug.security import generate_password_hash+ from app import db+ from app.models import User++ user = User(email='[email protected]', username='permviewer',+ password_hash=generate_password_hash('x'),+ role=User.ROLE_VIEWER, is_active=True)+ db.session.add(user)+ db.session.commit()+ return {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}+++class TestPermissionsEndpoint:++ def test_admin_gets_the_report(self, client, app, installed, admin_headers):+ perms.require(SLUG, AGENT_PERM)+ resp = client.get(f'/api/v1/plugins/{installed.id}/permissions',+ headers=admin_headers)+ body = resp.get_json()++ assert resp.status_code == 200+ assert body['slug'] == SLUG+ assert {r['permission'] for r in body['permissions']} == {AGENT_PERM, 'shell'}++ def test_non_admin_is_refused(self, client, installed, viewer_headers):+ """It describes what third-party code has been doing — operator info."""+ resp = client.get(f'/api/v1/plugins/{installed.id}/permissions',+ headers=viewer_headers)++ assert resp.status_code == 403++ def test_anonymous_is_refused(self, client, installed):+ assert client.get(+ f'/api/v1/plugins/{installed.id}/permissions').status_code == 401++ def test_unknown_plugin_is_404(self, client, admin_headers):+ assert client.get('/api/v1/plugins/999999/permissions',+ headers=admin_headers).status_code == 404