The sandbox

--capabilities tells you what a program can reach, and --allow / --deny refuse at compile time a program that reaches more than you grant. Neither holds the program once it runs: a declare function into C can open any file or socket libc can. --sandbox closes that gap on Linux. The binary asks the kernel, before any of your code runs, to refuse everything its main does not reach — for your Nish code, your dependencies, every C function you call and every C constructor alike.

The rules are in the reference, under The sandbox.

Building a sandboxed program

Pass the flag where you would build or run the program:

nish --link app.ts --sandbox -o app
nish run --sandbox app.ts
nish app.ts --sandbox          # IR only: the .ll carries the sandbox

Take a program that reads one file and does nothing else:

import { readFileSync } from "nish:fs"

export const main = (): number => {
  const text = readFileSync("/etc/hostname")
  console.log(text.length > 0)
  return 0
}

Its main reaches fs.read and nothing more (nish run --capabilities prints capabilities: fs.read (not deterministic)), so built with --sandbox it can still read any file the user can, but it cannot write one, start a process or open a socket — not from Nish, and not from a C library it links.

What is withheld

Each capability main does not reach is withheld:

Not reached What the kernel refuses
fs.read opening a file or a directory to read it
fs.write writing, creating, removing, renaming and truncating files, and changing their mode, owner, times or extended attributes
process.spawn starting a program or forking a process (threads are fine), and executing a file
net creating, connecting, binding and accepting sockets, and every io_uring call (reaching it lets a ring listener use the rings made for it at start; see Ring listeners)

Reaching process.spawn grants back executing, reading and device ioctls on every file beneath /, since a child has to load its program and libraries. So a program that reaches process.spawn can read any file the user can, even when its main does not reach fs.read.

A Unix-domain listener on a path makes a socket file, which the kernel counts as a write: under net alone, unixListen("app.sock", …) answers -13 and makes nothing. Reaching net does not reach fs.write for you, because the path is data the compiler cannot see. Reach fs.write as well, or listen on an abstract name ("@app"), which makes no file (Unix sockets).

Connecting is different. The kernel has no rule for connecting to a socket file, so a program that reaches net can unixConnect to any Unix socket on a path whose permissions let the user in, a system daemon's included, with or without fs.read or fs.write. The sandbox stops a connect only to an abstract name created outside it, and only from Landlock ABI 6 (below). If the program must not talk to the machine's daemons, do not let main reach net.

A descriptor that arrives already open is not checked either. Landlock rules apply when a path is opened, so a file another process opens and passes over a Unix socket with sendFd reaches recvFd usable as it was opened, whatever fs.read or fs.write say; sending and receiving such a descriptor are not filtered, only making the socket is. The same holds for what a sandboxed parent hands a child with spawnWithFds: the child holds whatever the parent held. Treat a socket that can pass descriptors as a door into the sandbox, and check who is on the other end with peerCredentials (Unix sockets).

A few things are refused whatever main reaches: attaching to, reading or writing another process (ptrace, process_vm_readv, process_vm_writev) and taking its descriptors (pidfd_getfd), x32 system calls and system calls of another architecture (a 32-bit int 0x80), and io_uring unless the program reaches net (and then only io_uring_enter, and only on the rings made at start for ring listeners, matched by descriptor number, unless it reaches process.spawn too; see Ring listeners). On a kernel whose Landlock is ABI 6 or later, so is signalling a process outside the sandbox and connecting to an abstract Unix socket created outside it, even when main reaches signal; the program can still signal itself. The other capabilities — clock, entropy, env, exit, tty, ffi, unsafe — withhold nothing.

A refused file operation fails with an error your program sees, as a missing permission would. A refused process or socket call ends the program with SIGSYS, which a shell reports as exit status 159:

$ ./app
Bad system call
$ echo $?
159

Granting one directory

fs.read and fs.write reach every file the user can. Under --sandbox you can grant either beneath one directory instead, with a scope in --allow:

nish --link app.ts --sandbox --allow fs.read=/srv/data -o app
nish --link app.ts --sandbox --allow fs.read=/srv/data,fs.write=/srv/data/out -o app

Built with --allow fs.read=/srv/data, the program above could read /srv/data/notes.txt but no longer /etc/hostname: that open fails with EACCES, as a missing permission would. Name a capability more than once to grant it beneath several directories (--allow fs.read=/srv/a,fs.read=/srv/b).

A scope is an --allow list like any other, so it also names every other capability the program reaches; leaving one out is refused at compile time, as without the scope. If the program calls C (ffi), the scopes you grant are what the C code can reach too.

Each directory is resolved, symbolic links and all, when you build, and must exist then:

compile: `fs.read=/srv/dta` names no directory; a scope is a directory that exists when the program is built

