[experiment] python

[AlexandreYang]

What does this PR do?

Motivation

Testing

Checklist

• Tests added/updated
• Documentation updated (if applicable)

[AlexandreYang]

Implementation notes: python builtin

This PR adds a python builtin command that executes Python 3.4 source code using gpython, a pure-Go Python interpreter. No CPython installation is required.

---

Architecture

The implementation is split across two packages:

builtins/python/python.go                  ← builtin registration, flag parsing, source dispatch
builtins/internal/pyruntime/pyruntime.go   ← gpython wrapper + security sandbox

The split is deliberate. builtins/internal/ is exempt from the builtinAllowedSymbols static-analysis check, which means the pyruntime package can freely use gpython's third-party API and the required blank import (_ "github.com/go-python/gpython/stdlib"). The outer builtins/python/python.go only sees the clean pyruntime.Run(ctx, opts) interface and is fully subject to the allowlist checker.

---

Usage

python [-c CODE] [-h] [SCRIPT | -] [ARG ...]

Mode	Description
python -c "print(1+1)"	Execute inline code string
python script.py	Execute a script file (via AllowedPaths sandbox)
echo "print(1)" | python -	Read source from stdin

---

Security sandbox

Every gpython context is hardened before any user code runs:

1. os module sanitisation

The os module is pre-loaded via py.Import(pyCtx, "os") and then stripped of all dangerous functions before user code can touch it. Deleted names include:

• Process exec/spawn: system, popen, execl, execle, execlp, execlpe, execv, execve, execvp, execvpe, fork, forkpty, spawnl … spawnvpe, startfile
• Filesystem writes: remove, unlink, mkdir, makedirs, rmdir, removedirs, rename, renames, replace, link, symlink, truncate, write
• Permission/ownership: chmod, chown, chroot
• Environment mutation: putenv, unsetenv
• Signal delivery: kill, killpg, _exit

Because the module is pre-loaded and cached in gpython's module store, any later import os in user code returns the already-sanitised copy.

2. Sandboxed open()

builtins.open is replaced with a Go-backed function that:

• Rejects any mode containing w, a, x, or + with PermissionError
• Routes read-only opens through callCtx.OpenFile, which enforces the AllowedPaths sandbox
• Returns a goFile object with read(), readline(), readlines(), close(), __enter__/__exit__ — enough for with open(...) as f: patterns
• Caps all reads at 1 MiB to prevent memory exhaustion

3. Blocked modules

tempfile and glob are neutered at context creation: their registered module implementations run Python code that raises ImportError, so import tempfile / import glob fails. (In practice, gpython's stdlib doesn't expose truly dangerous APIs for these, but neutering them is defence-in-depth.)

4. Stream redirection

sys.stdout, sys.stderr, and sys.stdin are replaced with custom Go-backed Python types (goWriter, goReader) that wrap callCtx.Stdout, callCtx.Stderr, and callCtx.Stdin. This ensures all Python print() output is captured by the shell executor's output limiter.

5. sys.exit() exit code propagation

gpython's built-in sys_exit has a bug: it returns the SystemExit exception as a Python value rather than raising it, so it never propagates to the Go caller. The fix is a custom override that stores the exit code in a closure variable (*exitCodePtr) before returning any error to stop the VM — this way the code is recovered even after gpython wraps the Go error into a SystemError exception:

var sysExitCode *int
// sys.exit() closure sets *sysExitCode before returning any error
sysMod.Globals["exit"] = py.MustNewMethod("exit", func(...) (py.Object, error) {
    c := code
    *exitCodePtr = &c
    return nil, fmt.Errorf("sys.exit(%d)", code)
}, ...)

// After py.RunCode returns:
if sysExitCode != nil {
    return *sysExitCode   // recovered before VM wraps the error
}

6. Context cancellation

Run() executes gpython in a goroutine and selects on ctx.Done(). If the shell's execution timeout fires, the goroutine is abandoned. Because gpython is pure-Go and holds no OS resources (no child processes, no file descriptors beyond what the sandbox controls), abandoning the goroutine is safe.

---

Memory limits

Resource	Limit	Enforcement
Script / stdin source	1 MiB	io.LimitReader in python.go
open().read()	1 MiB	io.LimitReader in goFile.read()
open().readlines()	1 MiB	io.LimitReader before bytes.SplitAfter
stdin .read()	1 MiB	io.LimitReader in goReader.read()
Print output	executor limit (1 MiB)	enforced upstream by shell executor

---

Static analysis

The implementation registers in both analysis allowlists:

• builtinPerCommandSymbols["python"] — lists the handful of stdlib symbols used directly in builtins/python/python.go (io.LimitReader, io.ReadAll, io.Reader, os.O_RDONLY, context.Context)
• internalPerPackageSymbols["pyruntime"] — lists all stdlib symbols used in pyruntime (bufio, bytes, context, errors, fmt, io, os, strings)
• internalAllowedSymbols — updated with the new symbols as the global ceiling
• ExemptImport in both internalCheckConfig and internalPerPackageCheckConfig — exempts github.com/go-python/gpython/ from symbol-by-symbol checking (listing every py.* symbol would be impractical and offer no security benefit)

---

Test coverage

Test file	Coverage
builtins/tests/python/python_test.go	30+ unit tests: all flags, sys.exit propagation, file I/O, every sandbox restriction, error paths, context cancellation
builtins/tests/python/python_fuzz_test.go	Two fuzz targets: arbitrary source strings via -c, arbitrary file content via script file
tests/scenarios/cmd/python/	14 YAML scenario tests across basic/, sandbox/, errors/, stdin/

---

Known limitations (gpython vs CPython)

• Python 3.4 syntax only — no f-strings, walrus operator (:=), match/case, *-unpacking in calls
• Very limited stdlib: math, sys, os (read-only), time, string, binascii — no json, re, io, pathlib, hashlib, collections, itertools, etc.
• str methods are limited — e.g. .upper(), .join(), .split() are not implemented in gpython
• No subprocess, socket, threading, multiprocessing (not in gpython stdlib)