SYD(5)

NAME

syd - document format for writing Syd profiles

API

Current version of the Syd command API is 3. This version is stable.

CONFIGURATION

Syd is configured through sandbox commands. For multiple matching rules (e.g. two rules matching the same path), the last matching rule wins. There are two ways to supply sandbox commands. First, Syd may be configured using a configuration file. The path to the configuration file is speficied using the -P command line switch. More than one configuration file may be specified this way. Single commands may also be passed via -m command line switch. Configuration profiles may be applied using the -p command line switch. See the PROFILES section for more information. Second, Syd may be configured using magic stat(2) calls during runtime. This is achieved by calling stat(2) 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(2) was chosen because it is practical to invoke using builtin shell commands like:

    ; test -c /dev/syd/sandbox/read:on

which enables Read Sandboxing for a shell running under Syd. It is also possible to query certain values using the return value of the stat(2) call:

    test -c /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(2), lstat(2), newfstatat(2), or statx(2). Syd supports the same interface through all these system calls transparently. Check the manual page syd(2) for a description of the stat(2) interface.

NAMING

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

SYNTAX

Input files must use the UTF-8 encoding. Config format is line oriented. Comments start with "#". Inline comments are not supported. Blank lines are ignored. All the other lines are treated as if they were supplied to Syd via the -m command line switch. For a list of available sandbox commands, consult syd(2). For a VIM syntax file for Syd profiles check here: https://gitlab.exherbo.org/sydbox/sydbox/-/tree/main/vim

As of verson 3.15.1, Syd adds two additional features to configuration file parsing:

1.  Enviroment variable expansion is performed on arguments. Notably, unset environment variables are not expanded to empty strings. On environment variable lookup errors and UTF-8 decoding errors Syd stops parsing and exits with error. This is done for safety as an unintended empty-string expansion can potentially cause the resulting sandboxing rule to allowlist unintended paths without the user easily noticing it. The user is recommended to set default values for environment variables using the familiar "${HOME:-/var/empty}" notation. If you really want empty-string expansion on unset environment variables, you can get this effect using the notation "${HOME:-}" but this is not recommended and should be used with care.
2.  "include" directives can be used to request the inclusion of another configuration file. Upon reading an include line, Syd stops parsing the current file, validates the given include path and start to parse the new configuration file. The file must not be writable by group or others for safety. For include files with relative paths, Syd searches the file under the directory of the previous configuration file rather than the current working directory for safety and ease of configuration. Loops in include directives are detected by caching the device id and inode of the configuration files. Note, this directive is not permitted when loading configuration from a file descriptor using the "load" command.

As of version 3.17.6, Syd adds the "include_profile" directive which may be used to include a Syd profile. See "syd-cat -p list" for the list of profiles.

PROFILES

Syd has a number of predefined profiles to make configuration easier. These profiles may be used standalone or stacked with other profiles and custom configuration to create various levels of isolation and confinement. To see the complete list of profiles, use "syd-cat -p list". To list the rules of a profile, use "syd-cat -p <profile-name>". Below you may find a brief list of common profiles and their functionality:

container | Enables Linux namespaces.
 | You may refer to this profile shortly as just c.
immutable | Enables Linux namespaces and remounts the following directories read only in the new mount namespace:
 | /etc, /home, /media, /mnt, /opt, /srv, and /usr.
 | Further mount options such as nodev, noexec, nosuid, and noatime are also applied as necessary.
 | In addition, /dev/shm and /tmp are mounted private and kernel filesystems are masked.
 | See syd-cat -p immutable for the full list of mount options.
 | You may refer to this profile shortly as just i.
privileged | Do not drop Linux capabilities at startup. Used to construct privileged containers.
 | You may refer to this profile shortly as just p.
landlock | Enables LandLock and allows system directories for Lock Sandboxing.
 | You may refer to this profile shortly as just l.
linux | Common Linux system profile, used by oci, paludis and user profiles.
oci | Used by syd-oci(1) as the default container profile.
paludis | Used by the Paludis package mangler.
noipv4 | Disables IPv4 connectivity.
 | You may refer to this profile shortly as just 6.
noipv6 | Disables IPv6 connectivity.
 | You may refer to this profile shortly as just 4.
core | Allows generation of coredumps.
 | You may refer to this profile shortly as just C.
debug | Allows debuggers inside the sandbox.
 | Syd does not use ptrace(1) with this profile, so tracers may attach.
 | You may refer to this profile shortly as just D.
nomem | Allows unsafe memory (no W^X, no Memory-Deny-Write-Execute, allows e.g. JITs).
 | You may refer to this profile shortly as just M.
nopie | Relaxes PIE (Position Independent Executable) restriction.
 | You may refer to this profile shortly as just P.
quiet | Silences all access violations.
 | You may refer to this profile shortly as just q.
