docs.rs failed to build syd-3.0.0-beta.3
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Visit the last successful build: syd-3.48.1

sydbox: The ☮ther SⒶndbøx

Introduction

sydbox has been the default sandbox of Exherbo GNU/Linux distribution for over a decade. We use it to provide a restricted environment under which package builds run with controlled access to file system and network resources. Exherbo package description format, currently exheres-0, uses a shell function called esandbox to interact with sydbox. See the Sandboxing section of Exheres for Smarties for more information.

Quick Start

sydbox-0 is a ptrace based sandbox.
sydbox-1 is a ptrace+seccomp based sandbox.
sydbox-2 is a seccomp+seccomp-unotify based sandbox.
sydbox-3 is a rewrite of sydbox-2 in Rust and it's what you are looking at.

This codebase has a history of a bit over 10 years and up to this point we have used C11 as our implementation language for various reasons. With sydbox-3 we are moving forwards one step and writing the sandbox from scratch using Rust programming language with the only !Rust dependency being libseccomp. Although we inherit many ideas and design decisions from the old codebase, we also don't shy away from radically changing the internal implementation making it much simpler, idiomatic, and less prone to bugs. This version also takes advantage of multithreading and handles system calls using a thread pool whose size is equal to the number of CPUs on the running machine. Moreover, access violations are logged into syslog, so you may use a command like journalctl SYSLOG_IDENTIFIER=syd to view the sandbox logs. We use clippy for static analysis with a strict configuration. In the name of code simplicity, we set the value 9 rather than the default 25 for the cylomatic, "cognitive", complexity lint, and the value 80 rather than the default 250 for the type complexity lint. Moreover, in the name of better error handling, we disallow the usage of Option::unwrap, Option::expect, Result::unwrap, and Result::expect. The program may easily be built statically, with a size about 1.3Mb for the x86-64 build, and 1.1Mb for the aarch64 build. After each push, the CI builds binaries with static linking using a musl target and keeps them available for download for 90 days. To download, browse to one of the URLs given below depending on your machine architecture, choose a succeeding build, and download the artifact syd on the left part of the build page. You may also download the syd-debug artifact for a non-stripped release build.

x86-64
- Host: Linux build 6.1.55-0-lts #1-Alpine SMP PREEMPT_DYNAMIC Sun, 24 Sep 2023 23:14:02 +0000 x86_64 Linux
- List: https://builds.sr.ht/~alip/syd/commits/main/linux-x86-64.yml
aarch64
- Host: Linux build 5.10.0-8-arm64 #1 SMP Debian 5.10.46-4 (2021-08-03) aarch64 GNU/Linux
- List: https://builds.sr.ht/~alip/syd/commits/main/linux-arm64.yml

To install from source, use cargo install --locked syd. To follow the latest developments, checkout the git repository and run cargo build --release on it. Make sure to have libseccomp development files installed. The command to install libseccomp library for some Linux distributions are given below.

Alpine: apk add libseccomp-dev libseccomp-static
Debian: apt install libseccomp-dev
Exherbo: cave resolve libseccomp
Gentoo: emerge libseccomp
Ubuntu: apt install libseccomp-dev

SydB☮x exposes the functionality of the following crates in their sandbox API:

glob-match: Pattern matching with Unix shell style patterns, see Wikipedia:Glob for more information.
ipnetwork: Pattern matching with Classless Inter-Domain Routing, see Wikipedia:Cidr for more information.

This manual page gives only brief information on Pattern Matching, and Address Matching. The user is recommended to read the documentation of the respective crates to get more information on the details of pattern matching, and address matching.

Manual

NAME

syd - seccomp-bpf and seccomp-notify based application sandbox

SYNOPSIS

syd [-hv] [--lock] [--root] [-m command...] [-c path...] [-p name...] [--] {command [arg...]}
syd exec {command [arg...]}
syd log

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 rights. All you need is a recent Linux kernel and 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 SydB☮x: bring easy, simple, flexible and powerful access restriction 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 (See Security about TOCTOU et. al), which are one of pathname, UNIX socket address, IPv4, or IPv6, network address, and make dynamic decisions using Unix shell style patterns such as allowlist/write+/home/sydbox/**, or allowlist/write+/run/user/*/pulse for pathnames, and using CIDR notation such as allowlist/network/connect+127.0.0.1/8@9050, or allowlist/network/connect+::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, aka EPERM.

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. It is recommended to have the CONFIG_CROSS_MEMORY_ATTACH kernel option enabled, if this option is not enabled, sydbox will fallback to reading/writing from /proc/$pid/mem. Linux-5.11 or later is recommended.

