SYD(1)

NAME

syd - Rock solid application kernel

SYNOPSIS

syd [-acefhlmpqtxEPV] [--] {command [arg...]}

syd --api

syd --check

syd --el

syd --sh

DESCRIPTION

Syd is a utility that uses the seccomp(2) system call to sandbox processes on Linux systems version 5.19 or later. It enables per-syscall control over a process's filesystem and network access without requiring root privileges. Syd is designed for ease of use across a wide array of architectures, including x86, x86_64, x32, armv7, aarch64, loongarch64, mips, mips64, mips64el, ppc, ppc64, ppc64le, riscv64, and s390x embodying the principle of providing simple, flexible, and reliable access control to Linux users.

The core functionality of Syd revolves around restricting a process's resource access through several mechanisms:

•   Bind Mounts: Utilized within a mount namespace to enforce restrictions at the Virtual File System (VFS) level, such as read-only, nodev, noexec, nosuid, and nosymfollow.
•   Landlock: Employs read-only and read-write path restrictions at the kernel level.
•   seccomp-bpf: Applies Secure Computing user filters for kernel-space sandboxing.
•   seccomp-notify: Enables sandboxing in kernel space with user space fallback for dereferencing pointer arguments in system calls, including pathnames and network addresses. Access checks use UNIX shell-style patterns and CIDR notation, defaulting to denying system calls with EACCES while attempting to emulate successful calls to mitigate Time-of-Check to Time-of-Use (TOCTOU) attack vectors.

Prerequisites for Syd include a Linux kernel supporting pidfd_getfd(2) and pidfd_send_signal(2) system calls, SECCOMP_USER_NOTIF_FLAG_CONTINUE operation in the Secure Computing facility, and preferably the CONFIG_CROSS_MEMORY_ATTACH kernel option. For syscall emulation, Syd uses the seccomp operation SECCOMP_IOCTL_NOTIF_ADDFD. Syd also sets the SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV flag to correctly handle interrupts during tracing. While Linux version 5.19 or later is required, for Landlock support Syd requires a kernel configured with the option CONFIG_LSM_LANDLOCK supporting Landlock ABI version 3, with syd-lock(1) available as a helper program to verify kernel support. Linux kernel options CONFIG_KCMP and CONFIG_UNIX_DIAG are recommended.

By default, Syd restricts the resource space accessible to sandboxed processes as tightly as possible. The SECURITY section of the syd(7) manual page lists all hardening measures and the trace/allow_unsafe_* options to relax specific restrictions when needed.

OPTIONS

The following options are understood:

-h, --help | Show usage and exit.
-V, --version | Show version and exit.
-C, --check | Print sandboxing support information about the current system and exit.
-v, --verbose | Increase verbosity, equivalent to incrementing log/verbose by one.
-c | Login shell compatibility
 | Causes command to be executed under a shell with the user profile.
 | The shell to execute is /bin/sh by default.
 | Use the environment variable SYD_SHELL to override.
-f | Login shell compatibility.
 | Causes Syd to parse the user profile on startup.
-l, --login | Login shell compatibility
 | Causes Syd to parse the user profile on startup.
-q | Enable quick boot mode for faster startup times.
 | This must be passed as the first option or it will be ignored.
 | See the explanation of the environment variable SYD_QUICK_BOOT for the safety of this option.
-x | Enable trace aka "dry run" mode.
 | In this mode Syd will allow system calls even if they raise access violations.
 | This mode with extended logging can be used to build sandboxing profiles in an automated way.
 | See pandora(1) which is a tool that uses Syd's trace mode to automatically generate sandbox profiles.
-m config | Configure sandbox during init, may be repeated.
-p name | Use a sandbox profile during init, may be repeated.
-P path | Run a configuration file during init, may be repeated.
-a alias | Set alias of the command. Passed as argv[0] to the program.
-e | Use -e var=val to put var=val in the environment for command, may be repeated.
 | Use -e var to remove var from the environment for command, may be repeated.
 | Use -e var= to pass-through an unsafe environment variable, may be repeated.
-t timeout | Specify sandbox timeout in human readable format.
 | Equivalent to timeout option, refer to syd(2) for more information.
-E mode | Export secure computing rules with the given format to standard output and exit.
 | Mode must be one of bpf or pfc:
 | bpf, aka Berkeley Packet Filter is a binary, machine readable format, whereas
 | pfc, aka Pseudo Filter Code is a textual, human readable format.
--api | Output syd(2) API specification in JSON format.
 | This specification is intended to ease generation of language bindings.
 | This specification is also available via the magic path /dev/syd.
--el | Output syd.el which is the Emacs Lisp implementation of Syd stat(2) interface.
 | This file is also available via the magic path /dev/syd.el.
--sh | Output a shell script which defines the esyd helper function.
 | This file is also available via the magic path /dev/syd.sh.
 | Works with POSIX sh, bash and zsh.
 | You may use eval "$(syd --sh)" in your shell init file.

INVOCATION

