sydbox

Description

sydbox is a seccomp(2) based sandboxing utility for modern Linux[>=5.6] machines to sandbox unwanted process access to filesystem and network resources.

sydbox requires no root access and no ptrace(2) rights. They don't depend on any specific Linux kernel option to function. The only dependency is libseccomp which is available on many different architectures, including x86, x86_64, x32, arm, aarch64, mips, mips64...

This makes it very easy for a regular user to use. This is the motto of SydBox: bring easy, simple, flexible and powerful security to the Linux user!

The basic idea of sydbox is to run a command under certain restrictions. These restrictions define which system calls the command is permitted to run and which argument values are permitted for the given system call. The restrictions may be applied via two ways. seccomp-bpf can be used to apply simple Secure Computing user filters to run sandboxing fully on kernel space, and seccomp-notify functionality can be used to run sandboxing on kernel space and fallback to user space to dereference pointer arguments of system calls -- which are one of pathname, UNIX socket address, IPv4 or IPv6 network address -- and make dynamic decisions using `rsync`-like wildcards such as `allowlist/write+/home/sydbox/***`, or `allowlist/write+/run/user/*/pulse` for pathnames, and using CIDR notation such as `allowlist/network/connect+inet:127.0.0.1/8@9050`, or `allowlist/network/connect+inet6:::1/8@9050` for IPv4 and IPv6 addresses and perform an action which is by default denying the system call with an appropriate error -- which is usually **permission denied** -- or kill the process running the system call, or kill all processes at once with SIGKILL.

seccomp-bpf filters are extremely fast and secure yet somewhat limited. The limitation stems from the fact that a seccomp-bpf filter may not dereference a pointer in a system call argument. This means, e.g, one may not check if a path name argument is under a certain directory tree. However, one may check if a file opening call is read or write. Note, this is important from the security point of view as dereferencing a pointer is a Time-of-Check-to-Time-of-Use-Problem, or shortly TOCTOU. This means using seccomp-user-notify is never completely secure. Use it at your own risk.

To be able to use sydbox, you need a recent Linux kernel with the system calls pidfd_getfd, pidfd_send_signal, process_vm_readv and process_vm_writev. The Secure Computing facility of the Linux kernel should support the SECCOMP_USER_NOTIF_FLAG_CONTINUE operation. is recommended. It is recommended to enable the kernel configuration option CONFIG_CROSS_MEMORY_ATTACH. Linux-5.11 or later is recommeded. Check with syd --test to verify all the requirements are met.

Options

The following options are understood:

-h, --help: Show usage and exit
-v, --version: Show version and exit
-b, --bpf-only

Sandboxing

There are four sandboxing types:

Read sandboxing
Write sandboxing
execve(2) sandboxing
Network sandboxing

Sandboxing may have four states:

off

Sandboxing is off, none of the relevant system calls are checked and all access is allowed.

bpf

Sandboxing is initialized at startup, tracing happens at kernel space.

The action for the system call is deny with errno EPERM.

deny

Sandboxing defaults to deny, allowlists can be used to allow access.

allow

Sandboxing defaults to allow, denylists can be used to deny access.

In addition, there are filters for every sandboxing to prevent Sydbox from reporting an access violation. Note, access is still denied in such cases.

Write Sandboxing

This sandboxing checks certain system calls for filesystem write access. If a system call tries to write, modify or change attributes of a path, this attempt is reported and the system call is denied. There are two ways to customize this behaviour. Sydbox may be configured to "allowlist" some path patterns. If the path argument of the system call which is subject to be modified matches a pattern in the list of allowlisted path patterns, this attempt is not denied. Additionally, Sydbox may be configured to "filter" some path patterns. In this case a match will prevent Sydbox from reporting a warning about the access violation, the system call is still denied though.

List of filtered system calls are: access(2), faccessat(2), faccessat2(2), chmod(2), fchmodat(2), chown(2), chown32(2), lchown(2), lchown32(2), fchownat(2), open(2), openat(2), openat2(2), creat(2), mkdir(2), mkdirat(2), mknod(2), mknodat(2), rmdir(2), truncate(2), truncate64(2), mount(2), umount(2), umount2(2), utime(2), utimes(2), utimensat(2), futimesat(2), unlink(2), unlinkat(2), link(2), linkat(2), rename(2), renameat(2), renameat2(2), symlink(2), symlinkat(2), setxattr(2), lsetxattr(2), removexattr(2), and lremovexattr(2).

Read Sandboxing

This sandboxing checks certain system calls for filesystem read access. If a system call tries to read a path, this attempt is reported and the system call is denied. See the section called “Write Sandboxing” for more information on how to customize this behaviour.