OPTIONS

The following options are understood:

-h, --help

Show usage and exit

-v, --version

Show version and exit

-m command, --magic=command

Run a sandbox command during init, may be repeated. See the section called "CONFIGURATION" for more information.

-c path, --config=path

Run a configuration file during init, may be repeated. See the section called "CONFIGURATION" for more information.

-p name, --profile=name

Use a sandbox profile during init, may be repeated. See the section called "CONFIGURATION" for more information.

-l, --lock

Lock sandbox commands after initialization. By default, sydbox may be configured during runtime from inside the sandbox via Paludis esandbox command or via pandora. Locking prevents this and makes sydbox sandbox tamper-free making it a true jail replacement.

-r, --root

In fakeroot mode, the system will return a user/group id of 0, mimicking the root user. This allows users to execute commands with apparent root privileges, without actual superuser rights. It's useful for tasks like package building where root-like environment is needed, but not actual root permissions. You may also use the environment variable SYD\_FAKEROOT to this effect.

syd exec may be used to construct a sandbox command to execute a process outside the sandbox. See the description of cmd/exec command for more information.
syd log may be used to access sandbox logs using journalctl.

Profiles

paludis: Used by the Paludis package mangler.
noipv4: Disables IPv4 connectivity.
noipv6: Disables IPv6 connectivity.
user: Allows user-specific directories, and connections.

When invoked without arguments, syd drops to a shell with the user profile set.

SANDBOXING

There are four sandboxing types:

Read sandboxing
Write sandboxing
Exec sandboxing
Network sandboxing

Sandboxing may be on and off.

off: Sandboxing is off, none of the relevant system calls are checked and all access is allowed.
on: Sandboxing defaults to deny, allowlists and denylists can be used to refine access rights.

In addition, there are filters for every sandboxing to prevent Sydb☮x 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 in system log and the system call is denied. There are two ways to customize this behaviour. Sydb☮x 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. If, however it matches a pattern in the list of "denylist" path patterns the attempt is denied (last matching pattern wins). Additionally, Sydb☮x may be configured to "filter" some path patterns. In this case a match will prevent Sydb☮x from reporting a warning about the access violation, the system call is still denied though.

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

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, chdir, fchdir, faccessat, faccessat2, getdents, getdents64, open, openat, openat2, listxattr, flistxattr, and llistxattr.

Exec Sandboxing

This sandboxing denies execve, and execveat calls in case the path argument does not match one of the allowlisted patterns. Note, all exec family functions are sandboxed because these functions are just wrappers of either one of execve or execveat system calls. See the section called Write Sandboxing for more information on how to customize this behaviour.

Network Sandboxing

This sandboxing exposes a way to prevent unwanted network calls. The filtered system calls are: bind, connect, sendto, recvmsg, and sendmsg. To increase usability, these system calls are filtered in two groups: bind and connect. bind belongs to the first group, whereas the other system calls belong to the connect group. See the section called Write Sandboxing for more information on how to customize this behaviour.

Further Restrictions

There are other ways to further restrict access which are listed below.

exec/kill: Kill the exec process in case it matches a path pattern.

CONFIGURATION

Sydb☮x is configured through sandbox commands. There are two ways to supply sandbox commands:

Sydb☮x may be configured using a configuration file. The path to the configuration file is speficied using the -c command line switch. More than one configuration file may be specified this way. Single commands may also be passed via -m command line switch. Some default configuration sets may be applied using the -p command line switch. The available sets are paludis, noipv4, and noipv6. More than one profile may be specified. For multiple matching rules (e.g. two rules matching the same path), the last matching rule wins.
Sydb☮x may be configured using "magic" stat calls during runtime. This is achieved by calling stat() system call on the special path /dev/syd followed by the sandbox command. Note that runtime configuration is only possible if the sandbox lock is unset. The system call stat() was chosen because it is practical to invoke using builtin shell commands like:

test -e /dev/syd/sandbox/read:on

which enables read sandboxing for a shell running under Sydb☮x. It is also possible to query certain values using the return value of the stat call:

test -e /dev/syd/sandbox/read? &&\
  echo "read sandboxing on" ||\
  echo "read sandboxing off"

