SheetPython — security model
This document states what the Python integration of ORIX Sheet enforces, how each claim is verified, and what it
does not enforce. Claims marked ✔ are asserted by a test that runs a real interpreter; the test name is given.
Observations were made on macOS 27.0 (26A5425a), Apple Silicon, with Homebrew Python 3.14.4 and the Xcode Python
3.9.6. Tests live in Tests/SheetPythonTests (engine) and ../FeaturePython/Tests/FeaturePythonTests (app layer).
1. Design in one paragraph
Scripts run in a separate process of a Python interpreter already installed on the Mac (nothing is bundled or
embedded), started with posix_spawn in its own process group. The script talks to the app only through two
inherited pipes (fd 3 and 4) carrying newline-delimited JSON requests: read a range, list sheets, read the
selection, buffer a write, announce a figure or a table preview, report the end. The app answers reads from the live
workbook and buffers writes; they are applied as one undoable step only when the run succeeds. In restricted
mode (the default) the interpreter is wrapped in /usr/bin/sandbox-exec -p <profile>.
2. Threat model
Assets: the user's files and credentials, the network position of the Mac, the other processes of the user, the content of the open workbook, the integrity of the workbook.
Adversaries considered:
- A workbook received from someone else that contains a script (the main threat). The script must not run without the user reading and approving it, and when it runs in restricted mode it must not reach files, network or other programs.
- A script the user wrote or pasted that misbehaves: infinite loop, huge output, fork bomb-like behaviour, memory exhaustion, attempts to keep running after the run.
- A script attacking the app through the protocol: malformed messages, oversized messages, forged requests, closing the pipes, never reading answers.
Out of scope: a compromised interpreter or a malicious package already installed in the interpreter's site-packages (it is code the user installed; in restricted mode it runs under the same restrictions as the script), kernel or sandbox vulnerabilities, an attacker who already runs code as the user outside restricted mode.
3. Never auto-executed
- Scripts are stored as data (
Workbook.attachments["python/<id>.json"]).PythonScripts.loadonly decodes JSON. - Nothing in SheetPython or FeaturePython starts an interpreter on a script when a workbook is opened, when the
Studio appears or when a script is selected. The only path to execution is
PythonStudioModel.run()(the Run button / ⌘↩), which first evaluates consent. ✔StudioModelTests.scriptsFromAWorkbookNeverRunWithoutConsent(opening + showing: console empty, sheet untouched, no audit entry for that code). - Interpreter discovery does run the interpreters found at the standard locations (and the one the user chooses)
with the bundled
probe.pyunder-I -B, an 8 s timeout and a minimal environment — it runs no workbook content./usr/bin/python3is only probed when developer tools are installed (otherwise the shim would open an install dialog). Note: an attacker able to plant an executable namedpython3in one of those locations already has the user's privileges.
4. Consent
Implemented by PythonConsent (FeaturePython) and PythonTrust (SheetPython).
| Rule | Verified by |
|---|---|
| A script that arrived with a workbook shows the consent sheet (full code, interpreter, mode, time limit, SHA-256) before its first run in a session | ConsentTests.scriptsFromAWorkbookAlwaysAsk, StudioModelTests.scriptsFromAWorkbookNeverRunWithoutConsent |
| "Cancel" runs nothing | same model test |
| The answer is valid only for the exact text and mode that were displayed: if the script changed while the sheet was open, nothing runs | same model test (marker file never created) |
| "Run once" records nothing; a later session asks again | same model test |
| "Always trust this script" stores the SHA-256 of the exact text + the workbook identifier; any change of the text (in another editor, in the file) makes it untrusted again; another workbook asks again | RecordsTests.trustIsKeyedByExactCodeWorkbookAndMode, ConsentTests.trustIsForTheExactTextAndMode, model test (tampered copy) |
| Consent given for restricted mode never covers an unrestricted run | RecordsTests…, ConsentTests.trustIsForTheExactTextAndMode, StudioModelTests.unrestrictedModeNeedsItsOwnConfirmations |
| Turning restricted mode off needs an explicit confirmation, once per app launch; restricted mode is ON at every launch | StudioModelTests.unrestrictedModeNeedsItsOwnConfirmations |
| Even a script written in this session needs the consent sheet to run unrestricted | same |
Deliberate usability choice (rule 2 of PythonConsent): once the user has reviewed a script in the sheet, or
created it in the current session, the edits they type afterwards run without a new prompt until the app quits.
The trust store is ~/Library/Application Support/ORIX Sheet/python-trust.json (mode 0600).
Limit: the trust store and the audit log are ordinary files of the user. A script run unrestricted could edit them (and anything else). A restricted script can neither read nor write them (home directory denied).
5. Restricted mode — what is enforced
Profile: PythonSandbox.profile (SBPL, "allow default, then deny"). If sandbox-exec is missing or cannot apply a
profile (checked by really launching a sandboxed /usr/bin/true once per launch), restricted runs are refused;
they never fall back to unrestricted.
✔ RestrictedModeTests.restrictedModeRefusesToRunWithoutTheSandbox (missing launcher and failing launcher: error
sandboxUnavailable, marker file not created, audit entry refused).
Every denial below is asserted by RestrictedModeTests.restrictedModeDeniesWhatItClaims, and the same probe
script is asserted to succeed without the sandbox by RestrictedModeTests.unrestrictedModeAllowsTheSameThings
(so the tests measure the sandbox, not an unrelated failure). Independent evidence is checked from the test process:
a local TCP listener counts connections, files are looked up on disk, a victim process is checked alive.
| Enforced in restricted mode | Observed |
|---|---|
✔ No outbound TCP (even to 127.0.0.1), no UDP send, no listening socket ((deny network*), (deny system-socket)) |
PermissionError: Operation not permitted; listener saw 0 connections |
✔ No file creation/modification outside the run directory and explicitly granted writable paths: ~/Desktop, /tmp/… denied |
PermissionError; files absent |
✔ Writing inside the run directory (cwd, TMPDIR) works; it is deleted after the run |
write_run_dir, write_cwd ok; runPython helper asserts removal after every test |
✔ No reading of /Users/** (the whole home: listing ~, ~/.ssh, ~/Library/Keychains, ~/Documents, ~/Library/Application Support), nor of /private/tmp, /Volumes, nor of the user's per-user temp/cache tree outside the run directory |
PermissionError for each probed path (~, ~/.ssh, ~/Library/Keychains, ~/Documents, ~/Library/Application Support, /Volumes, a directory in /tmp) |
✔ Explicitly granted paths: readablePaths readable but not writable, writablePaths writable |
granted_read ok, granted_read_write_refused denied, granted_write ok |
✔ No other program can be executed: /usr/bin/curl, /bin/ls, a shell via os.system, /usr/bin/osascript ((deny process-exec*) except the interpreter's own tree) |
PermissionError |
✔ The interpreter may re-execute itself (needed by multiprocessing); children inherit the sandbox |
spawn_self ok |
| ✔ No signal to processes outside the sandbox | os.kill → PermissionError; victim still alive |
✔ Network can be re-enabled only by PythonRunOptions.allowNetwork (not exposed in the 1.0 UI); it opens nothing else |
networkCanBeGrantedExplicitly |
| ✔ The scientific stack works under the profile (numpy, pandas, matplotlib, scipy, statsmodels, scikit-learn, polars, duckdb, pyarrow, sympy) | scientificStackWorksRestricted |
| ✔ Works with every interpreter found (Homebrew 3.14, Xcode 3.9, a venv) | DiscoveryTests.restrictedModeWorksWithEveryDiscoveredInterpreter, managedVenvIsCreatedOffline |
Also in the profile but not covered by a dedicated test (do not present them to users as guarantees):
(deny mach-lookup) except a short allow-list (user database, logging, preferences, fonts), (deny appleevent-send),
(deny lsopen), (deny job-creation), and read denials for /private/var/tmp, /Network, /Library/Keychains,
/private/var/root.
6. Restricted mode — what is NOT enforced
- Reads outside the denied roots.
/Applications,/usr,/opt,/Library(except Keychains),/System,/private/etc… remain readable. The script can list running processes through system calls. - The workbook. A script can read every sheet of the open workbook through
orix(hidden sheets included) and print it or write it back into cells. Restricted mode stops it from sending that data over the network or to a file, not from reading it. - It is not a VM.
sandbox-execis Apple's Seatbelt launcher; Apple marks it deprecated, it still ships and works on macOS 27. The script and native extension modules run on the real kernel. - Memory. macOS refuses
RLIMIT_AS,RLIMIT_DATAandRLIMIT_RSSfor a running interpreter ("current limit exceeds maximum limit") and a 600 MB allocation succeeds regardless (✔addressSpaceLimitIsNotEnforceableButTheWatchdogIsprints and asserts this). Instead the host samples the physical footprint of the script's process tree every 0.2 s and kills it abovemaxMemoryBytes(default 8 GB) (✔ same test: 400 MB cap, killed, audit outcomekilled). A script can overshoot between two samples. - Processes that detach. Termination signals the process group and every descendant seen during the run
(process table sampled every 0.2 s), so
setsidchildren that ignore SIGTERM are killed (✔cancelWithChildProcesses, restricted and unrestricted). A process that daemonises faster than one sampling interval and is re-parented to launchd could survive; in restricted mode it stays inside the sandbox and underRLIMIT_CPU. - Disk space. A script may fill the run directory up to
RLIMIT_FSIZEper file (default 1 GB), with no cap on the number of files. - Unrestricted mode has no sandbox at all: only §7 and §8 apply. The script has the user's full file and network access (subject to macOS TCC prompts attributed to ORIX Sheet).
7. Resource limits (both modes)
| Limit | Mechanism | Verified by |
|---|---|---|
| Wall-clock time (default 60 s) | host timer → SIGTERM to group + descendants, SIGKILL after 0.5 s | timeoutKillsTheScript, killedWhileHostIsAnswering |
| Stop button | same termination path, also on Swift task cancellation | cancelInfiniteLoop, cancelSleeping, cancelCPUBoundNativeCode, cancelIgnoringSIGTERMGetsSIGKILL, cancelWithChildProcesses, taskCancellationStopsTheScript (pids checked dead) |
| No orphans after a normal end | group + known descendants SIGKILLed when the interpreter exits | childrenLeftBehindByAFinishedScriptAreKilled |
| CPU time (default 300 s per process) | RLIMIT_CPU soft = n → SIGXCPU, hard = n+1 → SIGKILL, set by the runner before user code |
cpuLimitIsEnforcedByTheKernel (restricted and unrestricted) |
| File size (default 1 GB) | RLIMIT_FSIZE, hard limit |
fileSizeAndOpenFileLimits (EFBIG) |
| Open files (default 256) | RLIMIT_NOFILE, hard limit |
same (EMFILE) |
| Limits cannot be raised again by the script | soft = hard | same (setrlimit refused) |
| Output (default 4 MB stdout+stderr) | host keeps and forwards the first N bytes, drains and drops the rest | outputIsCappedAndStreamed |
| Buffered writes | at most 20 000 000 cells per run; each write must fit 1 048 576 × 16 384 | writesOfPlainPythonTypes, malformedMessagesAreIgnored |
| Core dumps | RLIMIT_CORE = 0 |
— |
| App quits while a script runs | PythonRunner.killAllRunningScripts() (called by FeaturePython on NSApplication.willTerminate): SIGKILL to every family, run directories removed |
AppExitTests.quittingTheAppKillsRunningScriptsAndRemovesTheirDirectories |
| App crashes / is force-quit while a script runs | a watchdog thread in runner.py notices the re-parenting within 0.5 s and SIGKILLs the script's process group |
AppExitTests.scriptDoesNotOutliveACrashedApp (restricted and unrestricted). The run directory of a crashed app is removed by removeStaleRunDirectories() at a later launch (after 24 h). A script that blocks the interpreter in native code without releasing the GIL delays this watchdog; RLIMIT_CPU still applies. |
The rlimits are applied by runner.py (trusted code) before the user's code is compiled; .pth files of the
interpreter's own site-packages run earlier, inside the sandbox in restricted mode.
8. Environment isolation (both modes)
Launch line: python -u -X utf8 -I -B runner.py <run-dir>.
-I:PYTHON*variables ignored (noPYTHONPATH,PYTHONSTARTUP), no per-user site directory, the script directory is not onsys.path. Consequence: packages installed withpip install --userare not importable unlessPythonRunOptions.includeUserSiteis set (not exposed in the 1.0 UI; the launch line stays-Iand the runner adds that single directory withsite.addsitedir); packages in the interpreter's own site-packages (Homebrew, python.org, a venv with its system site-packages) are importable.- Environment built from an allow-list:
LANG,LC_ALL,LC_CTYPE,TZcopied;PATH=/usr/bin:/bin:/usr/sbin:/sbin,HOME,TMPDIRandXDG_CACHE_HOMEinside the run directory (XDG_CACHE_HOME=TMPDIR),MPLBACKEND=Agg,MPLCONFIGDIRinside the run directory, andORIX_SHEET=1(lets a script detect that it runs inside ORIX Sheet).LANGdefaults toen_US.UTF-8when the app has none. Caller extras (PythonRunOptions.extraEnvironment) are applied last and may override these; those starting withPYTHONorDYLD_are dropped. - Only fd 0 (/dev/null), 1, 2, 3, 4 are inherited (
POSIX_SPAWN_CLOEXEC_DEFAULT). - A fresh 0700 run directory per run, removed afterwards (figures are kept until the caller calls
discard()). The only file that travels between runs is matplotlib'sfontlist-v*.jsoncache, copied by the host (regular file, < 8 MB, never overwritten once present), with separate copies for restricted and unrestricted runs.
✔ environmentIsAnAllowList (secret variable absent, flags, cwd/HOME/TMPDIR, inherited descriptors, directory
removed), ✔ every runPython call asserts no run directory is left, ✔ staleRunDirectoriesAreSwept.
9. Protocol robustness
✔ malformedMessagesAreIgnored (non-JSON, unknown operation, wrong shapes, ragged rows, out-of-sheet anchor, a
"figure" outside the run directory: refused, recorded as warnings, channel still usable),
✔ scriptClosingThePipes, ✔ hostErrorsReachTheScript (host exception → orix.OrixError),
✔ scriptSpammingTheChannelAndExiting, ✔ killedWhileHostIsAnswering.
A figure is accepted only if it is a .png directly inside the run's figures directory.
Writes are never applied by the engine. The app applies them only when PythonRunResult.succeeded, after
re-validating every target and parsing every formula; any invalid item cancels the whole batch
(✔ WriteApplierTests.anInvalidBatchWritesNothing, ✔ StudioModelTests.failedRunWritesNothingAndMarksTheLine).
A read made after a write in the same run sees the pre-run sheet (✔ readAfterWriteSeesThePreRunSheet).
10. Audit log
PythonRunner.run itself appends one JSON line per run — and per refused run — to
~/Library/Application Support/ORIX Sheet/python-audit.jsonl (mode 0600, bounded to 4 MB): timestamp, workbook
name, script name, SHA-256 of the code, interpreter path and version, restricted flag, network flag, duration, exit
status, outcome (ok, error, timeout, cancelled, killed, refused), error summary, number of writes.
✔ RecordsTests.everyRunIsAudited, plus the outcome assertions in the timeout/cancel/refusal/memory tests.
It is a record for the user, not a tamper-proof log (see §4).
11. Packages
Listing packages (PythonEnvironmentManager.listPackages) reads importlib.metadata only and reports each
distribution's install location, INSTALLER and provenance (✔ packageListingHasProvenance). Creating the managed
venv works offline (✔ managedVenvIsCreatedOffline). PythonEnvironmentManager.install is the only operation
that uses the network: it runs pip install -- <requirement> in the managed venv, unsandboxed, and pip executes
the package's build/installation code. The requirement is validated against a strict pattern (no options, URLs,
paths; ✔ requirementValidation) and the UI asks for an explicit confirmation that shows the exact command. Real
installs are not exercised by the tests.