Merge pull request 'Address review feedback: Research and design GDScript sandboxing approach' (#19) from agent/8f93a0732163 into main
This commit was merged in pull request #19.
This commit is contained in:
@@ -0,0 +1,159 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user