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
docs(security): stop claiming extension permissions are enforced
Juan Denis8df7350f41f2
diff --git a/SECURITY.md b/SECURITY.mdindex 160e5314..39212724 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -108,6 +108,45 @@ carry a `sink-safe: <sanitizer> — <why>` comment. `scripts/check-html-sinks.mjfails CI on any new unannotated sink, so a raw-HTML injection point can't landsilently.+## Extension Trust Model++Extensions are **in-process code**. An installed extension runs with the panel's+privileges, in the panel's interpreter, against the panel's database. Nothing in+ServerKit sandboxes it, and no permission string changes that. Everything below is+about making an extension's behaviour *legible* before and after you install it —+not about containing it. Treat installing an extension exactly as you would treat+running any other code as root on the box.++**Integrity — what the panel does verify.** First-party release zips are signed+(ed25519; the pinned public key ships in `backend/app/data/`), and the registry+index carries `signature` + `publisher_key_id`. Install verifies before extracting:+a **bad** signature is always a hard failure, an **unsigned** extension prompts for+consent rather than being blocked (third parties must remain installable), and the+verdict is stamped on the installed row and shown in the UI. Registry entries are+additionally pinned by sha256, so a swapped release asset fails the download.++**Permissions — what the panel does NOT enforce.** A manifest's `permissions` array+is a consent signal shown at install time. It is enforced only where a capability+*must* pass through the SDK gate, which today means `agent.command:<action>` and+nothing else. `docker`, `shell`, `filesystem`, `network` and `db` have no gated+helper — the SDK exposes none, and `db` is raw SQLAlchemy — so an extension using+them imports the host module directly and no in-process check is involved.++The extension detail page reflects that split rather than papering over it: it+records real use (and refusals) for the mediated capability, and for the rest it+says use **cannot be observed** instead of showing a zero count. A "never used"+badge on an unenforceable permission would imply a boundary that does not exist.++**Python dependencies** are not installed by default. pip would run with the+backend's privileges and a `setup.py` hook is arbitrary code, so a shipped+`requirements.txt` is saved for review and surfaced on the extension's page;+operators opt in with `SERVERKIT_ALLOW_PLUGIN_PIP=1`.++The practical controls, in order of how much they actually protect you: install+only extensions you have reason to trust, prefer signed first-party releases,+read the consent dialog, and keep the registry curated. See+[docs/EXTENSIONS.md](docs/EXTENSIONS.md) for the per-capability table.+## Deployment NoteThe agent gateway keeps all connected-agent state in-memory in a single process.diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.mdindex 073520d8..819c73f3 100644--- a/docs/EXTENSIONS.md+++ b/docs/EXTENSIONS.md@@ -342,7 +342,7 @@ def list_things():| `doctor` | Register a health check; it appears on the doctor page, repair button and all. || `search` | Register searchable entities; they appear in the command palette. || `agents` | Run a command on a managed server (gated by `agent.command:<action>`). |-| `require_permission(slug, cap)` | Capability gate — raises `PermissionDenied` if `cap` isn't declared in `permissions`. |+| `require_permission(slug, cap)` | Capability gate — raises `PermissionDenied` if `cap` isn't declared in `permissions`, and records the call (allowed or refused). Only mediates what routes through it; see [Permissions & compatibility](#permissions--compatibility). || `panel_version()` | The panel's version string (for in-plugin compat checks). |Errors follow the core convention: `return jsonify({'error': 'message'}), status`.@@ -527,10 +527,43 @@ def register():## Permissions & compatibility-- `permissions` is a consent step on install and is **enforced** by the SDK gate:- `require_permission(slug, "docker")` raises unless `docker` is declared. (This is- in-process, declaration-based enforcement — see ADR 0001 / plan #42 for the- sandboxing posture.)+`permissions` is a **consent signal**, and for most capabilities that is all it is.+Be precise about which half applies, because the difference matters to anyone+deciding whether to trust an extension.++**What is actually mediated.** `require_permission(slug, cap)` raises+`PermissionDenied` unless `cap` is declared. That gate is real, but it only fires+where something *calls* it. Today exactly one capability is routed through it+unavoidably:++| Capability | Mediated? | Why |+|---|---|---|+| `agent.command:<action>` | **Yes** | The SDK is the only way to reach an agent, so every use passes the gate. Uses and refusals are recorded and shown on the extension's detail page. |+| `docker`, `shell`, `filesystem`, `network`, `db` | **No** | The SDK exposes no helper for these (and `db` is raw SQLAlchemy), so an extension imports the host module directly and no in-process check is involved. |++So declaring `docker` does **not** stop an extension from using Docker, and *not*+declaring it does not stop it either. What declaring does is tell the operator, at+install time, what the extension says it needs — and let them refuse.++**Why the panel says "cannot be observed".** The extension detail page compares+declared permissions against observed use. For `agent.command:*` an unused+declaration is real evidence of over-asking. For the five host capabilities the+panel reports that use *cannot be observed* rather than showing a zero: absence of+evidence is not evidence of absence, and a "never used" badge there would imply an+enforcement boundary that does not exist.++Declare honestly regardless. The consent dialog is what the operator agrees to, and+under-declaring to look harmless is the behaviour the curated registry exists to+catch. True out-of-process sandboxing is deliberately out of scope — see ADR 0001 /+plan #42 for the posture.++**Python dependencies.** A `requirements.txt` in your zip is **not** installed by+default: pip would run with the backend's privileges and a `setup.py` hook is+arbitrary code. The file is saved next to the installed extension and surfaced on+its detail page so an operator can review and install it deliberately. Operators+opt in with `SERVERKIT_ALLOW_PLUGIN_PIP=1`. Design your extension to degrade+clearly when an optional dependency is absent rather than crashing on import.+- `min_panel_version` / `max_panel_version` are enforced at install **and** updatefor every source (URL/upload/local/builtin/registry).