off | Turns all sandboxing off.
lib | libsyd helper profile. Turns all sandboxing off and sets sandbox lock to "exec".
 | Useful to configure Syd in the application using libsyd.
user | Allows user-specific directories, and connections, and parses the files
 | /etc/user.syd-3, and ~/.user.syd-3 if they exist.
 | Syd sets the environment variables UID, GID, USER, HOME before parsing this profile.
 | To enforce system-wide settings, set "lock:on" at the end of /etc/user.syd-3.
 | You may refer to this profile shortly as just u.
kvm | Profile to allowlist KVM ioctl(2) requests without path check.
 | Read: https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt
tty | Profile to allow TTY access, used by oci, paludis, and user profiles.
 | Syd sets the environment variable TTY before parsing this profile.
 | If the process has no controlling terminal, TTY variable is set to "/dev/null".

  Stacking Profiles

It is possible to stack multiple profiles to configure a more restricted sandbox. Remember the order you stack the profiles matter, the last matching rule wins. Below are some examples:

•   syd -puser -pimmutable -mroot:/mnt/gnu ...
•   syd -ppaludis -plandlock -mallow/lock/write+/var/tmp ...

It is also possible to combine the one character shortcuts of helper profiles, in order to stack them together. Below are some examples:

•   syd -pMPX ... # Disable MDWE, PIE and exec restrictions.
•   syd -puis ... # Parse user profile, create an immutable container, and silence access violations.

  Login shell and the User Profile

When invoked without arguments, /bin/sh is executed under Syd with the user profile as a login shell, use SYD_SH environment variable to override the shell to execute.

SECURITY

As of version 3.30.0, Syd aborts with error if path to a specified configuration file has a symbolic link in any of its path components.

Therefore, the user must supply canonicalized paths as configuration file arguments.

EXAMPLE

    # Syd profile for OpenNTPD
    # Seccomp sandbox
    sandbox/read,stat,write,exec,net:on
    # Landlock
    sandbox/lock:on
    # Provide isolation using namespaces.
    unshare/mount,uts,pid,ipc,cgroup:1
    # Allow adjtimex and keep CAP_SYS_TIME.
    trace/allow_unsafe_time:1
    # Mount everything ro except /var
    bind+tmpfs:/dev/shm:nodev,nosuid,noexec
    bind+tmpfs:/tmp:nodev,nosuid
    bind+/etc:/etc:ro,nodev,noexec,nosuid,noatime
    bind+/home:/home:ro,nodev,noexec,nosuid,noatime
    bind+/media:/media:ro,nodev,noexec,nosuid,noatime
    bind+/mnt:/mnt:ro,nodev,noexec,nosuid,noatime
    bind+/opt:/opt:ro,nodev,nosuid,noatime
    bind+/srv:/srv:ro,nodev,noexec,nosuid,noatime
    bind+/usr:/usr:ro,nodev,noatime
    # Hide Syd
    deny/read,stat,write+/proc/1/***
    # Allow listen to the ntp port on loopback.
    allow/net/bind+loopback!123
    # Allow connections to NTP servers.
    allow/net/connect+any!53
    allow/net/connect+any!123
    allow/net/connect+any!65535
    # Allow logging to syslog.
    allow/net/connect+/dev/log
    # Allow `listen wildcard`
    allow/net/bind+0.0.0.0!0
    allow/net/connect+0.0.0.0!0
    # Allow listen to the ntpd socket.
    allow/net/bind+/run/ntpd.sock
    allow/net/bind+/var/run/ntpd.sock
    allow/write+/run/ntpd.sock
    allow/write+/var/run/ntpd.sock
    # Allow access to system paths
    allow/read,stat+/dev/urandom
    allow/lock/read+/dev/urandom
    allow/read,stat+/etc/hosts
    allow/lock/read+/etc/hosts
    allow/read,stat+/etc/ntpd.conf
    allow/lock/read+/etc/ntpd.conf
    allow/read,stat+/etc/passwd
    allow/lock/read+/etc/passwd
    allow/read,stat+/etc/resolv.conf
    allow/lock/read+/etc/resolv.conf
    allow/read,stat+/etc/services
    allow/lock/read+/etc/services
    allow/read,stat+/usr/share/zoneinfo-posix/UTC
    # chroot /var/empty && cd /
    allow/stat+/
    allow/stat+/var/empty
    allow/write+/dev/null
    allow/lock/write+/dev/null
    # Allow executing the ntp binary.
    allow/lock/read+/proc
    allow/lock/read+/usr
    allow/lock/write+/run
    allow/lock/write+/var/run
    allow/exec+/usr/**/bin/openntpd*
    # Allow writing the drift file.
    allow/write+/var/db/ntpd.drift
    allow/lock/write+/var/db/ntpd.drift
    # Lock configuration
    lock:on

SEE ALSO

syd(1), syd(2), syd(7)

syd homepage: https://sydbox.exherbolinux.org/

AUTHORS

Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and 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.