Documentation
¶
Overview ¶
Package confine holds a declared exec command to the places it may write. run_command starts each declared command through this binary's `confine` role, which asks the kernel's Landlock to refuse every write outside the named directories and then replaces itself with the command: the restriction is the kernel's, inherited across execve, and nothing the command does can lift it. Reading is not restricted unless the caller names what may be read (--read: grep and glob's ripgrep). The tools server itself is never confined, so write_report and the receipts' ledgers under /out are written as before, while a declared command can no longer write there.
Landlock is Linux's (5.13 and later, with the LSM enabled). gVisor does not implement it, so ABI reports an error there and the tools server falls back to running the command as an unprivileged user (runnerimage/toolsrv).
Stdlib only, like the rest of the runner image: the syscalls and constants of include/uapi/linux/landlock.h are spelled here.
Index ¶
Constants ¶
const ErrorFD = 3
ErrorFD is the descriptor the trampoline reports its own failure on. The caller passes a pipe's write end there; Exec marks it close-on-exec, so a command that started closes it unwritten and never holds it, and whatever the caller reads from it is the trampoline's, never the command's.
const ExitFailed = 125
ExitFailed is the trampoline's exit status when it could not confine or start the command.
const Role = "confine"
Role is the runner binary's argument that runs Trampoline.
Variables ¶
This section is empty.
Functions ¶
func ABI ¶
ABI is the running kernel's Landlock ABI version, or why there is none: ENOSYS on a kernel or runtime without it (gVisor), EOPNOTSUPP when the LSM is built but not enabled, EPERM when a seccomp filter refuses it.
func Exec ¶
Exec confines this process to writing beneath dirs (and to /dev/null), then replaces it with path, argv and env. It returns only on failure.
func ExecWith ¶
ExecWith holds this process to o, then replaces it with path, argv and env. It returns only on failure.
The address-space limit comes last, after every argument of execve is built: this process is Go, whose runtime may already hold more address space than the limit, so nothing may allocate once it is set. A failed execve past that point is reported and exits without allocating (failExec).
func Main ¶
Main is the trampoline: `confine [--write DIR …] [--read DIR …] [--max-memory BYTES] [--no-network] -- PROGRAM [ARG …]`, or `confine --limits-only [--max-memory BYTES] -- PROGRAM [ARG …]`. It confines this process to writing beneath each --write DIR and, when any --read DIR is named, to reading beneath those and the writable ones, with the limits, and then execs PROGRAM with ARGs and this process's environment. It returns only on failure, and never runs PROGRAM with less than it was told.
func NetworkDenied ¶
NetworkDenied says whether NoNetwork refuses TCP at Landlock ABI abi.
func Trampoline ¶
func Trampoline(args []string)
Trampoline is the role's entry point: Main, with its failure written to ErrorFD (or to stderr, when the caller passed none) and ExitFailed. It does not return.
Types ¶
type Options ¶
type Options struct {
// Writable are the directories the program may write beneath (with
// /dev/null), by Landlock.
Writable []string
// Readable, when set, are the only directories (or files) the program
// may read, list and run anything beneath, besides the writable ones, the
// program itself and /dev/null: Landlock then refuses every other
// read. Unset, reading is not restricted.
Readable []string
// MaxMemory, when set, is the program's address-space limit in bytes
// (RLIMIT_AS): an allocation past it fails.
MaxMemory uint64
// NoNetwork refuses the program every TCP bind and connect where
// Landlock can (ABI 4 and later); on an older ABI it is not refused,
// which NetworkDenied tells the caller beforehand.
NoNetwork bool
// LimitsOnly applies MaxMemory and no_new_privs and no Landlock: the
// caller holds the program's writes another way, by starting it as a
// user that owns nothing it must not write. For a machine without
// Landlock (gVisor).
LimitsOnly bool
// contains filtered or unexported fields
}
Options is what the trampoline holds a program to.