# Syd's Box

<img src="https://dev.exherbo.org/~alip/images/sydbox160.png" alt="SydBox" title="img: That cat's something I can't explain!"/>

SydBox is a [seccomp](http://man7.org/linux/man-pages/man2/seccomp.2.html) based
sandbox for modern [Linux](https://kernel.org) machines to sandbox unwanted process
access to filesystem and network resources.

See: https://sydbox.exherbo.org

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

## Build &amp; Requirements

SydBox uses autotools. To build, simply do `./configure`, `make`, `make -j check`
and `sudo make install`. By default this will produce a statically linked *SydBox* binary.
If you want use dynamic linking, give the `--disable-static` option to `./configure`.

To use SydBox you need a [Linux](https://kernel.org) kernel with version 5.11 or
newer which includes [the secure computing mode](https://en.wikipedia.org/wiki/Seccomp)
with the `SECCOMP_USER_NOTIF_FLAG_CONTINUE` facility,
and the system calls
[pidfd_send_signal](https://man7.org/linux/man-pages/man2/pidfd_send_signal.2.html),
and [pidfd_getfd](https://man7.org/linux/man-pages/man2/pidfd_getfd.2.html).

In addition, it is recommended that you enable the kernel option
`CONFIG_CROSS_MEMORY_ATTACH` so that SydBox can use the system calls
[process_vm_readv](https://man7.org/linux/man-pages/man2/process_vm_readv.2.html)
and
[process_vm_writev](https://man7.org/linux/man-pages/man2/process_vm_readv.2.html).
These system calls are available in Linux since 3.2. Note SydBox will use the file
`/proc/pid/mem` if these system calls are unavailable or not working.

For more information about these requirements, check the following links:
- [kernelnewbies.org/Linux-5.6](https://kernelnewbies.org/Linux_5.6#A_new_pidfd_syscall.2C_pidfd_getfd.282.29)
- [LWN article about pidfd_getfd](https://lwn.net/Articles/808997/)
- `SECCOMP_USER_NOTIF_FLAG_CONTINUE`:
[commit](https://git.kernel.org/linus/fb3c5386b382d4097476ce9647260fc89b34afdb),
[commit](https://git.kernel.org/linus/223e660bc7638d126a0e4fbace4f33f2895788c4), and
[commit](https://git.kernel.org/linus/0eebfed2954f152259cae0ad57b91d3ea92968e8).

### PinkTrace

If you do not have a very recent Linux version, you may use Sydbox-1.2.1 which
requires [Pink's Tracing Library](http://dev.exherbo.org/~alip/pinktrace/api/c/)

**NOTE: SydBox-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](https://git.exherbo.org/arbor.git/tree/packages/dev-libs/pinktrace/pinktrace.exlib)
  - [pinktrace-scm.exheres-0](https://git.exherbo.org/arbor.git/tree/packages/dev-libs/pinktrace/pinktrace-scm.exheres-0)
- Git: https://git.exherbo.org/git/pinktrace-1.git
- Lightweight [ptrace](http://linux.die.net/man/2/ptrace) wrapper library
  providing a robust API for tracing processes.
- An extensive API reference is available [here](http://dev.exherbo.org/~alip/pinktrace/api/c/).
- Tar: https://dev.exherbo.org/distfiles/pinktrace/pinktrace-0.9.6.tar.bz2
- Git: https://git.exherbo.org/git/pinktrace-1.git

## Sandboxing

See the [SydBox manual
page](https://dev.exherbo.org/~alip/sydbox/sydbox.html) on more information about
[secure computing mode](https://en.wikipedia.org/wiki/Seccomp) protections. The
parts which are of particular interest to read are:

- [Sandboxing](https://dev.exherbo.org/~alip/sydbox/sydbox.html#sandboxing)
- [core/restrict/general](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-general)
- [core/restrict/io_control](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-ioctl)
- [core/restrict/memory_map](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-mmap)
- [core/restrict/shared_memory_writable](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-shm-wr)

## SydBox &amp; Pandora

**NOTE:** Pandora is in its early stages of development. To be able to use Pandora
you need **Sydbox-2.0.1** or later.

- Tar: https://dev.exherbo.org/~alip/sydbox/sydbox-2.0.1.tar.bz2
- SHA: https://dev.exherbo.org/~alip/sydbox/sydbox-2.0.1.tar.bz2.sha1sum
- GPG: https://dev.exherbo.org/~alip/sydbox/sydbox-2.0.1.tar.bz2.sha1sum.asc
- Git: https://git.exherbo.org/git/sydbox-1.git

- Browse: https://git.exherbo.org/sydbox-1.git/
- Exheres:
  - [sydbox.exlib](https://git.exherbo.org/arbor.git/tree/packages/sys-apps/sydbox/sydbox.exlib)
  - [sydbox-scm.exheres-0](https://git.exherbo.org/arbor.git/tree/packages/sys-apps/sydbox/sydbox-scm.exheres-0)

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

```
$ sydbox --version
sydbox-2.0.1
Options: dump:yes seccomp:yes ipv6:yes netlink:yes
```

To see if your system is supported by **SydBox**, 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: [>] SydBox is supported on this system!
```

To verify **SydBox** is working correctly, either use `make -j check` during
installation or use the helper utility `sydtest` to run the installed tests.

# Pandora

https://pandora.exherbo.org

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

Simple Example:

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/](Firefox).

```
$ 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 [SydBox manual page](https://dev.exherbo.org/~alip/sydbox/sydbox.html#pattern-matching) 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](https://www.torproject.org/).

Check [SydBox manual page](https://dev.exherbo.org/~alip/sydbox/sydbox.html#address-matching) 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 [SydBox manual page for a list of system call
  protections.](https://dev.exherbo.org/~alip/sydbox/sydbox.html#sandboxing)
- 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

# Bugs
Read [BUGS](https://git.exherbo.org/sydbox-1.git/plain/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** [alip@exherbo.org](mailto:alip@exherbo.org)
- **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](https://libera.chat/)

# 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 [SydBox](https://dev.exherbo.org/~alip/sydbox/sydbox.html) and [SydFmt](https://dev.exherbo.org/~alip/sydbox/sydfmt.html).

# Blog Posts

* [Sydbox: Stop Skype P2P/Call Home: People Have The Right To Communicate W\o Eavesdropping](https://tinyurl.com/sydbox-stop-skype-call-home)
* [Recent Linux Changes Help Safe & Secure w\o Root](https://tinyurl.com/recent-linux-changes-help-safe)
* [A Study in Sydbox](https://tinyurl.com/a-study-in-sydbox)
* [Pink's Tracing Library](https://tinyurl.com/pink-s-tracing-library)
* [Sydbox Logo Survey](https://tinyurl.com/sydbox-logo-survey)
* [Sydbox: Default Sandbox of Exherbo](https://tinyurl.com/sydbox-default-sandbox-exherbo)
* [Disabling External Commands in Metadata Phase (Exherbo&gt;Gentoo)](https://tinyurl.com/no-commands-in-metadata-phase)
* [ptrace on IA64](https://tinyurl.com/ptrace-on-ia64)
* [Network Sandboxing and /proc (Exherbo&gt;Gentoo)](https://tinyurl.com/network-sandboxing-and-proc)
* [ptrace on FreeBSD](https://tinyurl.com/ptrace-on-freebsd)
* [Running Untrusted Binaries that Access the Network](https://tinyurl.com/running-untrusted-binaries)
* [Proper Network Sandboxing (Exherbo&gt;Gentoo)](https://tinyurl.com/proper-network-sandboxing)
* [Deprecating addpredict (Exherbo&gt;Gentoo)](https://tinyurl.com/deprecating-addpredict-gentoo)

<!-- vim: set tw=80 ft=markdown spell spelllang=en sw=4 sts=4 et : -->
