// sydbox man page
// vim: set ts=4 sts=4 et tw=120 ft=asciidoc :
// Copyright (c) 2009, 2010 Ali Polatel <alip@exherbo.org>
// Distributed under the terms of the GNU General Public License v2
SYDBOX(1)
=========
:man source: sydbox
:man version: 0.7.2
:man manual: Sydbox Manual

NAME
----
sydbox - ptrace based sandbox

SYNOPSIS
--------
*sydbox* ['OPTION'] -- command [args]

DESCRIPTION
-----------
Sydbox is a sandboxing utility.

*Features*:::
- Ptrace based which means it can sandbox static binaries unlike *LD_PRELOAD* based sandbox utilities.
- Intercepts system calls and checks for allowed filesystem prefixes, denies them when checks fail.
- Basic support for disallowing network connections.
- Basic support for sandboxing execve(2) calls.

OPTIONS
-------
The ordering of option precedence is configuration file, environment variables, command line parameters.

*-?*::
*--help*::
    Show help options

*-V*::
*--version*::
    Print version information and exit

*-c*::
*--config*::
    Specify path to the configuration file

*-p*::
*--profile*::
    Specify profile of the configuration file, equal to specifying DATADIR/sydbox/NAME.conf as configuration file

*-D*::
*--dump*::
    Dump configuration and exit

*-0*::
*--log-level*::
    Logging verbosity

*-l*::
*--log-file*::
    Path to the log file

*-C*::
*--no-colour*::
    Disallow colouring of messages

*-L*::
*--lock*::
    Disallow magic commands

*-P*::
*--disable-sandbox-path*::
    Disable path sandboxing

*-E*::
*--sandbox-exec*::
    Enable execve(2) sandboxing

*-N*::
*--sandbox-network*::
    Enable network sandboxing

*-B*::
*--network-whitelist-bind*::
    Automatically whitelist bind() addresses

*-X*::
*--exit-with-eldest*::
    Finish tracing when eldest child exits

*-W*::
*--nowrap-lstat*::
    Disable the lstat() wrapper for too long paths

ENVIRONMENT VARIABLES
---------------------
The behaviour of sydbox is affected by the following environment variables.

SYDBOX_WRITE
~~~~~~~~~~~~~
This variable specifies the paths that are allowed to be written to. It is
expected to be a colon delimited list of paths.

SYDBOX_DISABLE_PATH
~~~~~~~~~~~~~~~~~~~~
If set, this variable disables path sandboxing. This is equivalent to the *-P*
option.

SYDBOX_EXEC
~~~~~~~~~~~~
This variable controls the behaviour of sydbox with regard to execve(2) access.
If it is set, sydbox will sandbox execve(2) connections. This is equivalent to
*-E* option.

SYDBOX_EXEC_ALLOW
~~~~~~~~~~~~~~~~~~
This variable specifies the paths that execve(2) access is allowed. It is
expected to be a colon delimited list of paths. This is only used when execve(2)
sandboxing is on.

SYDBOX_NET
~~~~~~~~~~~
This variable controls the behaviour of sydbox with regards to network access.
If it is set, sydbox will deny network connections. This is equivalent to *-N*
option.

SYDBOX_NET_WHITELIST_BIND
~~~~~~~~~~~~~~~~~~~~~~~~~
This variable is a semicolon delimited list of whitelisted network connections for the bind() system call.
The values can be in one of 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*

SYDBOX_NET_WHITELIST_CONNECT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This variable is a semicolon delimited list of whitelisted network connections for the connect() system call.
The address format is the same as SYDBOX_NET_WHITELIST_BIND.

SYDBOX_NET_AUTO_WHITELIST_BIND
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This variable, if specified, makes sydbox automatically add bind() calls to the connect() whitelist.
This is equivalent to *-B* option.

SYDBOX_CONFIG
~~~~~~~~~~~~~~
This variable specifies the configuration file to be used by sydbox. This is
equivalent to the *-c* option.

SYDBOX_NO_COLOUR
~~~~~~~~~~~~~~~~~
This variable controls the behaviour of sydbox with regards to colourized
output. If it is set, sydbox's output will not be coloured. This is equivalent
to the *-C* option.

SYDBOX_LOG
~~~~~~~~~~~
This variable specifies the log file to be used by sydbox. This is equivalent to
the *-l* option.

SYDBOX_LOCK
~~~~~~~~~~~~
If this variable is set, sydbox will disallow magic commands. This is equivalent
to *-L* option.

SYDBOX_EXIT_WITH_ELDEST
~~~~~~~~~~~~~~~~~~~~~~~
If this variable is set, sydbox will finish tracing when the eldest child exits.
This is equivalent to the *-X* option.

