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(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.py
index 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.py
index 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 tight
later.
"""
import logging
+import threading
+from datetime import datetime
logger = 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 the
plugin 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.py
new file mode 100644
index 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