Syd executes a command with the specified arguments under a sandbox and exits with the same status. The sandbox may be constructed by command-line arguments and configuration files. syd(2) API is available for dynamic configuration if the sandbox lock allows it. An IPC socket may be configured with the ipc command to configure Syd through a UNIX socket. Refer to the syd(2) manual page for more information.

ENVIRONMENT

SYD_IPC | Specify UNIX socket address for runtime configuration.
 | Equivalent to the ipc command, see the syd(2) manual page.
 | ipc command has precedence over this environment variable.
SYD_LOG | Set log level to emerg, alert, crit, error, warn, notice, info or debug.
SYD_LOG_BUF_LEN | Set syslog(2) ring buffer capacity.
 | By default, ring buffer is allocated on the stack with 256k size.
 | Setting this variable makes Syd allocate ring buffer on the heap with user-specified size.
 | The value is parsed using the parse-size crate.
 | Refer to their documentation for information on formatting.
SYD_LOG_FD | Set log file descriptor, defaults to stderr(3).
 | Negative values are permitted as a shorthand to disable logging.
 | Positive values must be valid FDs or Syd will exit with EBADF ("Bad file number").
SYD_PDS | Set parent-death signal with PR_SET_PDEATHSIG(2const) using signal name or number.
SYD_PID_FN | Set pid filename, makes Syd write its process ID to this file at startup.
 | The file must not exist and is going to be created with user-only read permissions.
SYD_NPROC | Set the number of core syscall handler threads, defaults to the number of CPUs.
 | The number must be at least 1.
SYD_NPROC_MAX | Set the number of maximum syscall handler threads, defaults to usize::MAX.
 | The number must be greater than SYD_NPROC.
SYD_CHDIR | Change current working directory to a safe directory at startup.
 | This is implied if no optional arguments are given.
SYD_COMPAT_SOCKET | Allow the legacy socketcall(2) multiplexer system call.
 | This is only necessary for compatibility with libcs which don't yet support the newer non-multiplexed system calls available as of Linux-4.3.
 | Equivalent to trace/allow_unsafe_socketcall:1.
SYD_SHELL | Pick the shell to spawn when invoked as a login shell. It is not split into words.
 | Defaults to /usr/bin/bash --login --noprofile --norc --restricted.
SYD_DUMP_SCMP | Export secure computing rules with the given format, equivalent to the -E option.
SYD_SKIP_SCMP | Skip seccomp(2) confinement of per-Syd threads.
 | This is unsafe and should only used for profiling.
 | Syd honours RUST_BACKTRACE environment variable when this is set.
 | This is ignored unless Syd is built with the trusted Cargo feature.
SYD_SKIP_NAME | Skip randomizing Syd thread names which is useful for debugging.
 | This is ignored unless Syd is built with the trusted Cargo feature.
SYD_FORCE_NO_UNIX_DIAG | Force disable UNIX socket diagnostics, to test fallback paths used on kernels configured without CONFIG_UNIX_DIAG.
 | This is intended for testing and should not be used in production.
 | This is ignored unless Syd is built with the trusted Cargo feature.
SYD_FORCE_NO_SYMLINKS | Force RESOLVE_NO_SYMLINKS resolve flag at open(2) boundary.
 | Equivalent to trace/force_no_symlinks:1.
SYD_FORCE_NO_MAGICLINKS | Force RESOLVE_NO_MAGICLINKS resolve flag at open(2) boundary.
 | Equivalent to trace/force_no_magiclinks:1.
SYD_FORCE_NO_XDEV | Force RESOLVE_NO_XDEV resolve flag at open(2) boundary.
 | Equivalent to trace/force_no_xdev:1.
SYD_FORCE_CLOEXEC | Force close-on-exec for file descriptors.
 | Equivalent to trace/force_cloexec:1.
SYD_FORCE_RAND_FD | Use randomized file descriptors to harden against fd reuse.
 | Equivalent to trace/force_rand_fd:1.
 | This environment variable is ignored if kcmp(2) isn't supported.
SYD_FORCE_RO_OPEN | Reject creating and writing open(2) calls.
 | Equivalent to trace/force_ro_open:1.
SYD_FORCE_WX_OPEN | Reject creating and writing open(2) calls for executables.
 | Equivalent to trace/force_wx_open:1.
SYD_FORCE_LOCAL_NET | Force local networking, rewrites all addresses to loopback for bind/connect.
 | Equivalent to trace/force_local_net:1.
SYD_FORCE_TTY | Force TTY output which is pretty-printed JSON.
SYD_QUIET_TTY | Force quiet TTY output which is line-oriented JSON.
SYD_PROXY_HOST | Override the default value of proxy/ext/host,
 | If the value is a hostname and not an IP address,
 | Syd resolves this hostname at startup and selects a response IP randomly.
SYD_PROXY_PORT | Override the default value of proxy/ext/port.
SYD_PROXY_UNIX | Set the default value for proxy/ext/unix which overrides proxy/ext/host.
SYD_QUICK_BOOT | Enable quick boot mode, this makes Syd startup noticeably faster:
 | However, quick boot removes a layer of defense against some container breaks!
 | Use this if you frequently re-execute syd(1) or syd-oci(1),
 | as Exherbo Linux does during cave-generate-metadata(1).
 | This is ignored unless Syd is built with the trusted Cargo feature.
