sydbox / sydbox-1

seccomp-bpf & seccomp-notify based sandbox for modern Linux machines to sandbox unwanted process access to filesystem and network resources. This is a FREQUENTLY UPDATED MIRROR. You are welcome to use issues and pull requests here if you feel like it. Main git repo is on git.exherbo.org, development happens on sr.ht where bug tracker and mailing lists are present. Thank you.

The ☮ther SⒶndbøx

SydB☮x is a seccomp based sandbox for modern Linux machines to sandbox unwanted process access to filesystem and network resources.

• sydB☮x written in portable C and licensed GPLv2.
• libsyd is written in portable C and licensed GPLv2.

SydB☮x requires no r☮☮t Ⓐccess and no ptrace 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 SydB☮x: bring easy, simple, flexible and powerful security to the Linux user!

The basic idea of SydB☮x is to run a command under certain restrictions. These are the seccomp restrictions which restricts system calls and SydB☮x' command line flags to create new namespaces (containers), change user, change group, add additional groups, change directory, chroot into directory, change the root mount, and various other daemon options (cgroups support is work in progress.). See the SydB☮x manual page for details.

Run SydB☮x without arguments to drop into the SydB☮x shell which is running in a new pid, user, mount, net, time and cgroup namespace with its home under a temporary directory under »/tmp«, with read, write, exec and network sandboxing modes set to »deny« but with unlocked sandbox status which is insecure, try syd ipc kill 9 as an example on why, but allows the user to configure the SydB☮x using the stat(2) IPC using the special »/dev/sydb☮x« device node. See syd ipc --help for details. Use syd ipc lock to switch to secure mode under SydB☮x or run SydB☮x with sydbox --lock.

Secure Computing Mode, also known as »Seccomp« allows the user to define restrictions on 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.

1. seccomp-bpf can be used to apply simple Secure Computing user filters to run sandboxing fully on kernel space, and
2. 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 operation canceled -- or kill the process running the system call, or kill all processes at once with SIGKILL.

See: https://sydbox.exherbo.org

For updates, check out my blog at https://pink.exherbo.org

Build & Requirements

SydB☮x uses autotools and cargo. To build, simply do ./configure, make, make -j check and sudo make install. Make sure you have cargo and cbindgen under PATH. By default this will produce a statically linked SydB☮x binary. If you want use dynamic linking, give the --disable-static option to ./configure.

Make sure you have xsltproc under PATH if you want to build the manual page. You may also browse the manual of the latest version at https://sydbox.exherbo.org.

To use SydB☮x you need a Linux kernel with version 5.6 or newer which includes the secure computing mode with the SECCOMP_USER_NOTIF_FLAG_CONTINUE facility, and the system calls pidfd_send_signal, and pidfd_getfd.

In addition, it is recommended that you enable the kernel option CONFIG_CROSS_MEMORY_ATTACH so that SydB☮x can use the system calls process_vm_readv and process_vm_writev. These system calls are available in Linux since 3.2. Note SydB☮x will use the file /proc/pid/mem if these system calls are unavailable or not working so this is not a hard dependency.

For more information about these requirements, check the following links:

• kernelnewbies.org/Linux-5.6
• LWN article about pidfd_getfd
• SECCOMP_USER_NOTIF_FLAG_CONTINUE: commit, commit, and commit.

Sandboxing

See the SydB☮x manual page on more information about secure computing mode protections. The parts which are of particular interest to read are:

• Sandboxing
• core/restrict/general
• core/restrict/io_control
• core/restrict/memory_map
• core/restrict/shared_memory_writable

SydB☮x & Pand☮ra

NOTE: Pand☮ra is in its early stages of development. To be able to use Pand☮ra you need Sydb☮x-2.2.0 or later.

.	@
Tar	https://dev.exherbo.org/~alip/sydbox/sydbox-2.2.0.tar.bz2
SHA	https://dev.exherbo.org/~alip/sydbox/sydbox-2.2.0.tar.bz2.sha1sum
GPG	https://dev.exherbo.org/~alip/sydbox/sydbox-2.2.0.tar.bz2.sha1sum.asc
Git	https://git.exherbo.org/git/sydbox-1.git
Ann	https://pink.exherbo.org/sydbox-v2.0.1/

• Browse: https://git.exherbo.org/sydbox-1.git/
• Exheres:
  • sydbox.exlib
  • sydbox-2.2.0.exheres-0

You can check the build options using sydbox --version:

$ sydbox --version
sydbox-2.2.0
Options: dump:yes seccomp:yes ipv6:yes netlink:yes

To see if your system is supported by SydB☮x, use sydbox ---test:

$ sydbox --test
sydbox: Linux/chesswob 5.12.10
sydbox: [>] Checking for requirements...
sydbox: [*] cross memory attach is functional.
sydbox: [*] /proc/pid/mem interface is functional.
sydbox: [*] pidfd interface is functional.
sydbox: [*] seccomp filters are functional.
sydbox: [>] SydB☮x is supported on this system!

