The current Sandbox API aims to provide a reduced subset of Bubblewrap functionality to multiple platforms, but the precise extent of this API and the definition of what constitutes an essential feature is not decided at the moment.
Core features
Ideally, the Bastille library should continue to model itself around Bubblewrap in terms of feature set while ensuring that this functionality is available on all platforms with as few platform-specific caveats as possible. At the time of writing, some features considered "essential" include:
It must be able to create an isolated chroot/pivot_root filesystem and arbitrarily mount external files and directories into it as read-only or read-write.
It must be able to create arbitrary directory structures and soft links within the isolated filesystem.
It must be able to disallow network access, only whitelisting the lo interface when networking is off.
It must be able to granularly disallow Unix, IPv4, and/or IPv6 socket access. This is confirmed to be possible on Linux with seccomp(2) (source) and macOS with sandbox_init(3).
It must be able to disallow access to device files, e.g. /dev/null.
It must be able to set or clear the environment variables of the sandboxed process.
It must be able to set the UID and GID of the sandboxed process.
It must be able to set the current working directory of the sandboxed process, defaulting to $HOME if it does not exist, or / if $HOME does not exist or is unset.
It must be able to set the maximum number of open file descriptors the sandboxed process may have using setrlimit(2) and RLIMIT_NOFILE, or leave it at the defaults if unspecified.
As mentioned previously, this core feature list is not set in stone and may change over time.
Platform specific features
It is an open question whether we should expose platform-specific functionality in addition to the core platform-agnostic feature set described above, and if so, how to do so in an ergonomic way. Most likely, these extra features would be exposed as additional builder methods on Sandbox guarded by doc-cfg (works on stable Rust).
I believe that Bastille should take a similar approach to the Rust standard library, which is roughly the following:
If a feature exists on all platforms in its full form, it is considered fully agnostic. It is exposed as a Sandbox method on all platforms.
If a feature exists on all platforms but with limitations or different run-time guarantees, it is considered mostly agnostic. It is exposed as a Sandbox method on all platforms, with any platform-specific caveats recorded in the API documentation.
If a feature exists only on some platforms with no reasonable equivalent, it is considered platform specific. It is exposed via a separate impl block or SandboxExt trait guarded by a #[cfg(platform)] attribute.
We should strive to maximize feature sets 1 and 2 as much as possible and only expose feature set 3 if the feature in question is supported by all first-class platforms (see PLATFORM.md). For example, mounting tmpfs filesystems is supported on all platforms except macOS, which is considered a second-class platform, so it is a good candidate for exposing as a platform-specific feature in the future. Other examples include user, PID, and network namespace separation, both of which are also supported on all platforms except for macOS (further investigation is still needed to verify this is the case).
The current
Sandbox
API aims to provide a reduced subset of Bubblewrap functionality to multiple platforms, but the precise extent of this API and the definition of what constitutes an essential feature is not decided at the moment.Core features
Ideally, the Bastille library should continue to model itself around Bubblewrap in terms of feature set while ensuring that this functionality is available on all platforms with as few platform-specific caveats as possible. At the time of writing, some features considered "essential" include:
chroot
/pivot_root
filesystem and arbitrarily mount external files and directories into it as read-only or read-write.lo
interface when networking is off.seccomp(2)
(source) and macOS withsandbox_init(3)
./dev/null
.$HOME
if it does not exist, or/
if$HOME
does not exist or is unset.setrlimit(2)
andRLIMIT_NOFILE
, or leave it at the defaults if unspecified.As mentioned previously, this core feature list is not set in stone and may change over time.
Platform specific features
It is an open question whether we should expose platform-specific functionality in addition to the core platform-agnostic feature set described above, and if so, how to do so in an ergonomic way. Most likely, these extra features would be exposed as additional builder methods on
Sandbox
guarded bydoc-cfg
(works on stable Rust).I believe that Bastille should take a similar approach to the Rust standard library, which is roughly the following:
Sandbox
method on all platforms.Sandbox
method on all platforms, with any platform-specific caveats recorded in the API documentation.impl
block orSandboxExt
trait guarded by a#[cfg(platform)]
attribute.We should strive to maximize feature sets 1 and 2 as much as possible and only expose feature set 3 if the feature in question is supported by all first-class platforms (see
PLATFORM.md
). For example, mountingtmpfs
filesystems is supported on all platforms except macOS, which is considered a second-class platform, so it is a good candidate for exposing as a platform-specific feature in the future. Other examples include user, PID, and network namespace separation, both of which are also supported on all platforms except for macOS (further investigation is still needed to verify this is the case).