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 `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 protections.

**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`.

**NOTE:** Pandora is in its early stages of development. To be able to use pandora
you should clone SydBox from [git](https://git.exherbo.org/git/sydbox-1.git) and
build SydBox from the **inspect** branch.

Browse at https://git.exherbo.org/sydbox-1.git/?h=inspect

SydBox requires [Pink's Tracing Library](http://dev.exherbo.org/~alip/pinktrace/api/c/)

- 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/).

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) 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) 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](https://dev.exherbo.org/~alip/sydbox/sydbox.html) 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 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!**

Documentation
=============

Read the fine manual of [SydBox](https://dev.exherbo.org/~alip/sydbox/sydbox.html) and [SydFmt](https://dev.exherbo.org/~alip/sydbox/sydbox.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 : -->