To verify SydB☮x is working correctly, either use make -j check during installation or use the helper utility syd-test to run the installed tests.

Pand☮ra

https://pandora.exherbo.org

Pand☮ra's Box: A helper for SydB☮x, a ptrace & seccomp based sandbox to make sandboxing practical. This makes it easy for the end user to use secure computing for practical purposes.

pandora sandbox

SydB☮x may be configured through the magic path /dev/sydbox which is a virtual path that exists solely for inter-process communication with the sandbox to configure and extend it. In Exherbo, we have the command esandbox to interface with the sandbox. The subcommand pandora sandbox provides the exact same interface.

Note: pandora sandbox works as long as the magic lock of Sydb☮x is not locked either via the magic command core/trace/magic_lock:on or via the command-line option --lock. You may also lock the magic command using pandora with pandora sandbox lock after which no more sandboxing commands are permitted.

Here's a list of pandora sandbox commands:

Querying sandbox status

• check: Check whether the program is being executed under sandboxing.
• enabled or enabled_path: Check whether path sandboxing is enabled.
• enabled_exec: Check whether exec sandboxing is enabled.
• enabled_net: Check whether network sandboxing is enabled.

Turning sandboxing on/off

• enable or enable_path: Enable path sandboxing.
• disable or disable_path: Disable path sandboxing.
• enable_exec: Enable exec sandboxing.
• disable_exec: Disable exec sandboxing.
• enable_net: Enable network sandboxing.
• disable_net: Disable network sandboxing.

Whitelisting

• allow or allow_path: Whitelist a path for path sandboxing. Takes one extra argument which must be an absolute path.
• disallow or disallow_path: Removes a path from the path sandboxing whitelist. Takes one extra argument which must be an absolute path.
• allow_exec: Whitelist a path for execve() sandboxing. Takes one extra argument which must be an absolute path.
• disallow_exec: Removes a path from the execve() sandboxing whitelist. Takes one extra argument which must be an absolute path.
• allow_net: Whitelist a network address for bind() whitelist - or for connect() whitelist if --connect option is given.
• disallow_net: Removes a network address from the bind() whitelist - or from connect() whitelist if --connect option is given.

Filtering

• addfilter or addfilter_path: Add a pattern as a path sandboxing filter. Takes one extra argument which is a fnmatch() pattern.
• rmfilter or rmfilter_path: Removes a pattern from the path sandboxing filter list. Takes one extra argument which is a fnmatch() pattern.
• addfilter_exec: Add a pattern as a execve() sandboxing filter. Takes one extra argument which is a fnmatch() pattern.
• rmfilter_exec: Removes a pattern from the execve() sandboxing filter list. Takes one extra argument which is a fnmatch() pattern.
• addfilter_net: Add a network address as a network sandboxing filter. Takes one extra argument which is a network address.
• rmfilter_net: Removes a pattern from the network sandboxing filter list. Takes one extra argument which is a network address.

Miscellaneous commands