List of filtered system calls are: access(2), chdir(2), fchdir(2), faccessat(2), faccessat2(2), open(2), openat(2), openat2(2), listxattr(2), and llistxattr(2).

execve(2) Sandboxing

This sandboxing denies execve(2), and execveat(2) calls in case the path argument does not match one of the allowlisted patterns. Note, all exec(3) family functions are sandboxed because these functions are just wrappers of either one of execve(2) or execveat(2) system calls.

Network Sandboxing

This sandboxing exposes a way to prevent unwanted network calls. The filtered system calls are: bind(2), connect(2), sendto(2), recvmsg(2), and sendmsg(2). To increase usability, these system calls are filtered in two groups: bind and connect. bind(2) belongs to the first group, whereas the other system calls belong to the connect group.

Further Restrictions

There are other ways to further restrict access which are listed below. Note, some of these options are enabled by default.

core/restrict/general
core/restrict/identity_change
core/restrict/io_control
core/restrict/memory_map
core/restrict/shared_memory_writable
core/allowlist/successful_bind
core/allowlist/unsupported_socket_families
exec/kill_if_match

Configuration

Sydbox is configured through the so-called magic commands. There are three ways to supply magic commands:

Sydbox may be configured using a configuration file. The path to the configuration file is speficied using the -c command line switch or the SYDBOX_CONFIG environment variable. More than one configuration file may be specified this way. However, only the initial configuration file can change the core configuration. If path to the configuration file is prefixed with the character '@', Sydbox looks for this configuration file under $sharedir/sydbox/ where $sharedir is usually /usr/share. The command line switch has precedence over the SYDBOX_CONFIG environment variable.
Sydbox may be configured using magic stat(2) calls during runtime. This is achieved by calling stat() system call on the special path /dev/sydbox followed by the magic command. Note that runtime configuration is only possible if the magic lock is unset. The system call stat() was chosen as the magic call because it is practical to invoke using builtin shell commands like:
```
            test -e /dev/sydbox/core/sandbox/read:deny
          
```
which enables read sandboxing for a shell running under Sydbox. It is also possible to query certain values using the return value of the magic stat(2):
```
            test -e '/dev/sydbox/core/sandbox/read?' &&\
              echo "read sandboxing on" ||\
              echo "read sandboxing off"
          
```
Note
Some of these shell builtins may actually call lstat(2) or newfstatat(2) system calls instead of stat(2) thus Sydbox makes sure to check lstat() and newfstatat() system calls for magic commands as well.

Note
Inspection (dry run, sandbox mode = dump) behaves identical to off for magic stat(2)

Command Types

Every magic command accepts an argument of a certain type. The available types are listed below:

boolean: A boolean type may have one of the two values, true or false. To specify boolean values when supplying magic commands to Sydbox, you may also use true or false. In addition you can use the short forms t or f and you can also use 1 or 0.
integer: This type represents the basic integer type.
string: This type represents the basic string type.
string-array: This type represents a list of strings. Other types aren't allowed within this type.
command: This is a special type which is used to make sydbox execute certain functions. It is meant to be used as a basic interprocess communication to workaround some tracing limitations.
Note
Magic commands of this type can only be used with the magic stat(2) system call.

Specifying Magic Commands

As mentioned in the section called “Configuration” Sydbox may be configured using the so-called magic commands. Format of the magic commands is simple:

          ${PREFIX}/section/of/option${OPERATION_CHARACTER}value

where ${PREFIX} is /dev/sydbox by default (may be altered at compile-time using SYDBOX_MAGIC_PREFIX definition). This prefix is only required for magic stat(), not for -m command line switch.

${OPERATION_CHARACTER} determines the operation of the magic command. Possible values are listed below:

:: This term is used to set a value. Value must be either a boolean, an integer or a string.
?: This term is used to query a value. Boolean values and certain other values may be queried.
+: This term is used to append to a string array.
-: This is used to remove an element from a string array.
!: This is used to execute a special sydbox command.

Configuration File Format

Configuration file format of sydbox is simple. It is just a way to supply many magic commands in a convenient way. All empty lines and lines starting with the number sign '#' are ignored. All the other lines are treated as if they were supplied to Sydbox via the -m command line switch.

Configuration File Naming

Configuration file naming of sydbox follows a naming scheme which makes it possible to extract magic command API version from the file name. A sydbox configuration file must have the extension "syd-" followed by the API version (e.g. "syd-2" for API version 2).

Current magic command API of sydbox version is `2'.