Only fs.read and fs.write take a scope, only in --allow, and only with --sandbox, the one thing that enforces it; each of the others is refused with exit status 2. A directory with a comma in its name cannot be named.

Granting a dependency its capabilities

A package you install under node_modules may read files, write them, start programs, reach the network, call C or use nish:unsafe only when your own package.json says it may. Those six, fs.read, fs.write, process.spawn, net, ffi and unsafe, are the gated capabilities. Without a grant, the build stops in the dependency's source, naming the package, the capability and the chain of calls that reaches it:

node_modules/pkg_http/src/index.ts:6:10: error: the dependency `pkg_http` reaches `net` through `dial`, which the root package does not grant it; grant it with "nish": { "capabilities": { "dependencies": { "pkg_http": ["net"] } } } — the chain that reaches it: node_modules/pkg_http/src/index.ts:6:10 calls netAddress

Grant each one by the package's name, under nish.capabilities.dependencies in the package.json nearest above your entry file. A package that reads files, runs tools, writes files and opens pull requests needs all of this:

{
  "nish": {
    "capabilities": {
      "dependencies": {
        "@amritk/vector": ["fs.read", "fs.write", "process.spawn", "net", "unsafe"]
      }
    }
  }
}

Only your own package.json grants. A dependency's package.json cannot grant itself anything, and neither can --allow on the command line. Every other capability, such as clock or env, needs no grant. The package.json reference lists every field Nish reads, with each error a mistake in it gets, and nish-capabilities.lock.json records what each dependency reaches, so an upgrade that reaches something new stops the build.

Narrowing what a dependency is granted

