--sandbox: holding a running process to main's capabilities
The record for the OS sandbox's first two stages: the --sandbox flag, the
wrapper calls it lowers to, runtime/runtime-sandbox.c, which applies it, and
the fs.read=<dir> and fs.write=<dir> scopes it enforces. It says
what the sandbox withholds, against which adversary, what it leaves that
adversary, and which test pins each answer. The design and its open questions
are wp37-os-sandbox.md; a § or an "open question"
below is that note's. It was written on main at 804120e and names
functions rather than lines, so it has no file:line anchors to move.
Scope
| File | What |
|---|---|
runtime/runtime-sandbox.c |
nish_sandbox (the seven steps), nish_sandbox_check, nish_sb_drop_capabilities, nish_sb_landlock, nish_sb_granted, nish_sb_scope, nish_sb_rule, nish_sb_seccomp and its syscall tables; nish_sb_keep_marks and nish_sb_spawn_open, the spawn-target check, and nish_sb_spawn_once, nish_sb_supervisor, nish_sb_spawner, nish_sb_start, nish_sb_answer, nish_sb_lift and nish_sb_refuse_spawn, the one exec a spawn's subtree is held to (SBX-1); the non-Linux stubs |
runtime/runtime-net.c, runtime/runtime-uring.c |
step 5, the rings made before the filter (WP63 S3): nish_net_ring_premake, nr_slots and nr_open's latch on a pooled failure; nish_uring_premake, nish_uring_pooled, ur_make_ring, ur_restrict, ur_ops_ok, ur_pool and ur_add_ring's pool path. The io_uring side of those rings, what a restricted ring still reaches in the kernel, is net-uring.md's |
src/attributes.ts, src/manifest.ts |
the ring fact: listenFlagsValue, listenFlagsMayRing and FunctionFacts.ringListen, carried by relaxEdge, which say whether main can reach tcpListenFlags with NET_LISTEN_RING; netRingsAt, the position NL3058 names |
src/emit.ts |
the wrapper: @.sandbox.apply, its .preinit_array entry kept by @llvm.used, the call of @nish_sandbox_check first in @main, and the scope constants @.sandbox.read, @.sandbox.write and @.sandbox.exec (sandboxDirs) |
src/compile.ts, src/options.ts |
the flag, its modes, and the refusals: darwin (NL3044), --emit-napi, --emit-napi-async, --emit-ts, --emit-ast, --emit-checked, --fix, two modes at once, an entry with no main; the scopes (capabilityListMask, capabilityScopes): which are accepted, and each directory's resolution |
src/compilation.ts |
sandboxWidened, the widening of an ffi main by the policy's grants (open question 13); narrowSandbox, the scopes and the exec allowlist taken from a dependency's grant arguments, and the // mark on an interpreter the grant does not name (WP37 §2a, WP40 §2a); readNetRings (NL3058) and sandboxNetRings, the ring count nish_sandbox takes last: nish.netRings (1 to 64, default 1) when main reaches net and the ring bit, else 0 |
runtime/runtime-os.c |
nish_spawn_sandboxed and its call in nish_spawn_start: the spawn handed to the sandbox whole under an exec allowlist, and its error |
runtime/runtime-parallel.c |
nish_cpu_prime and the ceiling nish_cpu_count clamps to, step 1 |
runtime/nish.h |
the declarations of nish_sandbox, nish_sandbox_check, nish_cpu_prime and nish_spawn_sandboxed |
scripts/build.sh |
the refusal of --sandbox IR under the wasm and wasi profiles; -pthread on every ELF link, for the two threads a spawn under an exec allowlist runs on. A build without --sandbox is byte for byte the same on glibc 2.34 and later; before 2.34, where pthread_create is in libpthread, it can gain a DT_NEEDED on libpthread.so.0 (the debug profile always, speed and size where --as-needed still sees the runtime's reference), one more library of the same glibc loaded at start. Not measured: no test machine has such a glibc |
Out of scope: scopes in package.json's "nish" field for the root's own
capabilities, which stay refused (open question 1), and scopes of any
capability but fs.read and fs.write on the command line, which are
refused. A dependency's grant arguments are the one route by which the
manifest narrows the sandbox; their build-time check is
capabilities.md's (CAPS-14 to CAPS-20).
Threat model
This is §9's statement, in its words; every row of the mapping below is checked against it.
Who is trusted. The person who launches the binary, and everything that
person controls: the environment (LD_PRELOAD and LD_AUDIT among it), the
arguments, the working directory, the link line and the toolchain. Also
trusted are the compiler and the mask it computes, which --sandbox
enforces rather than checks, and the kernel.
Who is the adversary. All code in the process that runs after the
preinit call of §3: the program's Nish code, std, every dependency, every
ffi callee, and every constructor, in the executable, in an ffi object
or in a shared library. Its aim is to do what the mask withholds.
With what privilege. Whatever the launch gave, as uid 0, with file
capabilities or with a container's default set, step 3 of §3 drops every
capability before the adversary runs, and NO_NEW_PRIVS keeps an exec
from gaining one back. The identity stays. A uid-0 process still owns
root's files, so Landlock and the metadata-write rule are what hold it to
the mask, not file modes.
It can also signal other uid-0 processes, which
open question 8's scoping limits from ABI 6. A user namespace the adversary
creates gives it capabilities only over the namespace's own objects:
init_module, kexec_load, open_by_handle_at and bpf check the initial
namespace, the domain and the filter stay attached, and Landlock refuses
mount in a confined process.
What ffi code is allowed. The mask is computed from the Nish code, so
an ffi callee is held to what the Nish code reaches, not to what the C
code needs (§1). That errs towards refusal: a C library that needs more is
killed or refused, unless the policy grants it.
A main that reaches ffi under an allowlist (--allow, the manifest's
allow, or both, intersected) is widened by that list's net, fs.read,
fs.write and process.spawn, less any denial, a directory scope kept as a
scope (open question 13). The widening is the person building the program
choosing what the C code may reach; it never exceeds what the policy writes,
and without an allowlist nothing is widened.
What runs before the call. The dynamic loader, LD_AUDIT, LD_PRELOAD's
interposition and libc's own start-up run first. They are the launcher's
choice, so they are out of scope by this statement. An IFUNC resolver in an
ffi object or in a DT_NEEDED shared library also runs first, and it is
adversary code: that is a limit on what --sandbox holds (open question
11). On a C library that skips .preinit_array every constructor runs
first as well, and the program then refuses to run (§3, §7).
What the adversary keeps. Under the mask it was given, it keeps:
-
descriptors open before the call, and any it receives over
SCM_RIGHTS(from Linux 6.7 the kernel refuses to send an io_uring descriptor that way; one inherited acrossexecstill arrives, and the filter refusesio_uring_enteron it, and theclose,dup2anddup3that would put it at a premade ring's number, NURING-36); -
of
/proc/self, what needs no open:statandreadlinkon its entries, and descriptors to it already open; opening its files needsfs.read(open question 6); -
a terminal open before the call, fd 0 included, with
TIOCSTIwheredev.tty.legacy_tiocstiis 1, and below ABI 5 a terminal it reopens withfs.read(§4, open question 12); -
what argument-level checks would be needed to withhold (§10):
ioctl'sFS_IOC_SETFLAGSandFS_IOC_FSSETXATTRon a read-only descriptor, andmmapwithPROT_EXEC; -
the metadata reads of §4:
stat,lstat,statx,readlink,access,getxattr,listxattr,O_PATH,chdir,inotifyandfanotify; -
io_uring, when both
netandprocess.spawnare granted; withnetwithoutprocess.spawn,io_uring_enteronly on the descriptor numbers of the rings step 5 made (the filter comparesargs[0]with each; with none made,io_uring_enterkills like the other two), each ring restricted to ACCEPT, RECV, SEND, CLOSE, ASYNC_CANCEL and NOP, with no SQE flag but FIXED_FILE, BUFFER_SELECT and CQE_SKIP_SUCCESS, and no register call after it was enabled; what those opcodes reach in the kernel is net-uring.md's; -
the same-uid routes no row kills: SysV shared memory and message queues
(
shmget,shmat,msgget) shared with an unconfined process of the same user,perf_event_openwithin whatperf_event_paranoidallows,kcmp's comparison of another process's descriptors, andprocess_madvise(440) on a same-uid process it holds a pidfd to; - signals to its own uid (until ABI 6), the clock, entropy and the environment;
-
under best-effort without Landlock, every file the user can reach,
/proc/<pid>/memof another process included; -
under
process.spawn, read and execute on every file (open question 5), afs.read=<dir>scope notwithstanding; -
inside an
fs.write=<dir>scope, nothing more than outside it of the metadata writes:chmod,chown,utimensatand the extended-attribute writes still answerEPERMthere (open question 1); - beneath a scope, everything under the directory as the binary opens it at start, not as the compiler resolved it (see Limits), including a directory later moved or bind-mounted beneath it;
- kernel bugs, which no part of a sandbox in the same kernel holds;
-
the IFUNC resolvers above, and every constructor on a libc that skips
.preinit_array; - everything, on macOS, where
--sandboxis refused (§7).
Checked against the mapping. Each route to a withheld capability lands on one of these:
-
Files: Landlock's rights (§4), with the metadata writes in seccomp. On a
uid-0 process, Landlock holds where file modes would not.
open_by_handle_atwalks past path rules, but it needsCAP_DAC_READ_SEARCH, which step 3 drops. -
Processes: the
process.spawnrow,clone3'sENOSYSand the io_uring rows: no ring can be made or registered withoutprocess.spawn, and a premade ring refuses every opcode that opens, reads, writes or messages another ring. A module that loads one (finit_module) is refusedEPERMafter step 3.bpfis refusedEPERMwherekernel.unprivileged_bpf_disabledis 1 or 2, the default of most distributions; where it is 0, an unprivileged process may still load a socket filter, which reaches no capability the mask withholds. -
The network: the
netrow, the io_uring rows (a premade ring's ACCEPT, RECV and SEND reach only descriptors thenetrow lets the process hold) and the x32 kill. -
Another process: the always-on
ptrace,process_vm_*andpidfd_getfdkills.
What lands on none of these is in the list above, by name. A route found later is either added to §4's rows or added to that list, never left unstated.
The mapping
main's capability set is the first operand of nish_sandbox, a bitmask in
the report's order (bit 5 fs.read, 6 fs.write, 7 net, 8
process.spawn). nish_sandbox runs from .preinit_array, before every
constructor, and applies, in order:
-
nish_cpu_prime, which reads the CPU count (the cgroup's quota among it) while files can still be read; the pool takes it as the ceiling forNISH_NUM_THREADS, whose own read needs no file. -
PR_SET_NO_NEW_PRIVS. -
The capability drop: the effective, permitted and inheritable sets emptied, the ambient set cleared, the bounding set emptied when
CAP_SETPCAPallows it — each read back, not trusted. -
Landlock: every right the kernel's ABI knows is handled (REFER from ABI 2, TRUNCATE from 3, IOCTL_DEV from 5, the signal and abstract-socket scopes from 6), and one
path_beneathrule on/grants back the rights the mask grants whole —fs.read: READ_FILE, READ_DIR;fs.write: WRITE_FILE, the MAKE_* and REMOVE_* rights, REFER, TRUNCATE;process.spawn: EXECUTE, READ_FILE and IOCTL_DEV (open question 5).A scoped
fs.readorfs.write(the third and fourth operands, each a list of directories ended by a NUL and the list by a second,nullfor none) is left out of the rule on/and granted by onepath_beneathrule per directory, openedO_PATH(a directory, or, for the fifth operand, a file); a path that cannot be opened refuses strict and, under best-effort, is named and left out, which only narrows what is granted.The fifth operand, the exec allowlist (a list in the same shape: the programs a dependency's
process.spawn=<program>grants name, and the ELF interpreter or#!interpreter each needs), takes EXECUTE off the rule on/and grants it on each listed file alone. A directory scope is resolved by the compiler and refused there unless it is a directory, so droppingO_DIRECTORYwidens no scope the command line can name. -
Unless both
netandprocess.spawnare granted, the premade rings: withnetand a sixth operand above 0,nish_net_ring_premakemakes that many io_uring rings, each set upIORING_SETUP_R_DISABLED, thenIORING_REGISTER_RESTRICTIONS(the six opcodes and three flags above), then its file table, buffer ring and eventfd, thenIORING_REGISTER_ENABLE_RINGSlast. The firsttcpListenFlagswithNET_LISTEN_RINGtakes them; a ring that fails is closed, the process serves without rings for good, andnetRingStateanswers that step's errno. A failure here never exits: a ring is an optimisation, and the fallback is the unsandboxed path's. With both granted, a listener makes its rings itself, as it does unsandboxed. -
A seccomp denylist (open question 4),
SECCOMP_FILTER_FLAG_TSYNC:- an architecture other than the build's kills, and on x86-64 a number with bit 30 (x32) kills;
-
always:
ptrace,process_vm_readv,process_vm_writev,pidfd_getfdkill; -
without
net:socket,socketpair,connect,bind,listen,accept,accept4kill; -
io_uring, the same in both modes: without
net,io_uring_setup,_enterand_registerkill; withnetand withoutprocess.spawn,io_uring_setupandio_uring_registerkill, andio_uring_enter, the one call a premade ring needs, is let through only when its first argument is one of the descriptors step 5 wrote back, and kills otherwise, or always when no ring was made; with both, none kills; -
without
fs.write, or with it only beneath directories: the mode, owner, times and extended-attribute writes answerEPERM; -
without
process.spawn:execve,execveat,fork,vforkkill,clone3answersENOSYS, andclonekills unlessCLONE_THREADis set.
-
Marks itself applied;
nish_sandbox_check,@main's first call, exits 126 if it was not.
A failure in any step but 5 prints nish: --sandbox: <what> (<errno>) and
exits 126. The two modes differ only where Landlock is missing or too old: strict
exits 126 without Landlock, or below ABI 3 when fs.write is not granted
whole (TRUNCATE could not be withheld); best-effort runs and names what it
could not withhold. A scope directory that cannot be opened is the one
failure the modes treat differently outside Landlock's ABI: strict exits 126,
nish: --sandbox: cannot open the directory <dir> (<errno>), and best-effort
names it once and runs with nothing granted beneath it.
Findings
What the sandbox does not hold by design is stated in the threat model's "What the adversary keeps" list above, and the limits below are recorded rather than counted. One finding is counted, and it is fixed:
| ID | Severity | Where | What must hold | Status |
|---|---|---|---|---|
| SBX-1 | High | narrowSandbox in src/compilation.ts, nish_sandbox, nish_sb_spawn_open and nish_sb_spawn_once in runtime/runtime-sandbox.c, nish_spawn_start in runtime/runtime-os.c |
Under --sandbox, a dependency granted process.spawn=<program> must run only that program. |
Fixed, in two parts. The exec allowlist must grant EXECUTE on each granted program's ELF interpreter (PT_INTERP, e.g. /usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2) and #! interpreter, which the kernel needs to start it. Before the fix that loader was a spawn target too: spawnSync([loader, "/bin/echo", "x"]) was an allowed execve, the loader then opened /bin/echo under process.spawn's READ_FILE on / and mapped it, and Landlock checks EXECUTE at execve and open-for-exec, not at mmap, so any program ran. Now narrowSandbox writes an interpreter the grant does not name with a second leading / (//usr/lib/...), the same file to Landlock's O_PATH open; nish_sandbox records each marked entry's (st_dev, st_ino) before it confines the process and sets nish_spawn_sandboxed. Every spawn then resolves argv[0] as posix_spawnp would, opens it O_PATH, refuses (EACCES) a file whose identity is a marked entry's, and otherwise execs that same open file through /proc/self/fd/N, so the file checked is the file run: a rename or symlink swap between the check and the execve cannot substitute the loader. An interpreter the grant also names (process.spawn=sh beside a script) stays unmarked and spawnable. Before/after: sandbox dependency grants: a granted program's ELF loader is refused as a spawn target (SBX-1) (sandboxed the spawn returns -1; the same build without --sandbox runs echo), sandbox dependency grants: a second name for the loader is refused too (SBX-1), sandbox dependency grants: a granted #! script runs and its interpreter is refused as a spawn target (SBX-1) and sandbox dependency grants: a program the grant names stays spawnable when it is also another's interpreter (SBX-1) in tests/run.js. The second part. That first fix (#1447) kept the loader from the Nish program's own spawns and from nothing below them: Landlock's EXECUTE on the loader holds for the whole process tree, since the kernel needs it to start the granted program, so a granted program that executes a path from its arguments reached it all the same. With process.spawn=find granted, spawnSync(["find", ".", "-maxdepth", "0", "-exec", loader, "/any/binary", ";"]) ran the binary, and env, xargs, nice, timeout and nohup do the same; SBX-1 was recorded Fixed while this stayed open. Now every spawn under an exec allowlist is held by the kernel to one exec: nish_sb_spawn_once runs it on two threads of its own, the spawner installs a seccomp filter that sends execve and execveat to a user-notification listener (and answers a request for a second listener EBUSY) and calls posix_spawn, so the child inherits the filter; the supervisor answers the first notification, the child's own exec of the granted program, with "continue" and closes the listener, after which the kernel answers every exec in that child's subtree ENOSYS. The supervisor does the identity check and holds the target, the listener and its pipe in a descriptor table of its own (unshare(CLONE_FILES)), so no other thread of the program can close or replace one of them between the check and the exec. The descriptors the child's file actions name. Those actions are numbers: dup2(source, base + k) for the descriptors a builtin passes, and opens onto 1 and 2. A descriptor the hold makes takes the lowest free number, which would be a source another thread closed after the builtin read it, or 0, 1 or 2 where the program closed them, and the child would then be handed the listener or the pipe in place of the file the Nish code named. Three rules close that for every descriptor the hold makes, not one of them: (1) right after unshare, before it makes anything, the supervisor checks that each source is open in the private table, and refuses the spawn (EBADF) if one is not, so a source that is open is the caller's own and no later allocation can take its number; (2) every descriptor the hold makes (both pipe ends, the listener, the target) is moved by nish_sb_lift to base + n + 3 or above, past every number the actions read from 0, 1 and 2 or write, before any child exists; (3) both pipe ends are moved before either is tested, so the refusal line is never written to stderr while one of them sits on 2. The private table ends with the two threads, so nothing is left to close. Pinned by sandbox dependency grants: a program granted to <builtin> is started with no descriptor of the sandbox's, stdin and stderr closed (SBX-1) for spawnSync, spawnPiped, spawnPipedWithin, spawnWithFds and spawn, which run with 0 and 2 closed and count the non-file descriptors the child holds, the same with and without --sandbox; the race with another thread's close is not made deterministic by any test and rests on rule (1), listed under the branches the tests do not reach. Before/after, each against the same build without --sandbox, where the ungranted program runs: sandbox dependency grants: a program granted to <builtin> cannot hand the loader an ungranted binary (SBX-1) for each of spawnSync, spawnSyncTo, spawnPiped, spawnPipedWithin, spawnWithFds and spawn; sandbox dependency grants: a granted find cannot hand the loader an ungranted binary (SBX-1) and the same for env; sandbox dependency grants: a granted program cannot exec another granted program (SBX-1); sandbox dependency grants: a granted program cannot exec itself again (SBX-1); and sandbox dependency grants: a spawn whose child dies before its exec answers the error and does not hang (SBX-1). What the hold costs is under Limits. |
Limits
-
What runs before the preinit call. The loader,
LD_PRELOAD,LD_AUDIT, libc's start-up and IFUNC resolvers (open question 11). -
IOCTL_DEV below ABI 5. A device opened with
fs.readtakes anyioctlthere; strict runs anyway, since a terminal already on fd 0 gives the same on every ABI (open question 12). -
The scopes below ABI 6. Signals to the same uid and abstract Unix sockets are not scoped; strict runs anyway (open question 8).
nish:net'sunixConnectreaches abstract names, so below ABI 6 a sandboxed program grantednetcan connect to an abstract listener outside the sandbox; from ABI 6 that connect is -1 (EPERM), and its own abstract listeners still work. -
The premade rings are fixed at start. Under
netwithoutprocess.spawn, a process holdsnish.netRingsrings for its whole life, each with as many descriptor slots as the softRLIMIT_NOFILEit was launched with; a ring listener past them serves through the fallback, and rings a closed listener held are not made again. The ring flags loseSINGLE_ISSUERandDEFER_TASKRUN, which tie a ring to the thread that made it, the preinit thread here. Both are recorded in net-uring.md (NURING-30, NURING-31), with the silent premake failure (NURING-32). The probe still holds a premade set to the unsandboxed floor (NURING-33), and a spent set answers without counting (NURING-34). -
io_uring_enteris matched by descriptor number. The filter lets it take only the numbers of the rings step 5 made (NURING-35). seccomp cannot see the file behind a number, so the filter keeps each number on its ring instead:close,dup2anddup3naming a premade ring's number, or the keeper's, as the one they close or replace kill,dup3from the keeper excepted, which is how a closed ring listener's ring is dropped with the keeper, a ring that takes only NOP, left at its number;close_rangeanswers ENOSYS.dup,fcntl(F_DUPFD),recvmsgandpidfd_getfdtake only free numbers, which no ring's number ever is, and exec is killed (NURING-36, fixed). -
A pathname Unix listener needs
fs.write. Landlock counts binding a socket file as MAKE_SOCK, a write, sounixListenon a path undernetalone is -13 and leaves no file. The capability pass grantsnetfor the call and does not inferfs.write, since the path is data; a program that listens on a path asks for both, or uses an abstract name. Pinned by the twosandbox: granted net …checks intests/run.js. -
A pathname Unix connect is not confined. The sandbox uses no Landlock right that covers connecting to a pathname socket: a later ABI adds
LANDLOCK_ACCESS_FS_RESOLVE_UNIX, whichruntime/runtime-sandbox.cdoes not ask for, and the abstract-socket scope covers abstract names only.A sandboxed program granted
netcan thereforeunixConnectto any pathname listener outside the sandbox whose file it may write and whose directories it may search, such as a system daemon's socket;fs.readandfs.writedo not govern it. Recorded open: what bounds it is the socket file's mode and its directory's, which the listener sets, and a program that must not reach a host's daemons should not be grantednet. Not pinned by a test. -
A passed descriptor is not checked. Landlock rules apply when a path is opened, and
sendmsgandrecvmsgare not in the seccomp filter, so a file another process opens and sends withsendFdreaches a sandboxedrecvFdusable as it was opened, whateverfs.readandfs.writegrant; only making the socket it arrives on needsnet. A child started withspawnWithFdslikewise holds what its parent handed it. This is the first bullet of "What the adversary keeps", now reachable from the language (docs/security/runtime.md, RT-37 and RT-40): what bounds it is who is at the other end, whichpeerCredentialsnames (RT-39). Not pinned by a test. -
Scopes are resolved at build time. The directory is the realpath the compiler saw; the binary opens that path when it starts, so a directory renamed, removed or replaced by a symlink in between is opened as it then is (a symlink is followed, since only the launcher, who is trusted, can place one there), or refused if it is gone.
-
A directory cannot hold a comma, which separates
--allow's list. -
Metadata writes inside an
fs.writescope stayEPERM, since seccomp cannot see the path (open question 1(a)). -
The exec allowlist narrows EXECUTE alone.
process.spawnstill grants READ_FILE and IOCTL_DEV on/whole, as it did, since a program it starts reads its own libraries; only which files may be executed is narrowed. A program the allowlist names may itself be an interpreter, and what it is told to run in its own process it still runs:python3 -c,perl -eandawkexecute any code they are handed, with the process's whole reach of every other capability. What an interpreter can no longer do is start a second program (the next limit), so a spawnedshruns its builtins and nothing else. Grant a program that takes code only to a dependency that may run anything. The ELF loader and#!interpreter the allowlist adds for a granted program are refused as spawn targets (SBX-1, fixed above) unless the grant names them itself: a grant ofshbeside a script keepsshspawnable, held to its builtins like the script. -
One exec per spawn. Under an exec allowlist a spawned program cannot start a second program, granted or not, and neither can anything it forks:
find -exec,xargs,env <program>,nice,timeout,makeand a shell's non-builtin commands all fail (ENOSYS, which a shell reports as "not found" or "function not implemented"). A granted#!script still starts, since the kernel loads its interpreter inside the oneexecve, and then runs builtins alone; a script that opens with#!/usr/bin/env shdoes not, becauseenv's exec ofshis the second. The hold covers every program the Nish binary spawns, the root's own as well as a dependency's, whenever the build carries an exec allowlist; a build without one (noprocess.spawn=<program>grant, orprocess.spawngranted whole) takes no filter and is not held, and neither is a program grantedprocess.spawn=exec:<program>(the next limit). Granting that, orprocess.spawnwhole, are the two ways to let a spawned program start others. -
process.spawn=exec:<program>lifts the hold for that program, and that is an escape by design.narrowSandboxwrites the program with three leading slashes (///usr/bin/git, the same file to Landlock), andnish_sb_keep_marksrecords its identity as unheld; a spawn whose target is that file is started bynish_sb_startstraight from the supervisor, with no filter and no listener, though still from the private descriptor table, after the identity check, and through/proc/self/fd/N. Its subtree may exec anything Landlock's EXECUTE allows, which includes the ELF loader and#!interpreters of every granted program, and the loader runs any binaryprocess.spawn's READ_FILE reaches:exec:gitlets git startld.so /any/binary, and lets the Nish program do the same through git (git -c alias.x='!ld.so /any/binary' x). Grant it only to a dependency that may run anything. What it does not open: a program granted plainly is still held to its one exec, so it cannot start theexec:program and borrow its reach (the kernel answers its second execENOSYS); the loader named directly is still refused (SBX-1); and a build with noexec:grant carries no///entry, so its IR and its runtime behaviour are what they were. The exec allowlist is the program's, not a package's, so another dependency grantedprocess.spawn=<anything>cannot reach theexec:program through its own subtree (held), but the Nish code of any package with aprocess.spawngrant may spawn it by a computed path, since the Nish program's own spawns are checked against the allowlist, not against which package made them. A program granted both ways isexec:; a file marked both as a kept interpreter and asexec:is refused, the stricter mark winning. The lock file recordsprocess.spawn=exec:gitas its own text, so moving a dependency fromprocess.spawn=gitto it is a widening NL2593 reports. "Both ways" is decided by file identity, not by path: the runtime looks a spawn target up by device and inode, so a second name for theexec:program, a symlink or a hard link (Debian's/usr/lib/git-core/git-*are hard links ofgit), granted plainly, is that program and starts unheld. It opens nothing a computed path to theexec:program does not. -
What the hold needs, and where it is missing. A seccomp user notification listener (Linux 5.0) and its "continue" answer (5.5). Where the filter cannot be installed (
EINVALon an older kernel,EBUSYwhere an ancestor's filter refuses a listener,ENOMEM) or "continue" is refused, the spawn is refused: the builtin answers a negative errno or its failure value, and one line on stderr saysnish: --sandbox: cannot hold a spawned program to one exec, so the spawn is refused (<errno>). That is so in--sandbox=best-effortas well: nothing falls back to an unheld spawn. A refused spawn returns; it does not wait. The child holds a copy of the listener until its exec commits, so closing the supervisor's copy would leave a child whose exec was notified and not answered blocked in it, and the spawn waiting on that child for good. Where "continue" is refused the supervisor therefore answers the same notification with an error (ENOSYS, an answer every kernel with a listener takes), which fails the child's exec; if that answer is refused as well it kills the child, reaps it and answers-ECHILDitself (there is no child left to wait for, and the number tells the two paths apart). A notification gone before its answer (ENOENT: the child was killed, or a signal restarted its exec) sends the supervisor back to wait for the next one or for the spawner's answer. Pinned by the twoa spawn whose exec cannot be answered "continue" is refused and does not hangchecks below, against a runtime built with-DNISH_SANDBOX_SIMULATE_NO_CONTINUE. The number the builtin answers is not always the errno the line prints, by design: a failedunshare,pipe2, descriptor move orpthread_createanswers-EAGAINand a refused "continue"-ENOSYS(-ECHILDwhere the child had to be killed), and a failed descriptor move printsEMFILEwhateverfcntlsaid; the line carries the cause. Eitherpthread_createfailing prints the line with its errno. The hold also needsunshare(CLONE_FILES)andpipe2, and a failure of either prints the same line. Docker's default seccomp profile is such a place: it allowsunshareonly to a container withCAP_SYS_ADMINand answersEPERMotherwise (moby'sprofiles/seccomp/default.json, read at v27.3.1;seccompandpipe2it allows), so in a defaultdocker runevery spawn under an exec allowlist is refused with(EPERM). The build still runs and its other confinement holds; to spawn there, run the container with a profile that allowsunshare(or--cap-add SYS_ADMIN, which is far more than this needs), or grantprocess.spawnwhole. Any other runtime whose profile deniesseccomp(2)orunshare(2)to its payload refuses the same way. Not run under Docker by any test. -
A sandboxed Nish program spawned by one cannot spawn. The filter refuses a second listener because the kernel lets the newest filter's "continue" stand for every older one, so a spawned program with a listener of its own would answer its children's execs itself. A granted program that is itself a
--sandboxbuild with an exec allowlist therefore has each of its spawns refused (EBUSY), where the one-exec hold would refuse the exec anyway. Any other program that needs a listener (a container runtime, a sandboxing browser) fails the same way when spawned. -
No other route gives a descendant a listener, or an answer of its own. Read against
kernel/seccomp.c: a listener comes only fromseccomp(2)withSECCOMP_FILTER_FLAG_NEW_LISTENER, whose bit the filter tests, so theTSYNCwithTSYNC_ESRCHspelling (flags 25) is refused with the plain one (8);prctl(PR_SET_SECCOMP)installs with no flags and cannot ask for one; the x32 numbers forseccompandexecveare killed by the same head as the process's filter, as is a foreign architecture. A descendant may still stack filters without a listener. One that answers an execERRNOorKILLoutranksUSER_NOTIFand only refuses more;ALLOW,LOGandTRACErank below it and change nothing; one that answersUSER_NOTIFwith no listener of its own getsENOSYS. Pinned bya granted program cannot install a seccomp listener of its ownbelow, for flags 8 and 25. -
Signals do not reach the helper threads. Both are created under a full mask, restored on the calling thread straight after, and the child starts with the caller's mask, not theirs. Without that, a handler chosen to run on the supervisor or spawner would act in the private descriptor table:
signalFd's handler writes one byte to its pipe by number, and in the private table a pipe thatsignalFdmade on another thread after theunshareis not there, its number unopened or given to the listener or the spawn's pipe, so the program's own wake would be lost or the supervisor woken with a byte it reads as the spawner's answer (-EIO, a refused spawn, never a held-open one).SIGKILLandSIGSTOPare the kernel's and act on the process whole. -
Who can raise the notification. The filter is the spawner thread's alone, and that thread makes no
execve: only the childposix_spawncreates carries it before the listener closes, so the one "continue" goes to that child's first exec, of/proc/self/fd/N, the file the supervisor checked. A child that dies in a redirect before its exec notifies nobody; the supervisor is woken by the spawner's pipe instead, closes the listener and answers the error. -
"Continue" trusts the child's memory. The kernel re-reads the path when it continues the call, from the child's memory, which until the exec is the Nish process's own (
posix_spawnclones withCLONE_VM). The path isjob.proc, on the stack of the thread that called the builtin, which is blocked until the spawn answers; another thread of a memory-safe Nish program cannot write there, and no linked C can either:narrowSandboxemits no exec allowlist for amainthat reachesffi. -
What a spawn costs under an exec allowlist. Two threads created and joined, a copy of the descriptor table, a pipe, a filter and two ioctls per spawn, beside reading
PATHto resolve the program (a changedPATHcan only find another file, which is checked the same way) and needing/procmounted to exec through/proc/self/fd/N. The child is left that descriptor (anO_PATHone, not close-on-exec, since theexecveneeds it); it is opened in the supervisor's private table, so a spawn on another thread no longer inherits it. The private table is a copy, though: while a spawn is in flight its two threads hold a duplicate of every descriptor the process had, so a pipe another thread closes in that window reads end-of-file only once the spawn has answered. A#!script started this way sees/proc/self/fd/Nas its$0. More than 16 marked entries refuses every spawn rather than check some of them. All of it is armed whenever the build carries an exec allowlist, Landlock or not: under--sandbox=best-efforton a kernel without Landlock, where exec is otherwise not confined, the hold and the refusal still apply. -
spawnSyncToopens its files in the child. Its stdout and stderr files are opened by the child before the exec, under the sandbox'sfs.writerules: a package grantedprocess.spawn=<program>and no write scope that holds the file gets-1and no program runs. That is Landlock's refusal, not the hold's, and it predates it. -
The allowlist is the build's. Each program is the realpath the compiler found on
PATH(or from the root package's directory), and its interpreter is read from the file then; a program replaced after the build with one that needs another interpreter fails to start (EACCES), which narrows, never widens. -
Non-Linux. Both symbols print
nish: --sandbox: this platform has no sandboxand exit 126, so a.llbuilt for Linux and linked elsewhere refuses to run rather than run unconfined.
Branches the tests do not reach
Each is a kernel answer the test machines do not give; each fails closed:
-
capget/capsetfailing,PR_CAPBSET_DROPorPR_CAP_AMBIENT_CLEAR_ALLfailing other thanEINVAL, and each "survived the drop" read-back; -
the Landlock ABI probe failing with an errno other than
ENOSYS,EOPNOTSUPPorEPERM;landlock_create_ruleset,open("/"),landlock_add_ruleorlandlock_restrict_selffailing; - ABI 3 and 4 (exercised only as the simulated 0, 1 and 2 and the machine's own), and the best-effort line's IOCTL_DEV and scope names on a real kernel below ABI 5 or 6;
-
a scope directory that opens but is refused by
landlock_add_rule(EBADFD,EINVAL), and a scope list longer than one directory at run time (the compiler emits it,tests/run.jschecks the constant, no run opens two); -
SECCOMP_GET_ACTION_AVAILrefusingKILL_PROCESS, andSECCOMP_SET_MODE_FILTERfailing; PR_SET_NO_NEW_PRIVSfailing;- the aarch64 tables, which compile but run on no test machine;
-
in a spawn under an exec allowlist:
unshareorpipe2failing and the "cannot hold" line each prints; a source descriptor of the file actions closed by another thread before the supervisor's snapshot (EBADF; the builtins hand over descriptors they opened or checked themselves, so only a racingfileClosereaches it);nish_sb_liftfailing for a pipe end, the listener or the target (EMFILE); eitherpthread_createfailing and the "cannot hold" line each prints;posix_spawnattr_initfailing (ENOMEM, returned asposix_spawn's error); a signal arriving while a spawn is in flight (the two mask checks below show what the child starts with, not that no handler ran on a helper: that follows from the mask the threads are created under, and no check makes the delivery deterministic); the filter refused (EINVAL,EBUSY,ENOMEM) and the "cannot hold" line it prints (the nested case needs a second sandboxed Nish binary as the granted program); a refused "continue" on a real kernel before 5.5 (reached only as the simulated refusal); a notification gone before it is read or answered (ENOENT: a child killed while it waited, or its exec restarted by a signal), after which the supervisor polls again and so cannot wait on a child that is gone, the spawner's pipe waking it;pollfailing, which is retried, not abandoned (EINTRandENOMEMpass;EFAULTandEINVALcannot occur, the array being the supervisor's own two entries, under any descriptor limit that let the listener exist);NOTIF_RECVfailing other thanENOENT, which polls again the same way (its argument is a zeroed struct of the supervisor's own, soEFAULTandEINVALcannot occur);killorwaitpidfailing after both answers were refused (the pid is the notifying child's, a child of this process no other thread has been told of); a short or interrupted read of the spawner's pipe (-EIO, and theEINTRretries ofread); -
for a
process.spawn=exec:<program>target:nish_sb_startfailing on the supervisor's own path (itsposix_spawnerror, as the spawner's would be); a file marked both as a kept interpreter and asexec:, which is refused (the compiler writes one mark per program, so only two names for one file reach it); and more than 16 marked entries withexec:ones among them, which refuses every spawn the same as more than 16 interpreters; - the non-Linux stubs.
Tests
The sandbox section of tests/run.js (node tests/run.js sandbox) and the
--sandbox block of tests/nish/cli.ts:
sandbox_hello: IR matches goldensandbox_hello: llvm-as accepts IRsandbox_hello: --emit-panics changes no byte of the IR, and agrees with itsandbox_hello: native output matches .outsandbox: fork from ffi without process.spawn dies of SIGSYS (strict)sandbox: execve from ffi without process.spawn dies of SIGSYS (strict)sandbox: socket from ffi without net dies of SIGSYS (strict)sandbox: io_uring_setup from ffi without net dies of SIGSYS (strict)sandbox: process_vm_writev into the parent dies of SIGSYS (strict)sandbox: ptrace(PTRACE_ATTACH) on the parent dies of SIGSYS (strict)sandbox: an x32 socket from ffi dies of SIGSYS (strict)sandbox: fork from ffi without process.spawn dies of SIGSYS (best-effort)sandbox: execve from ffi without process.spawn dies of SIGSYS (best-effort)sandbox: socket from ffi without net dies of SIGSYS (best-effort)sandbox: io_uring_setup from ffi without net dies of SIGSYS (best-effort)sandbox: process_vm_writev into the parent dies of SIGSYS (best-effort)sandbox: ptrace(PTRACE_ATTACH) on the parent dies of SIGSYS (best-effort)sandbox: an x32 socket from ffi dies of SIGSYS (best-effort)sandbox: without --sandbox the same probe forks (the control)
The premade rings of step 5 and the io_uring rows of step 6 (WP63 S3). The
checks marked (<mode>) run once under strict and once under
best-effort, with the same result, since the rule does not depend on the
mode:
sandbox: a main that reaches NET_LISTEN_RING with net asks for 1 ring (nish_sandbox's last operand is 1)sandbox: a main that reaches net but never the ring bit asks for no ring (nish_sandbox's last operand is 0)sandbox: a main that also reaches process.spawn passes its ring count on (nish_sandbox's last operand is 1)sandbox: a main without net asks for no ring (nish_sandbox's last operand is 0)sandbox: tcpListenFlags flags \` ask for ring(s) , for8(1),1(0),NET_LISTEN_RING | 1(1),(1 | 2)(0) andtoI32(process.argv.length)` (1: a value the compiler cannot fold may ring)sandbox: \nish.netRings` 3 asks for 3 ringsand the same for64`sandbox: \nish.netRings`is refused where package.json writes it , NL3058, for0,65,-1,1.5and"4"`sandbox: without --sandbox a ring program premakes no ring (the control)sandbox: without --sandbox io_uring_register and io_uring_enter reach the kernel (the control)sandbox: io_uring_setup from ffi with net and without process.spawn dies of SIGSYS (<mode>)sandbox: io_uring_register from ffi with net and without process.spawn dies of SIGSYS (<mode>)sandbox: io_uring_register from ffi without net dies of SIGSYS (<mode>)sandbox: io_uring_enter from ffi without net dies of SIGSYS (<mode>)sandbox: io_uring_enter from ffi with net on a descriptor that is no premade ring dies of SIGSYS (<mode>)sandbox: io_uring_enter from ffi with net and no ring premade dies of SIGSYS (<mode>)sandbox: with net and process.spawn io_uring_enter from ffi reaches the kernel (<mode>)sandbox: without --sandbox a ring inherited across exec is entered (the control)sandbox: a ring a parent made unconfined and passed across exec cannot be entered: SIGSYS (<mode>)sandbox: without net the ring probe answers the refusal, not SIGSYS (<mode>)sandbox: a main without net, or with net and never the ring bit, makes no ring (<mode>)sandbox: with net and process.spawn io_uring_setup from ffi is not killed and no ring is premade (<mode>)sandbox: a main that reaches NET_LISTEN_RING holds 1 premade ring (<mode>)sandbox: a premade ring completes a NOP (<mode>, the control)sandbox: a premade ring refuses IORING_OP_<op> with EACCES (<mode>), for SOCKET, CONNECT, OPENAT, READ, WRITE, SENDMSG, MSG_RING and URING_CMDsandbox: a premade ring refuses IOSQE_<flag> with EACCES (<mode>), for IO_DRAIN, IO_LINK, IO_HARDLINK and ASYNCsandbox: a premade ring takes <op> past its restriction (<mode>), for ACCEPT, RECV, SEND, CLOSE, ASYNC_CANCEL, and RECV with FIXED_FILE, with BUFFER_SELECT and with CQE_SKIP_SUCCESS (each completes with whatever its arguments earn, never EACCES)sandbox: a sandboxed NET_LISTEN_RING listener serves a loopback connection through a premade ring (<mode>)sandbox: \nish.netRings` 3 premakes 3 rings`sandbox: on a kernel that refuses DEFER_TASKRUN no ring is premade and the probe answers EINVAL (NURING-33)net_ring: under --sandbox a full set of premade rings answers -23 and makes no ring past them, in thenet_ringsection
Where this kernel refuses io_uring_setup to an unconfined process, the
premade-ring checks are skipped by name (sandbox: this kernel refuses io_uring_setup unconfined; ...) rather than passed; the kill checks still run.
sandbox: a process.spawn-granted program runs a childsandbox: chmod, utimensat and setxattr without fs.write fail EPERMsandbox: open from ffi without fs.read is refusedsandbox: a program whose main reaches fs.read opens /etc/passwdsandbox: a constructor in an ffi object runs confined, and the sandbox's preinit entry runs firstsandbox: a device ioctl without process.spawn is refusedsandbox: a spawn redirect without fs.write fails in the childsandbox: a granted program runs as it does unsandboxedsandbox: strict refuses without Landlock (ABI 0)sandbox: best-effort warns without Landlock (ABI 0)sandbox: strict refuses below ABI 3 without fs.write (ABI 1)sandbox: best-effort names TRUNCATE below ABI 3, and still confines the open (ABI 1)sandbox: strict refuses below ABI 3 without fs.write (ABI 2)sandbox: best-effort names TRUNCATE below ABI 3, and still confines the open (ABI 2)sandbox: strict runs below ABI 3 with fs.write, which grants TRUNCATE anyway (ABI 2)sandbox: strict refuses below ABI 3 with fs.write=<dir>, which grants nothing beneath / (ABI 2)sandbox: fs.read=<dir> reads inside and not outsidesandbox: an ffi main is widened by the policy's fs.read=<dir>, and held to itsandbox: a missing scope directory refuses strict, naming itsandbox: best-effort names a missing scope directory once and reads nothingsandbox: fs.write=<dir> creates inside and not outside(ABI 3 or later)sandbox: chmod, utimensat and setxattr inside an fs.write=<dir> scope still fail EPERM(ABI 3 or later)sandbox: a scope is a NUL-ended list constant passed to nish_sandbox, and llvm-as accepts itsandbox: a libc that skips .preinit_array fails closedsandbox: a process holding capabilities drops themsandbox: a threaded program without process.spawn still runs its poolsandbox: NISH_NUM_THREADS still lowers the pool (1)sandbox: NISH_NUM_THREADS still lowers the pool (3)sandbox: nish run --sandbox runs the program, and the child it starts, with no_new_privs and a seccomp filtersandbox: the wasm targets emit no call (wasm32)sandbox: the wasm targets emit no call (wasm32-wasi)sandbox: the wasm profile refuses sandboxed IRsandbox: without the flag the IR is the sandboxed IR less the sandbox's linesruntime objects: linking sandbox_hello.ll against the default runtime gives the bytes the sources doruntime objects: linking none-abi0.ll against the runtime built with -DNISH_SANDBOX_SIMULATE_ABI=0 gives the bytes the sources doruntime objects: linking none-abi1.ll against the runtime built with -DNISH_SANDBOX_SIMULATE_ABI=1 gives the bytes the sources doruntime objects: linking none-abi2.ll against the runtime built with -DNISH_SANDBOX_SIMULATE_ABI=2 gives the bytes the sources do`--sandbox --emit-napi` is a usage error, exit 2`--sandbox` on an entry with no `main` is a usage error, exit 2a directory scope beside `--sandbox` is accepted, exit 0-
the scope refusals, each word for word, exit 2: a scope without
--sandbox, a scope in--deny, a scope ofnet, a directory that does not exist, and a path that is a file tests/wordings/nl3044_sandbox_darwin(the darwin refusal, word for word)-
tests/runtime-budgets.js:RUNTIME_SANDBOX_TEXT_BUDGET, the ceiling on the unit's.text -
the
sandbox dependency grantsblock (node tests/run.js "sandbox dependency grants"), ontests/link/sandbox_dep_fs_scopedandsandbox_dep_exec_allowlist, each before/after:sandbox dependency grants: a dependency granted fs.read=<dir> reads inside it and not /etc/passwd(unscoped, the same build reads it),sandbox dependency grants: the wrapper passes the grant's real directory as the fs.read scope,sandbox dependency grants: a dependency granted process.spawn=true runs true and cannot exec echo(without--sandbox, it runsecho),sandbox dependency grants: the exec allowlist names the granted program by its absolute path; onsandbox_dep_fs_write_scoped:sandbox dependency grants: a dependency granted fs.write=<dir> writes inside it and not beside it(without--sandbox, it writes beside it; skipped below Landlock ABI 3),sandbox dependency grants: the wrapper passes the grant's real directory as the fs.write scope; and SBX-1's, each before/after against the same build without--sandbox:sandbox dependency grants: a granted program's ELF loader is refused as a spawn target (SBX-1),sandbox dependency grants: a second name for the loader is refused too (SBX-1), onsandbox_dep_exec_allowlist;sandbox dependency grants: a granted #! script runs and its interpreter is refused as a spawn target (SBX-1), onsandbox_dep_exec_script; andsandbox dependency grants: a program the grant names stays spawnable when it is also another's interpreter (SBX-1), onsandbox_dep_exec_interpreter_granted; and its second part's, onsandbox_dep_exec_oncewith a helper the check builds and grants, which execs its arguments:sandbox dependency grants: a program granted to spawnSync cannot hand the loader an ungranted binary (SBX-1)and the same check forspawnPiped,spawnPipedWithin,spawnWithFdsandspawn,sandbox dependency grants: a granted program cannot exec itself again (SBX-1),sandbox dependency grants: a granted program that execs nothing runs as before,sandbox dependency grants: a spawn whose child dies before its exec answers the error and does not hang (SBX-1),sandbox dependency grants: a spawn whose exec cannot be answered "continue" is refused and does not hang: the supervisor fails the child's exec (SBX-1)and... the supervisor kills and reaps the child (SBX-1)(the runtime built with-DNISH_SANDBOX_SIMULATE_NO_CONTINUE=1and=2; a hang ends in the run's timeout and fails the check; the builtin answers -38 for the first and -10 for the second),sandbox dependency grants: a granted program cannot install a seccomp listener of its own (SBX-1)(the helper asksseccomp(2)for a listener with flags 8 and 25 and both answerEBUSY, where the unsandboxed control answers 0),sandbox dependency grants: a program granted to spawnSync starts with the caller's signal mask (SBX-1)and the same forspawn,sandbox dependency grants: a granted find cannot hand the loader an ungranted binary (SBX-1)and the same forenv,sandbox dependency grants: a granted program cannot exec another granted program (SBX-1),sandbox dependency grants: a program granted exec: starts the loader with an ungranted binary, and itself (WP40 §2a)and the same for a programgranted exec: and plainly(each against the build without--sandbox, and with the loader named directly still refused),sandbox dependency grants: a program granted plainly beside another's exec: grant is held to its one exec (WP40 §2a),sandbox dependency grants: a hard link of a program granted exec:, granted plainly, is that program and starts unheld (WP40 §2a), andsandbox dependency grants: an allowlist with no exec: grant marks nothing /// (WP40 §2a); onsandbox_dep_exec_optin,sandbox dependency grants: env granted exec: runs another granted program (WP40 §2a); and onsandbox_dep_exec_once_to, whose grant adds the write scope the child's redirect needs:sandbox dependency grants: a program granted to spawnSyncTo cannot hand the loader an ungranted binary (SBX-1)(skipped below Landlock ABI 3). Each is skipped, and counted, whereclang, the loader or the tool is missing
Checks CI does not run
-
sandbox: a process holding capabilities drops themneeds an unprivileged user namespace (unshare -r). GitHub's Ubuntu 24.04 runners setkernel.apparmor_restrict_unprivileged_userns=1, sounshare -rfails there and the section printsSKIP sandbox: no unprivileged user namespace; the capability drop did not runinstead. It runs, and passes, on a machine that allows unprivileged user namespaces; on CI the drop is proved only by its read-back, which fails closed. -
sandbox: a pool without fs.read keeps to a cgroup quota of N CPUs, primed before confinementneeds a private mount namespace in a user namespace (unshare -rm) to put a tmpfs over/sys/fs/cgroup, so it is refused on those runners for the same reason and printsSKIP sandbox: no mount namespace with a cgroup tmpfs; the primed CPU count was not checked. It also skips on a host with fewer than 3 CPUs, or more than 65, where the pool's own cap of 64 decides the count. It runs, and passes, where the drop above does.