Note, some of these shell builtins may actually call other system calls such as fstat, lstat, newfstatat, or statx. Sydb☮x supports the same interface through all these system calls transparently.

Command Types

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

void: This command accepts no argument.
boolean: A boolean type may have one of the two values, true or false. To specify boolean values when supplying sandbox commands to Sydb☮x, 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 arent 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.

Specifying Sandbox Commands

As mentioned in the section called "CONFIGURATION", Sydb☮x may be configured using sandbox commands. Format of the sandbox commands is simple: ${PREFIX}/section/of/option${OPERATION_CHARACTER}value where ${PREFIX} is /dev/syd by default (may be altered at compile-time using MAGIC_PREFIX definition in config.rs). This prefix is only required for stat() call, not for -m command line switch.

${OPERATION_CHARACTER} determines the operation of the sandbox 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 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 Sydb☮x via the -m command line switch.

Configuration File Naming

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

Current command API of sydbox version is 3.

Commands

Sydb☮x recognizes the following commands:

dump

type: void
default: none
query: no

This command causes sydbox to output sandbox information on standard error.

lock

type: string
default: off
query: no

A string specifying the state of the sandbox lock. Possible values are on, off and exec. If the sandbox lock is on no commands are allowed. If exec is specified, the sandbox lock is set to on for all processes except the initial process (sydbox exec child) after the first exec call.

sandbox/exec

type: string
default: off
query: yes

A string specifying how exec calls should be sandboxed. See the section called Exec Sandboxing for more information.

sandbox/read

type: string
default: off
query: yes

A string specifying how read sandboxing should be done. See the section called Read Sandboxing for more information.

sandbox/write

type: string
default: on
query: yes

A string specifying how write sandboxing should be done. See the section called Write Sandboxing for more information.

sandbox/network

type: string
default: on
query: yes

A string specifying how network sandboxing should be done. See the section called Network Sandboxing for more information.

trace/allow_successful_bind

type: boolean
default: true
query: no

A boolean specifying whether the socket address arguments of successful bind calls should be allowlisted for connect, sendto, recvmsg, and sendmsg system calls. Note, these socket addresses are allowlisted globally and not per-process for usability reasons. Thus, for example, a process which forks to call bind will have its socket address allowlisted for their parent as well.

trace/allow_unsupported_socket_families

type: boolean
default: true
query: no

A boolean specifying whether unknown socket families should be allowed access when network sandboxing is on.

trace/memory_access

type: integer
default: 0
query: no

Mode on using cross memory attach or /proc/pid/mem. Cross memory attach requires a Linux kernel with the CONFIG_CROSS_MEMORY_ATTACH option enabled. Default mode is 0.

0: Use cross memory attach if available, use /proc otherwise.
1: Use /proc/pid/mem unconditionally. You may also use the environment variable SYD\_PROC\_MEM to this effect:

⇒  strace -eprocess_vm_readv -fc -- syd -m trace/memory_access:0 true
strace: Process 241337 attached
strace: Process 241336 attached
strace: Process 241339 attached
strace: Process 241335 attached
strace: Process 241340 attached
strace: Process 241338 attached
% time     seconds  usecs/call     calls    errors syscall
------ ----------- ----------- --------- --------- -----------------
100,00    0,000092           9        10           process_vm_readv
------ ----------- ----------- --------- --------- -----------------
100,00    0,000092           9        10           total
⇒  strace -eprocess_vm_readv -fc -- syd -m trace/memory_access:1 true
strace: Process 241423 attached
strace: Process 241424 attached
strace: Process 241425 attached
strace: Process 241426 attached
strace: Process 241427 attached
strace: Process 241428 attached
[pid 241424] ????( <detached ...>
⇒

exec/kill

type: string-array
default: [empty array]
query: no

This setting specifies a list of path patterns. If one of these patterns matches the resolved path of an exec system call, the process in question is killed. See the section called PATTERN MATCHING for more information on glob patterns.

filter/exec

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to filter for exec sandboxing. See the section called Exec Sandboxing and the section called PATTERN MATCHING.

filter/read

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to filter for read sandboxing. See the section called Read Sandboxing and the section called PATTERN MATCHING.

filter/write

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to filter for write sandboxing. See the section called Write Sandboxing and the section called PATTERN MATCHING.

filter/network

type: string-array
default: [empty array]
query: no

Specifies a list of network addresses to filter for network sandboxing. See the section called Network Sandboxing and the section called ADDRESS MATCHING.

allowlist/exec

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to allowlist for execve(2) sandboxing. See the section called "execve(2) Sandboxing" and the section called PATTERN MATCHING.

allowlist/read

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to allowlist for read sandboxing. See the section called Read Sandboxing and the section called PATTERN MATCHING.

allowlist/write

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to allowlist for write sandboxing. See the section called Write Sandboxing and the section called PATTERN MATCHING.

allowlist/network/bind

type: string-array
default: [empty array]
query: no

Specifies a list of network addresses to allowlist for bind network sandboxing. See the section called Network Sandboxing and the section called "ADDRESS MATCHING".

allowlist/network/connect

type: string-array
default: [empty array]
query: no

Specifies a list of network addresses to allowlist for connect network sandboxing. See the section called Network Sandboxing and the section called "ADDRESS MATCHING".

denylist/exec

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to denylist for exec sandboxing. See the section called Exec Sandboxing and the section called PATTERN MATCHING.

denylist/read

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to denylist for read sandboxing. See the section called Read Sandboxing and the section called PATTERN MATCHING.

denylist/write

type: string-array
default: [empty array]
query: no

Specifies a list of path patterns to denylist for write sandboxing. See the section called Write Sandboxing and the section called PATTERN MATCHING.

denylist/network/bind

type: string-array
default: [empty array]
query: no

Specifies a list of network addresses to denylist for bind network sandboxing. See the section called Network Sandboxing and the section called ADDRESS MATCHING.

denylist/network/connect

type: string-array
default: [empty array]
query: no

Specifies a list of network addresses to denylist for connect network sandboxing. See the section called Network Sandboxing and the section called ADDRESS MATCHING.

cmd/exec

type: command
default: none
query: no

Makes sydbox execute an external command without sandboxing. The program name and arguments must be separated with the US (unit separator, octal: 037) character. To ease usage, the syd exec subcommand is provided to construct a sandbox command of this type:

⇒  syd -- bash -c 'test -e $(syd exec echo hello world)'
{"caps":2,"cmd":"bash -c test -e $(target/debug/syd exec echo hello world)","ctx":"access","id":"syd","l":2,"path":"/dev/tty","pid":771840,"sys":"openat","t":1696548946}
{"caps":2,"cmd":"bash -c test -e $(target/debug/syd exec echo hello world)","ctx":"access","id":"syd","l":2,"path":"/dev/pts/8","pid":771840,"sys":"openat","t":1696548946}
{"abs":false,"caps":8,"cmd":"target/debug/syd exec echo hello world","ctx":"access","id":"syd","l":2,"pid":771842,"sys":"connect","t":1696548946,"unix":"/dev/log"}
{"cmd":"target/debug/syd exec echo hello world","ctx":"syd/exec","id":"syd","l":2,"path":"/dev/syd/cmd/exec!echo\u001fhello\u001fworld","pid":771842,"t":1696548946}
{"cmd":"target/debug/syd -- bash -c test -e $(target/debug/syd exec echo hello world)","ctx":"cmd/exec","id":"syd","l":2,"pid":771847,"t":1696548946}
hello world

PATTERN MATCHING

Sydb☮x uses shell-style pattern matching for allowlists and filters. The matching code uses the glob-match crate. Check their documentation on more information about patterns. Note, patterns are case sensitive. Note also, Sydb☮x gets patterns from multiple sources: a configuration file, a profile, the -m command line switch, or a stat call with /dev/syd prefix. There is no precedence between different sources, and the last matching pattern decides the outcome.

ADDRESS MATCHING

Sydb☮x has a simple address scheme to match network addresses. The addresses can either be a glob-match pattern to match UNIX and abstract UNIX socket addresses, or an IP CIDR followed by a port range to match IPv4 and IPv6 addresses. Port range can either be a single port or a range in format port1-port2. The address and the port range must be splitted by the character @. In addition there are some aliases, you may use instead of specifying an address:

LOOPBACK: Expanded to inet:127.0.0.0/8
LOOPBACK6: Expanded to inet6:::1/8
LOCAL: Expanded to four addresses as defined in RFC1918:
- inet:127.0.0.0/8
- inet:10.0.0.0/8
- inet:172.16.0.0/12
- inet:192.168.0.0/16
LOCAL6: Expanded to four addresses:
- inet6:::1
- inet6:fe80::/7
- inet6:fc00::/7
- inet6:fec0::/7

EXAMPLES

Below are examples of invocation and configuration of Sydb☮x.

Invocation Examples

Below are some invocation examples:

Deny all reads and writes, allow read access to /dev/zero and write access to /dev/full. The executable dd is not static in this case thus allow access to /lib64 where it will load its shared libraries from as well. Note, on the system of the author the dd binary links only to libraries under /usr/lib, use ldd to check the linked libraries on your system. Note also the quoting to escape shell expansion.

$ syd -m sandbox/read:on -m 'allowlist/read+/usr/lib/**' -m allowlist/read+/dev/zero -m allowlist/write+/dev/full -- dd if=/dev/zero of=/dev/full count=1
{"caps":1,"cmd":"dd if=/dev/zero of=/dev/full count=1","ctx":"access","id":"syd","l":2,"path":"/etc/ld.so.preload","pid":158744,"sys":"access","t":1696481934}
dd: writing to '/dev/full': No space left on device
1+0 records in
0+0 records out
0 bytes copied, 0.000916841 s, 0.0 kB/s

Kill common bittorrent applications.

$ syd -m 'exec/kill+/usr/bin/[kr]torrent' -- bash
{"caps":2,"cmd":"bash","ctx":"access","id":"syd","l":2,"path":"/dev/tty","pid":178259,"sys":"openat","t":1696484715}
{"caps":2,"cmd":"bash","ctx":"access","id":"syd","l":2,"path":"/dev/pts/4","pid":178259,"sys":"openat","t":1696484715}
{"abs":false,"caps":8,"cmd":"bash","ctx":"access","id":"syd","l":2,"pid":178259,"sys":"connect","t":1696484715,"unix":"/var/run/nscd/socket"}
{"abs":false,"caps":8,"cmd":"bash","ctx":"access","id":"syd","l":2,"pid":178259,"sys":"connect","t":1696484715,"unix":"/var/run/nscd/socket"}
syd> rtorrent
{"caps":5,"cmd":"bash","ctx":"exec","id":"syd","l":2,"path":"/usr/bin/rtorrent","pid":178259,"sys":"access","t":1696484726}
{"ctx":"spawn_response","err":"failed to send response: invalid request","id":"syd","l":3,"t":1696484726}
$ syd -m 'exec/kill+/usr/bin/[kr]torrent' -- bash
{"caps":2,"cmd":"bash","ctx":"access","id":"syd","l":2,"path":"/dev/tty","pid":178309,"sys":"openat","t":1696484730}
{"caps":2,"cmd":"bash","ctx":"access","id":"syd","l":2,"path":"/dev/pts/4","pid":178309,"sys":"openat","t":1696484730}
{"abs":false,"caps":8,"cmd":"bash","ctx":"access","id":"syd","l":2,"pid":178309,"sys":"connect","t":1696484730,"unix":"/var/run/nscd/socket"}
{"abs":false,"caps":8,"cmd":"bash","ctx":"access","id":"syd","l":2,"pid":178309,"sys":"connect","t":1696484730,"unix":"/var/run/nscd/socket"}
syd>ktorrent
{"caps":5,"cmd":"bash","ctx":"exec","id":"syd","l":2,"path":"/usr/bin/ktorrent","pid":178309,"sys":"access","t":1696484742}
{"ctx":"spawn_response","err":"failed to send response: invalid request","id":"syd","l":3,"t":1696484742}
$

BUGS

Report bugs by direct mail to alip@chesswob.org. Refer to BUGS on http://git.exherbo.org/sydbox-1.git/tree/BUGS for more information on providing information with bug reports. Note, attaching poems encourages consideration tremendously.

SECURITY

This is a tricky area. The main advantage sydbox brings to the table is that it requires no elevated privileges: no root access or ptrace capabilities are needed. This makes sydbox very easy to set up and use. Moreover, sydbox allows the user to configure the sandbox dynamically from within the sandbox, and lock it as necessary afterwards. This comes at a cost though. sydbox makes use of SECCOMP_USER_NOTIF_FLAG_CONTINUE to resume system calls after dereferencing pointer arguments, and hence the sandbox is vulnerable to Time-of-check to time-of-use attacks. This is something we accept and live with. That said sydbox takes some mild precautions to make TOCTOU attacks less likely such as disallowing system calls which can access remote process memory such as ptrace and process_vm_writev, and disallowing write access to /proc/${pid}/mem. This makes the attack vectors much harder to realize.

COPYRIGHT

SPDX-License-Identifier: GPL-3.0-or-later

ChangeLog

3.0.0-beta.3

Run tests as integration tests, drop the test-bin development dependency.

3.0.0-beta.2

Added the new user sandbox profile which allows access to user-specific directories such as HOME, and connections such as X, screen, tmux etc. When invoked without arguments, syd now drops to a shell with this profile.
Replace regex crate with the more lightweight and performant regex-lite crate.
Implement the cmd/exec sandbox command and the syd exec subcommand.
Switch from glob crate to the glob-match crate for matching glob patterns.
Fallback to /proc/$pid/mem if cross memory attach is not enabled in the kernel. Use SYD_PROC_MEM environment variable or the sandbox command trace/memory_access:1 to force /proc fallback.
exec/kill_if_match has been renamed to exec/kill which is a breaking change.
Set panic = abort in release builds for reduced binary size.
Name the polling thread syd-poll.
Better error handling, and cleaner code.
Use parking_lot crate for Mutex, and RwLock.
The default magic virtual device path has been updated from /dev/sydbox to /dev/syd saving three letters on each typing!! This is a breaking change.
The core/ prefix has been removed from the configuration items core/sandbox, e.g use sandbox/exec:on rather than core/sandbox/exec:on. allowlist/successful_bind has been renamed to trace/allow_successful_bind, and allowlist/unsupported_socket_families has been renamed to trace/allow_unsupported_socket_families. Moreover the config item core/trace/magic_lock has been renamed to simply lock. This is a breaking change.
The prefixes unix:, unix-abstract:, inet:, inet6: are no longer used in network addresses. Instead the pattern is treated as a UNIX shell style pattern if it starts with /, and as an IP address otherwise. There is no distinction between unix sockets and abstract unix sockets anymore. This is a breaking change. Check the data/ subdirectory for a sydbox.bash for use with Paludis.
Fix a bug with remote path canonicalization.
Access violations are logged to syslog now. Use, e.g. journalctl SYSLOG_IDENTIFIER=syd to view them.

3.0.0-alpha.2

When run without arguments, sydbox now drops into user's current running shell allowlisting the HOME directory.
Document the CLI option -p, --profile and add noipv4 and noipv6 profiles in addition the paludis profile. These profiles may be stacked by specifying more than one -p arguments.
Use a Seccomp BPF filter rather than a Notify filter for fakeroot mode.
Improve logging to achieve consistency. We have a very simple Logger which logs to standard error in format JSON lines. There are some common keys id is always syd, l gives the Log::Level as an integer whereby the lower the value of the integer the more severe is the log condition. t gives a UNIX time stamp in seconds, and ctx has short context on the log entry. Errors are represented with the err key, and system call names are given with the sys key.
The --profile <profile-name> and --config @<profile-name> is now supported. Paludis uses the former so it is important for compatibility. The profile file is no longer installed under ${sharedir}/sydbox where {sharedir} is usually /usr/share and is kept as a static array in the program itself. In the future when sydbox-3 has an exheres we can improve on this but for now this gets us going.
The setuid system call is now allowed in the sandbox.
Use snmalloc as the global allocator for improved performance.

3.0.0-alpha.1

New: Added core/allowlist/successful_bind.
- Utilizes getsockname hook, pidfd_getfd, and process_vm_writev for complete emulation.
- Features a TTL of 3 mins for tracking addresses to manage zero port arguments in bind() system calls.
Improved: Refined read, write, network/{bind,connect} sandboxing.
- Simpler implementation, yet compatible with Paludis via esandbox.
- No per-process sandboxing or process tree tracking; uses /proc/$pid/cwd when required.
- Single set of sandbox rules with configurations pushed upfront.
- API Change: Replaced allow, deny modes with simpler on/off toggle.
- core/sandbox/network can be set to bind or connect for selective sandboxing.
- Rule matching favors the latest rule for configuration stacking.
- Streamlined core/trace/magic_lock:exec due to lack of parent/child tracking.
New: Introduced seccomp process supervision.
- Implemented primarily in syd::hook and syd::remote.
- Derived from the greenhook crate, but with a deny-by-default seccomp policy.
- Allowlisted system calls maintained in syd::config (currently immutable by users).
- Notable system calls like ptrace, process_vm_writev, and io-uring are disabled to counteract TOCTOU vulnerabilities.

syd 3.0.0-beta.3