Syd's Box
=========
SydBox is a [ptrace](http://man7.org/linux/man-pages/man2/ptrace.2.html) & [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.
SydBox uses autotools. To build, simply do `./configure`, `make` and `sudo make install`.
To use SydBox you need a recent [Linux](https://kernel.org) kernel, preferably 3.5
or newer which has [secure computing mode](https://en.wikipedia.org/wiki/Seccomp)
facility. Make sure you build SydBox with **--enable-seccomp** given to
`./configure`. SydBox works fine without it but it is going to be noticably slower
and less secure. 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:
- [core/trace/use_seccomp](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-trace-use_seccomp),
- [core/restrict/file_control](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-fcntl)
- [core/restrict/shared_memory_writable](https://dev.exherbo.org/~alip/sydbox/sydbox.html#core-restrict-shm-wr)
**NOTE**: [Secure computing mode](https://en.wikipedia.org/wiki/Seccomp) only works
on `i386` and `x86_64` architectures.
In addition, it is advised that you enable the kernel option
`CONFIG_CROSS_MEMORY_ATTACH=y` so that SydBox can use the functions
[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:** Pandora is in its early stages of development. To be able to use Pandora
you need **Sydbox-1.2.0** or later.
- Tar: https://dev.exherbo.org/~alip/sydbox/sydbox-1.2.0.tar.bz2
- SHA: https://dev.exherbo.org/~alip/sydbox/sydbox-1.2.0.tar.bz2.sha1sum
- GPG: https://dev.exherbo.org/~alip/sydbox/sydbox-1.2.0.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-1.1.0-pandora-0.0.3-1-gc96f237 (pinktrace-0.9.5 git:v0.9.5-1-ge6ac27f)
Options: dump:yes seccomp:yes ipv6:yes netlink:yes
```
- **seccomp:yes** indicates **--enable-seccomp** was passed on build.
- **ipv6:yes** **IPv6 Network Sandboxing** is enabled.
SydBox requires [Pink's Tracing Library](http://dev.exherbo.org/~alip/pinktrace/api/c/)
- 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
Pandora
=======
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-1 to specify an alternative output path for profile.
```
$ $EDITOR out.syd-1
```
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:
***whitelist/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-1 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 a whitelist to your profile `.syd-1` file and restart your browser under
this new profile.
```
whitelist/connect/network+unix:/run/pulse/native
whitelist/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-1
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>Gentoo)](https://tinyurl.com/no-commands-in-metadata-phase)
* [ptrace on IA64](https://tinyurl.com/ptrace-on-ia64)
* [Network Sandboxing and /proc (Exherbo>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>Gentoo)](https://tinyurl.com/proper-network-sandboxing)
* [Deprecating addpredict (Exherbo>Gentoo)](https://tinyurl.com/deprecating-addpredict-gentoo)
<!-- vim: set tw=80 ft=markdown spell spelllang=en sw=4 sts=4 et : -->