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.

docs(security): stop claiming extension permissions are enforced

Juan Denis8df7350f41f2
diff --git a/SECURITY.md b/SECURITY.md
index 160e5314..39212724 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -108,6 +108,45 @@ carry a `sink-safe: <sanitizer> — <why>` comment. `scripts/check-html-sinks.mj
fails CI on any new unannotated sink, so a raw-HTML injection point can't land
silently.
+## 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 Note
The agent gateway keeps all connected-agent state in-memory in a single process.
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index 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** update
for every source (URL/upload/local/builtin/registry).