SYDBOX_NOWRAP_LSTAT
~~~~~~~~~~~~~~~~~~~
If this variable is set, sydbox won't use its lstat() wrapper for too long paths.
This is equivalent to the *-W* option.

SYDBOX_USER_CONFIG
~~~~~~~~~~~~~~~~~~
If this variable is set, sydbox will use the config file supplied as a suppliment to any other config files sydbox would
already use. The exception is that sydbox will only *update* various lists using this configuration file. Other
variables may not be altered this way.

MAGIC COMMANDS
--------------
Sydbox has a concept of magic commands to interact with it during its run.
These commands are special system calls that sydbox recognizes and does things
according to the command. Currently there's one type of magic commands:

- Magic commands based on stat(2)
  * */dev/sydbox/off*               stat'ing this path turns off path sandboxing.
  * */dev/sydbox/on*                stat'ing this path turns on path sandboxing.
  * */dev/sydbox/toggle*            stat'ing this path toggles path sandboxing.
  * */dev/sydbox/lock*              stat'ing this path locks magic commands.
  * */dev/sydbox/exec_lock*         stat'ing this path locks magic commands when an execve(2) is encountered.
  * */dev/sydbox/wait/all*          stat'ing this path sets wait mode to all.
  * */dev/sydbox/wait/eldest*       stat'ing this path sets wait mode to eldest.
  * */dev/sydbox/wrap/lstat*        stat'ing this path enables the lstat() wrapper for too long paths.
  * */dev/sydbox/nowrap/lstat*      stat'ing this path disables the lstat() wrapper for too long paths.
  * */dev/sydbox/sandbox/exec*      stat'ing this path turns on execve(2) sandboxing.
  * */dev/sydbox/sandunbox/exec*    stat'ing this path turns off execve(2) sandboxing.
  * */dev/sydbox/sandbox/net*       stat'ing this path turns on network sandboxing.
  * */dev/sydbox/sandunbox/net*     stat'ing this path turns off network sandboxing.
  * */dev/sydbox/write/PATH*        stat'ing this path adds *PATH* to the list of write allowed paths.
  * */dev/sydbox/unwrite/PATH*      stat'ing this path removes *PATH* from the list of write allowed paths.
  * */dev/sydbox/addexec/PATH*      stat'ing this path adds *PATH* to the list of execve(2) allowed paths.
  * */dev/sydbox/rmexec/PATH*       stat'ing this path removes *PATH* from the list of execve(2) allowed paths.
  * */dev/sydbox/addfilter/PATTERN* stat'ing this path adds *PATTERN* to the list of path violation filters
  * */dev/sydbox/rmfilter/PATTERN*  stat'ing this path removes *PATTERN* from the list of path violation filters
  * */dev/sydbox/addfilter_exec/PATTERN* stat'ing this path adds *PATTERN* to the list of exec violation filters
  * */dev/sydbox/rmfilter_exec/PATTERN*  stat'ing this path removes *PATTERN* from the list of exec violation filters
  * */dev/sydbox/addfilter_net/ADDR* stat'ing this path adds *ADDR* to the list of network violation filters
  * */dev/sydbox/rmfilter_net/ADDR*  stat'ing this path removes *ADDR* from the list of network violation filters
  * */dev/sydbox/net/whitelist/bind/ADDR*   stat'ing this path adds the given address to the bind() whitelist.
  * */dev/sydbox/net/unwhitelist/bind/ADDR* stat'ing this path removes the given address from the bind() whitelist.
  * */dev/sydbox/net/whitelist/connect/ADDR*   stat'ing this path adds the given address to the connect() whitelist.
  * */dev/sydbox/net/unwhitelist/connect/ADDR* stat'ing this path removes the given address from the connect() whitelist.
  * */dev/sydbox*                   stat'ing this path succeeds if magic commands are allowed.
  * */dev/sydbox/enabled*           stat'ing this path succeeds if path sandboxing is on, fails otherwise.

RETURN VALUE
------------
sydbox returns the return code of the executed program under most cases. In case the program is killed with a signal
sydbox returns 128 + *SIGNAL*.

SEE ALSO
--------
ptrace(1)

AUTHORS
-------
Ali Polatel <alip at exherbo dot org>

Saleem Abdulrasool <compnerd at compnerd dot org>

REPORTING BUGS
--------------
Report bugs to /dev/null.

COPYRIGHT
---------
Copyright (C) 2009, 2010 Ali Polatel <alip at exherbo dot org>

Copyright (C) 2009 Saleem Abdulrasool <compnerd at compnerd dot org>

Free use of this software is granted under the terms of the GNU General Public License (GPL).

