modbison/docs/architecture/scripting_sandbox.md

# GDScript Sandboxing for User-Written Scripts

> **Status:** Proposed
> **Owner:** Platform team
> **Related:** Content moderation & age verification (scripts are one of the
> three moderated content types), avatar component system

## 1. Overview

This document evaluates how to safely run **user-written scripts** as part of
UGC (user-generated content) in **agp-game**, and recommends an approach.

**Bottom line: Godot 4 has no built-in security sandbox for GDScript, and
none of the three options named in the original task hold up under testing.**
A script running anywhere inside the Godot process — however it's loaded,
parented, or wrapped — runs with full engine privileges: arbitrary process
execution, full filesystem read/write, and raw network access. Sandboxing
has to happen *outside* the scripting language, not through an in-engine
restriction mechanism, because no such mechanism exists.

This was verified directly against Godot 4.6.2 (`godot --headless`, evidence
in `sandbox_probe/` on this branch) rather than assumed from documentation,
some of which (see §2.1) describes APIs that don't actually exist in this
version.

## 2. Options Evaluated

### 2.1 Godot's built-in "ScriptServer" restrictions — does not exist

There is no `ScriptServer` class in Godot 4.6.2:

```
ClassDB.class_exists("ScriptServer")  →  false
```

There's also no project setting to disable engine subsystems for scripts —
none of `application/run/disable_os`, `disable_file_access`, or
`disable_network` exist as settings, and `ProjectSettings.get_property_list()`
returns nothing matching "sandbox", "restrict", or "security". Any plan that
assumes a flag like this exists needs to be dropped; it was likely conflated
with sandboxing features from a different engine/scripting ecosystem, or
with **export template stripping** (which controls what ships in a build,
not what a script can call at runtime).

Directly probed capabilities of an ordinary GDScript running as a normal
node script, no special setup:

| Capability | Available to any script? |
|---|---|
| `OS.execute(...)` — run arbitrary processes | ✅ Yes |
| `FileAccess.open(...)` — read/write any path the OS user can reach | ✅ Yes (read `/etc/hostname`, write `/tmp/...` both succeeded) |
| `TCPServer` / `HTTPClient` / `HTTPRequest` / `PacketPeerUDP` / `WebSocketPeer` | ✅ All instantiate and work |
| `ClassDB.instantiate(...)` — construct any engine class by name | ✅ Yes |
| Loading and running a second script from source text at runtime (`GDScript.new()` + `.reload()`) | ✅ Yes |

**Verdict: rejected.** There is nothing to configure here — the restriction
surface this option assumed doesn't exist in the engine.

### 2.2 Isolated SubViewport with a limited API — doesn't isolate scripts

`SubViewport` is a **rendering and input isolation** primitive (it gives a
scene subtree its own render target and can gate input propagation) — it is
not a security or scripting boundary. A script attached to any node inside a
`SubViewport` still runs in the same process, on the same GDScript VM, with
the exact same access to `OS`, `FileAccess`, networking classes, and
`ClassDB` as a script anywhere else in the tree. Nothing about being
"inside" a SubViewport changes what API calls are reachable from a script.

**Verdict: rejected.** This solves a rendering/UI-composition problem, not
the security problem the task is asking about. Worth keeping in mind for
other purposes (e.g. isolated preview rendering of user avatars), but it
provides zero script sandboxing.

### 2.3 Custom GDScript interpreter with an allowlist — right idea, wrong layer for "custom interpreter"

Two ways to read this option, tested separately:

**(a) Write/embed a separate GDScript parser+interpreter.** Not
practical — this means re-implementing (and then indefinitely maintaining,
in lockstep with every Godot release) a full language interpreter outside
the engine. Far more engineering than the problem justifies.

**(b) Use Godot's built-in `Expression` class as a restricted subset.**
`Expression` *looks* like a natural allowlist mechanism — it only evaluates
a single expression, no control flow, no arbitrary statements. But it isn't
safe by default: it can still reach through to unsafe engine methods if you
aren't careful about what object you hand it as a base instance:

```gdscript
var expr = Expression.new()
expr.parse("get_environment('HOME')", ["OS"])
expr.execute([], OS)   # → "/home/daddy"  (successfully called OS.get_environment)
```

So `Expression` is a viable building block only if the host **never passes
a base instance (or arguments) that exposes anything sensitive** — i.e. the
allowlisting work still has to happen at the call site, `Expression` itself
enforces none of it.

**Static text pattern-matching (blocklisting dangerous substrings like
`"OS.execute"` before parsing) was also probed and is not a real
defense** — it's trivially defeated by string concatenation, `call()`,
`Callable`, or any other indirection, and produces false confidence.

**Verdict: partially viable, but only as a foundation, not a solution on
its own.** A hand-built, narrow, data-driven DSL (not full GDScript, not
raw `Expression`) with an explicit allowlist of safe operations and *no
ability to reference engine singletons or arbitrary objects* is the only
version of "custom interpreter" that's actually safe. This is real
engineering effort, not a config flag.

## 3. Recommendation

**Don't run untrusted GDScript in-process at all.** Given none of the three
in-engine options provide a real boundary, the two approaches actually worth
building are, in order of recommended priority:

1. **Primary: a narrow, non-Turing-complete content DSL**, not general
   scripting. Most UGC scripting needs in a game like this (custom
   interactions, simple triggers, item behaviors) don't need a general
   programming language — they need a small set of declarative
   verbs/conditions (e.g. `on_interact: give_item("torch")`,
   `on_enter: play_sound("chime")`). Expressed as data (JSON/Resource, not
   code) and interpreted by trusted, hand-written GDScript on the engine
   side. This has *zero* attack surface by construction — there's no
   interpreter to escape because there's no general execution, just a
   fixed, reviewed set of verbs. This is almost certainly sufficient for
   the actual UGC use cases in this game and should be scoped against real
   feature requirements before assuming more is needed.

2. **If genuinely general scripting becomes a hard requirement**, isolate it
   at the OS level, not the engine level: run untrusted scripts in a
   **separate process** (a stripped-down Godot instance or a dedicated
   interpreter) under OS sandboxing (a restricted user account, a
   container, or `firejail`/`bwrap`/seccomp), communicating with the main
   game over a narrow IPC/RPC boundary that only exposes intentionally-safe
   operations. This is the only approach that provides a real security
   boundary for arbitrary code, because it doesn't depend on the scripting
   language cooperating — the OS enforces it. Substantially more
   infrastructure than option 1; only worth it if option 1's DSL genuinely
   can't express what's needed.

**Do not** attempt in-process GDScript sandboxing via SubViewport,
ScriptServer, or ad hoc blocklisting — all three were directly tested and
none provide a real boundary (§2).

## 4. Open Questions

- What do actual planned UGC scripts need to *do*? (Trigger conditions,
  simple item/state effects, dialogue branching?) This determines whether
  the DSL in §3.1 is sufficient or whether §3.2's process isolation is
  needed. Needs a concrete feature list before implementation starts.
- If §3.2 is needed later, does it run per-user-session or shared/pooled?
  Affects resource cost and isolation guarantees.
- Interaction with the content moderation pipeline (`content_moderation.md`):
  scripts as a moderated content type still need a moderation flag path
  regardless of which execution model is chosen — a DSL makes static
  analysis of *what a script can possibly do* far easier than it would be
  for general code, which is an additional point in its favor.