The specification's rules are in A dependency's capabilities. A grant can name what it is for, after an =: a directory for fs.read and fs.write, a program for process.spawn, an IP address (or a Unix socket's absolute path, such as net=/run/app.sock) for net.

{
  "nish": {
    "capabilities": {
      "dependencies": {
        "pkg_tool": ["fs.read=./data", "process.spawn=git", "net=127.0.0.1"]
      }
    }
  }
}

The directory is found from the folder your package.json is in, the program on your PATH, and both must exist when you build. A host is an address, not a name to look up. A grant without an = grants the whole capability, as it always did.

The build checks what it can see. A dependency that passes a fixed path, program or address outside its grant stops the build, at that string:

node_modules/pkg_conf/src/index.ts:2:38: error: the dependency `pkg_conf` hands `readFileSync` "/etc/passwd", which its `fs.read` grant does not cover: it is granted fs.read=data; name it in the grant, or grant `fs.read` whole

A path or program the dependency works out while it runs is beyond the build. Build with --sandbox and the kernel holds it instead: the granted directories become the program's fs.read and fs.write scopes, as --allow fs.read=<dir> makes them, and the granted programs the ones it may start (with the loader they need, below). A dependency granted fs.read=./data that is handed /etc/passwd at run time gets an error from readFileSync; one granted process.spawn=git that tries to start sh gets -1 from spawnSync.

The sandbox narrows a capability this way only when it can tell the grant is all of it: every dependency that reaches it names an argument, your own code does not reach it, --allow gives it no scope of its own and main does not call C. Otherwise the capability stays whole, as it was before. The scopes hold for the whole process, not one package: any dependency that reads files may read every granted directory.

Starting a program that is not a static binary needs its loader, such as /usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2, and a script needs the interpreter its #! line names, so the kernel may run those too. A dependency cannot start them itself: under a process.spawn=git grant, spawnSync([loader, "/bin/echo", "x"]) fails, as does spawnSync(["sh"]) under a grant of a #!/bin/sh script, unless the grant names sh as well. To make that check, a spawn under --sandbox opens the program first and runs the file it opened through /proc/self/fd, so /proc must be mounted, and a script started that way sees a /proc/self/fd/N path as its $0. A program the grant names may still be an interpreter: python3 runs any code it is handed inside its own process, and a shell runs its builtins. Grant one only to a dependency you have read.

A program started under such a grant cannot start another. The kernel holds it, and everything it forks, to its own start, so find -exec, xargs, env <program>, timeout and make fail where they would run a second program, a granted one included. A granted shell script still starts and runs its shell's builtins (echo, test, read); any other command in it fails, and a script that opens with #!/usr/bin/env sh does not start at all, because env starting sh is already the second program: name the interpreter's own path on the #! line. This needs Linux 5.5; on an older kernel, or inside a container that forbids the calls it takes, every spawn under such a grant fails and says so on stderr, in --sandbox=best-effort too. Docker's default seccomp profile is one that forbids them: there the line ends (EPERM). The same holds for a granted program that is itself a Nish program built with --sandbox and such a grant: its own spawns fail.

To let one program start others, write exec: before it in the grant:

{
  "nish": {
    "capabilities": {
      "dependencies": {
        "pkg_build": ["process.spawn=exec:make", "process.spawn=cc"]
      }
    }
  }
}

Under --sandbox, make and everything it starts may run any program on the list, and also the loader and the #! interpreters the list lets the kernel run, which start any binary the program can read. So exec: is close to granting process.spawn whole for that program: grant it only to a dependency that may run anything. cc above is still held to its own start, and so is every program granted without exec:, which cannot borrow make's reach by starting it. A program written both ways counts as exec:, and "the same program" means the same file: another name for make, a symlink or a hard link, granted plainly, is make and starts as make does. process.spawn=exec: with no program after it stops the build, as a program that is not on your PATH does. The other way to let a dependency's programs start others is to grant it process.spawn whole, which lifts the list of programs with it.

Addresses are checked at build time only. The kernel cannot see which address a socket call is given, so a net=<host> grant does not stop a dependency that builds its address at run time. Grant net to a dependency you have read.

nish-capabilities.lock.json records the arguments too ("pkg_conf": ["fs.read=data"]). Widening a grant past them — a new directory, program or address, exec: before a program, or the whole capability — stops the build until you review it and run --update-capability-lock again.

If the directory is gone when the program runs, --sandbox refuses to run, status 126, naming it:

nish: --sandbox: cannot open the directory /srv/data (ENOENT)

and --sandbox=best-effort runs with nothing granted beneath it, saying so once.

Inside a write scope a program can create, write, rename and remove files, but changing a file's mode, owner, times or extended attributes is still refused (EPERM): that check cannot see which directory a file is in. A program that reaches process.spawn can still read every file beneath /, scope or not, as above.

Ring listeners

A server that listens with NET_LISTEN_RING accepts into io_uring rings. Under --sandbox, when main reaches net but not process.spawn, those rings are made before anything is confined, and making more is refused afterwards. Say how many rings to make in the root package.json (an integer from 1 to 64; 1 when it is not written):

{ "nish": { "netRings": 2 } }

netRings counts rings, not listeners. Each ring holds as many connections as the soft descriptor limit (ulimit -n) the program started with, at most 16,384, and a busy listener takes another ring each time the ones it holds are full, so one listener can use several. Once every ring made is in use, a listener whose rings are full answers -23 from tcpAccept until a connection closes, and a ring listener opened after that serves through plain descriptors. To size it, divide the connections the process will hold at once by the smaller of ulimit -n and 16,384, and round up: 40,000 connections under a limit of 65,536 need 3 rings.

A ring a closed listener held is not given back to the pool, so a program that closes and reopens ring listeners spends rings each time (NURING-31). The rings' memory is held for the life of the process whether a listener uses them or not (NURING-32).

Each premade ring takes only accepting, receiving, sending, closing and cancelling; anything else submitted to it fails with -13. The rings' descriptors are held for the program: closing one, or putting another descriptor at its number with dup2 or dup3, ends the process with SIGSYS (the one dup3 allowed is from the keeper, a ring that takes only NOP, which the runtime puts at a closed listener's ring's number), and close_range fails with ENOSYS. Other descriptors are not affected (NURING-36). When a kernel is too old for the rings, or a descriptor limit too low to make them, every ring listener serves through plain descriptors, and netRingState() answers why. A ring listener that falls back because the rings made are all taken does not change netRingState(): once a ring listener has opened, it stays 1. Any other value of netRings is refused with NL3058. The rules are in The sandbox.

When the sandbox cannot be applied

The sandbox needs Linux's Landlock and seccomp. A program that cannot apply it prints one line and exits with status 126, before main runs:

nish: --sandbox: this kernel has no Landlock; build with --sandbox=best-effort to run with seccomp alone

--sandbox=best-effort runs anyway on such a kernel, with what it could apply, and says what it could not:

nish: --sandbox: no Landlock, files are not confined

A write scope needs Landlock ABI 3 (Linux 6.2); on an older kernel --sandbox refuses a program built with one, and best-effort runs it with TRUNCATE unconfined.

On an older Landlock it names the rights it could not withhold, for example nish: --sandbox: this kernel's Landlock cannot withhold TRUNCATE, IOCTL_DEV, the signal and abstract socket scopes, so they are not confined.

A program built with --sandbox also refuses to run, with status 126, if its C library skipped the step that applies the sandbox (musl does), or if its .ll is linked on a platform other than Linux. On such a C library every constructor, in your program and the libraries it links, has already run unconfined by the time it refuses.

Where it does not apply

  • macOS has neither Landlock nor seccomp, so a darwin target refuses the flag (NL3044).
  • WebAssembly targets accept it and add nothing: the host already decides what a module may import.
  • --emit-ast, --emit-checked, --emit-ts, --fix, --emit-napi and --emit-napi-async refuse it, and so does a program with neither a main nor top-level code that runs as one: there is nothing to confine.