• lock: Lock magic commands. After calling this none of the »sandboxcommands will work. You don«t need to call this, seeexec_lock`.
• exec_lock: Lock magic commands upon execve().
• wait_eldest: By default, sydbox waits for all traced processes to exit before exiting. However, this isn't desired in some cases. For example when a daemon, like udev, is restarted from within an exheres which will go on its execution after installation. This command makes sydbox resume all processes and exit after the eldest process has exited.
• wait_all: Wait for all processes before exiting. This is the default.

Specifying Network Addresses

Network addresses may be specified in the following forms:

• unix:FNMATCH_PATTERN
• unix-abstract:FNMATCH_PATTERN
• inet:ipv4_address/NETMASK@PORT_RANGE
• inet6:ipv6_address/NETMASK@PORT_RANGE

where /NETMASK can be omitted and PORT_RANGE can either be a number or two numbers in the form BEGIN-END. In addition, there are a few network aliases that are expanded to network addresses. They are listed below:

• LOOPBACK is expanded to inet://127.0.0.0/8
• LOOPBACK6 is expanded to inet6://::1/8
• LOCAL is 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 is expanded to four addresses:
  • inet6:::1
  • inet6:fe80::/7
  • inet6:fc00::/7
  • inet6:fec0::/7

So you may use LOOPBACK@0 instead of inet:127.0.0.0/8@0

Example 1: Restricted Login Shell

When run without arguments Sydb☮x drops into a restricted login shell. This is the default sandboxing profile installed by Sydb☮x and may also be used as basic config for other applications. It's installed under $sharedir/sydbox/default.syd-2 where $sharedir is usually /usr/share.

Note: By default, Sydb☮x allows interacting with the sandbox. Try with syd --lock to disable this for a more real jail experience. Note in this mode /dev/sydbox is inaccessible.

Here is a screenshot:

Example 2: Sandbox Firefox

Step 1: Inspect and gather data about the given process.

In this case, we're going to try with https://www.mozilla.org/de/firefox/new/.

$ pandora profile firefox

Browse using firefox for a while, let pandora gather data. The browser is running under a tracer so it'll run noticably slower.

• use --bin /path/to/sydbox, if sydbox is not in PATH
• use --output firefox.syd-2 to specify an alternative output path for profile.

$ $EDITOR out.syd-2

Inspect what the browser has been doing. Enable, disable additional options or turn paths into wildcards such as /home/*** to allow home and everything beyond /home the usual glob characters, ?, * are supported.

Check SydB☮x manual page to learn more on how PATTERN MATCHING works.

Enable, disable additional network addresses unless you're using a SOCKS5 proxy which does remote DNS lookups, e.g:

allowlist/network/connect+inet:127.0.0.1@9050

for Tor.

Check SydB☮x manual page to learn more on how ADDRESS MATCHING works.

$ pandora box -c out.syd-2 firefox

• Run the browser under secure computing with full protection.

• Check SydB☮x manual page for a list of system call protections.

• Check the console for possible access violations over time.

• Edit the profile file as necessary and update restrictions.

For instance if you see an access violation such as

sydbox: 8< -- Access Violation! --
sydbox: connect(-1, unix:/run/user/1000/pulse/native)
sydbox: proc: AudioIPC Server[754336] (parent:0)
sydbox: cwd: »/home/alip/src/exherbo/sydbox-1«
sydbox: cmdline: »/usr/lib/firefox/firefox «
sydbox: >8 --
sydbox: 8< -- Access Violation! --
sydbox: connect(-1, unix:/var/run/pulse/native)
sydbox: proc: AudioIPC Server[754336] (parent:0)
sydbox: cwd: »/home/alip/src/exherbo/sydbox-1«
sydbox: cmdline: »/usr/lib/firefox/firefox «
sydbox: >8 --

This sounds like you're trying to play some audio on your browser. In this case, you should add an allowlist to your profile .syd-2 file and restart your browser under this new profile.

allowlist/connect/network+unix:/run/pulse/native
allowlist/connect/network+unix:/var/run/pulse/native

Note, sometimes you may have to add a symbolic link rather than the file it is pointing to, or vice versa, or both.

Last but not least,

Share your profile with other people and help others use secure computing!

Here is a Firefox profile edited by yours truly:

https://git.exherbo.org/sydbox-1.git/plain/data/firefox.syd-2

PinkTrace

If you do not have a very recent Linux version, you may use Sydb☮x-1.2.1 which requires Pink's Tracing Library

NOTE: SydB☮x-2.0.1 and newer do not use ptrace() but use seccomp user notify facilities in recent Linux kernels 5.6 and newer. Hence, PinkTrace is no longer a dependency.

See: https://pinktrace.exherbo.org

• Exheres:
  • pinktrace-1.exlib
  • pinktrace-scm.exheres-0
• Git: https://git.exherbo.org/git/pinktrace-1.git
• Lightweight ptrace wrapper library providing a robust API for tracing processes.
• An extensive API reference is available here.
• Tar: https://dev.exherbo.org/distfiles/pinktrace/pinktrace-0.9.6.tar.bz2
• Git: https://git.exherbo.org/git/pinktrace-1.git

Bugs

Read BUGS.

Below are the details of the author. Mail is preferred. Attaching poems encourages consideration tremendously.

Hey you, out there beyond the wall,
Breaking bottles in the hall,
Can you help me?

• Alï Polatel [e-mail]
• Exherbo: https://git.exherbo.org/dev/alip.git/
• Github: https://github.com/alip/
• Twitter: https://twitter.com/hayaliali
• Mastodon: https://mastodon.online/@alip
• IRC: alip at Libera

Git

• Original Git: https://git.exherbo.org/sydbox-1.git/
• Github Mirror: https://github.com/sydbox/sydbox-1

Github mirror is updated periodically. Feel free to submit an issue or a pull request there. Attaching poems encourages consideration tremendously.

Documentation

Read the fine manual of SydB☮x and SydFmt.

Blog Posts

• Sydb☮x: Stop Skype P2P/Call Home: People Have The Right To Communicate W\o Eavesdropping
• Recent Linux Changes Help Safe & Secure w\o Root
• A Study in Sydb☮x
• Pink's Tracing Library
• Sydb☮x Logo Survey
• Sydb☮x: Default Sandbox of Exherbo
• Disabling External Commands in Metadata Phase (Exherbo>Gentoo)
• ptrace on IA64
• Network Sandboxing and /proc (Exherbo>Gentoo)
• ptrace on FreeBSD
• Running Untrusted Binaries that Access the Network
• Proper Network Sandboxing (Exherbo>Gentoo)
• Deprecating addpredict (Exherbo>Gentoo)