SYD_RLIMIT_AS | Set the default value for rlimit/as.
SYD_RLIMIT_CORE | Set the default value for rlimit/core.
SYD_RLIMIT_DATA | Set the default value for rlimit/data.
SYD_RLIMIT_FSIZE | Set the default value for rlimit/fsize.
SYD_RLIMIT_MEMLOCK | Set the default value for rlimit/memlock.
SYD_RLIMIT_NICE | Set the default value for rlimit/nice.
SYD_RLIMIT_NOFILE | Set the default value for rlimit/nofile.
SYD_RLIMIT_NPROC | Set the default value for rlimit/nproc.
SYD_RLIMIT_RTPRIO | Set the default value for rlimit/rtprio.
SYD_RLIMIT_RTTIME | Set the default value for rlimit/rttime.
SYD_RLIMIT_SIGPENDING | Set the default value for rlimit/sigpending.
SYD_RLIMIT_STACK | Set the default value for rlimit/stack.
SYD_TMOUT | Set the default value for timeout.
SYD_NO_CROSS_MEMORY_ATTACH | Disable cross memory attach and use proc_pid_mem(5) unconditionally.
SYD_PROC_PID_MEM_FALLBACK | By default, Syd uses cross memory attach unconditionally.
 | Setting this variable causes Syd to fall back to proc_pid_mem(5) automatically,
 | if process_vm_readv(2) or process_vm_writev(2) fails with ENOSYS,
 | which indicates kernel support is missing for these system calls.
 | The variable SYD_NO_CROSS_MEMORY_ATTACH has precedence over this variable.
SYD_ASSUME_KERNEL | Override uname(2) to get host Linux kernel version used for feature detection.
 | Syd reports the major and minor kernel version at uname(2) boundary within the sandbox.
 | The micro version is randomized per-Syd run to prevent information leaks.
 | This environment variable is ignored unless Syd is built with the "trusted" feature.
SYD_PALUDIS_LPATH | Override sandbox/lpath option for the paludis profile, defaults to off.
SYD_PALUDIS_NPATH | Override sandbox/npath option for the paludis profile, defaults to off.
SYD_PALUDIS_LIST | Override sandbox/list option for the paludis profile, defaults to off.
SYD_PALUDIS_WALK | Override sandbox/walk option for the paludis profile, defaults to off.
SYD_PALUDIS_IOCTL | Override sandbox/ioctl option for the paludis profile, defaults to off.
SYD_PALUDIS_PASSFD | Override sandbox/passfd option for the paludis profile, defaults to off.
SYD_USER_LPATH | Override sandbox/lpath option for the user profile, defaults to on.

LOGGING

There're eight log levels: emerg, alert, crit, error, warn, notice, info, and debug with descending priority. Log level may be set with the SYD_LOG environment variable. Logs go to stderr(3) unless a file descriptor is specified with the environment variable SYD_LOG_FD. Syd logs in JSON lines. Below is a list of commonly used log keys with their descriptions:

KEY | DESCRIPTION
id | Sandbox ID as 64 lowercase hexadecimal characters.
ctx | Context of log entry, e.g. access, safesetid, segvguard etc.
cap | Sandbox capability
act | Sandbox action: allow, warn, deny, panic, stop, abort, kill or exit
pid | Process ID
path | Path argument of syscall
addr | Network address argument of syscall, e.g. 127.0.0.1!22
unix | UNIX socket address argument of syscall
ipv | IP version of network address in addr field (4 or 6)
abs | True if socket address in unix field is an abstract UNIX socket
sys | Name of syscall
arch | Architecture of syscall
args | Arguments of syscalll
cmd | Process name, or command line if log output is a TTY or log feature is enabled
cwd | Current working directory of sandbox process
uid | User ID
time | Timestamp in ISO8601-compatible format, currently YYYYMMDDThhmmssZ
 | Time format may change but it will always remain ISO8601-compatible.
 | Formatting errors fallback to printing timestamp as an integer.
err | Error information
msg | Informational messages
tip | Educational messages on how to configure Syd

EXIT STATUS

Syd exits with same exit code as the sandbox process. If the sandbox process exits with a signal, Syd exits with 128 plus value of the signal. In case there was an error in spawning or waiting for the sandbox process, Syd exits with errno(3) indicating the error condition. Syd exits with 101 on panics. Syd exits with 102 on fatal allocator errors. Syd exits with 124 if sandbox timeout is exceeded.

SEE ALSO

syd(2), syd(5), syd(7), syd-lock(1), syd-ls(1), syd-mdwe(1), syd-ring(1), sydtutorial(7)

•   syd homepage: https://sydbox.exherbo.org/
•   libsyd homepage: https://libsyd.exherbo.org/
•   pandora homepage: https://lib.rs/pandora_box
•   paludis homepage: http://paludis.exherbo.org/
•   Landlock homepage: https://landlock.io

AUTHORS

Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and on Radicle at rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF. Bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat or in #sydbox:mailstation.de on Matrix.