Created
June 20, 2011 08:28
-
-
Save alip/1035301 to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| From 072fdfa7679f17193afb5d0704ba3792679ce115 Mon Sep 17 00:00:00 2001 | |
| Message-Id: <072fdfa7679f17193afb5d0704ba3792679ce115.1308556182.git.polatel@gmail.com> | |
| From: Ali Polatel <[email protected]> | |
| Date: Thu, 31 Mar 2011 14:17:46 +0300 | |
| Subject: [PATCH] initial attempt at documenting esandbox | |
| Organization: Pink Floyd | |
| --- | |
| eapi/exheres-for-smarties.mkd | 117 ++++++++++++++++++++++++++++++++++------ | |
| 1 files changed, 99 insertions(+), 18 deletions(-) | |
| diff --git a/eapi/exheres-for-smarties.mkd b/eapi/exheres-for-smarties.mkd | |
| index 18464ec..5fb3659 100644 | |
| --- a/eapi/exheres-for-smarties.mkd | |
| +++ b/eapi/exheres-for-smarties.mkd | |
| @@ -1115,19 +1115,7 @@ We probably want to ban these at some point. | |
| ### sydbox.bash | |
| -- `addwrite` | |
| - Adds a path to the list of write-allowed path prefixes. The argument must be an absolute path. | |
| - If the path argument of system calls starts with the given path prefix, it doesn't cause an | |
| - access violation and the system call is allowed. | |
| -- `rmwrite` | |
| - Removes the given path prefix from the list of write-allowed path prefixes. | |
| -- `addfilter` | |
| - Adds a pattern to the list of access violation filters. The argument is an | |
| - [fnmatch](http://linux.die.net/man/3/fnmatch) pattern. An access violation filter is a filter | |
| - which, if it matches, prevents the access violation from being raised. Unlike `addpredict` | |
| - the access to the system call is still denied. | |
| -- `rmfilter` | |
| - Removes the given pattern from the list of access violation filters. | |
| +See [Magic Commands](#magic_commands) under [Sandboxing](#sandboxing). | |
| ### exheres-0/build\_functions.bash | |
| @@ -1558,11 +1546,102 @@ If a `bind` call is successful the address is automatically added to the `connec | |
| ### Magic Commands | |
| The behaviour of sandboxing may be altered by using magic commands. These commands provide a simple | |
| -way to interact with `sydbox`. Check `sydbox` manual page for the list of magic commands. The | |
| -exheres command `sydboxcmd` is a simple wrapper around the magic `stat`. So instead of `stat`'ing | |
| -e.g. `/dev/sydbox/off` you may use `sydboxcmd off`. | |
| - | |
| -For a list of magic commands consult the `sydbox(1)` man page. | |
| +way to interact with `sydbox`. Check `sydbox` manual page for the list of magic commands. Previously | |
| +we used a simple wrapper function called `sydboxcmd` around sydbox' magic `stat()` function. This | |
| +function is now deprecated in favour of the higher level wrapper `esandbox`. | |
| + | |
| +Here's a list of `esandbox` commands: | |
| + | |
| +#### Querying sandbox status | |
| +- `esandbox check`: Check whether the program is being executed under sandboxing. | |
| +- `esandbox enabled` or `esandbox enabled_path`: Check whether path sandboxing is enabled. | |
| +- `esandbox enabled_exec`: Check whether exec sandboxing is enabled. | |
| + | |
| +#### Turning sandboxing on/off | |
| +- `esandbox enable` or `esandbox enable_path`: Enable path sandboxing. | |
| +- `esandbox disable` or `esandbox disable_path`: Disable path sandboxing. | |
| +- `esandbox enable_exec`: Enable exec sandboxing. | |
| +- `esandbox disable_exec`: Disable exec sandboxing. | |
| +- `esandbox enable_net`: Enable network sandboxing. | |
| +- `esandbox disable_net`: Disable network sandboxing. | |
| + | |
| +#### Whitelisting | |
| +- `esandbox allow` or `esandbox allow_path`: Whitelist a path for path sandboxing. | |
| +Takes one extra argument which must be an __absolute__ path. | |
| +- `esandbox disallow` or `esandbox disallow_path`: Removes a path from the path sandboxing whitelist. | |
| +Takes one extra argument which must be an __absolute__ path. | |
| +- `esandbox allow_exec`: Whitelist a path for `execve()` sandboxing. | |
| +Takes one extra argument which must be an __absolute__ path. | |
| +- `esandbox disallow_exec`: Removes a path from the `execve()` sandboxing whitelist. | |
| +Takes one extra argument which must be an __absolute__ path. | |
| +- `esandbox allow_net`: Whitelist a network address for `bind()` whitelist - or for `connect()` | |
| +whitelist if _--connect_ option is given. | |
| +- `esandbox disallow_net`: Removes a network address from the `bind()` whitelist - or from `connect()` | |
| +whitelist if _--connect_ option is given. | |
| + | |
| +#### Filtering | |
| +- `esandbox addfilter` or `esandbox addfilter_path`: Add a pattern as a path sandboxing filter. | |
| +Takes one extra argument which is a `fnmatch()` pattern. | |
| +- `esandbox rmfilter` or `esandbox rmfilter_path`: Removes a pattern from the path sandboxing filter list. | |
| +Takes one extra argument which is a `fnmatch()` pattern. | |
| +- `esandbox addfilter_exec`: Add a pattern as a `execve()` sandboxing filter. | |
| +Takes one extra argument which is a `fnmatch()` pattern. | |
| +- `esandbox rmfilter_exec`: Removes a pattern from the `execve()` sandboxing filter list. | |
| +Takes one extra argument which is a `fnmatch()` pattern. | |
| +- `esandbox addfilter_net`: Add a network address as a network sandboxing filter. | |
| +Takes one extra argument which is a network address. | |
| +- `esandbox rmfilter_net`: Removes a pattern from the network sandboxing filter list. | |
| +Takes one extra argument which is a network address. | |
| + | |
| +#### Miscallenous commands | |
| +- `esandbox lock`: Lock magic commands. After calling this none of the `esandbox` commands will | |
| + work. You don't need to call this, see `exec_lock`. | |
| +- `esandbox exec_lock`: Lock magic commands upon `execve()`. This is the default for phases other | |
| + than `metadata` thus you don't need to call this command from exhereses. | |
| +- `esandbox 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. | |
| +- `esandbox wait_all`: Wait for all processes before exiting. This is the default. | |
| +- `esandbox nohack_toolong`: Sydbox tries hard to workaround problems regarding too long paths. | |
| + However, this isn't desired in some cases where these hacks increase the execution time | |
| + considerably. This command disables sydbox' hacks for too long paths. | |
| +- `esandbox hack_toolong`: This enables sydbox' hacks for too long paths. | |
| + | |
| +#### 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 | |
| + | |
| +##### Deprecated Commands | |
| +- `sydboxcmd`: Use the appropriate `esandbox` command instead | |
| +- `sydboxcheck`: Use `esandbox check` instead | |
| +- `addwrite`: Use `esandbox allow` instead | |
| +- `rmwrite`: Use `esandbox disallow` instead | |
| +- `addfilter`: Use `esandbox addfilter` instead | |
| +- `rmfilter`: Use `esandbox rmfilter` instead | |
| ## Formatting | |
| @@ -1671,6 +1750,8 @@ Copyright 2008, 2009 Ciaran McCreesh | |
| Copyright 2008, 2009, 2010, 2011 Bo Ørsted Andresen | |
| +Copyright 2011 Ali Polatel | |
| + | |
| This work is licensed under the Creative Commons Attribution Share Alike 3.0 License. To view a copy | |
| of this license, visit http://creativecommons.org/licenses/by-sa/3.0/; or, (b) send a letter to | |
| Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA. | |
| -- | |
| 1.7.5.4 | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment