Getting Started With Sandboxed API

Build Dependencies

To build and run code with SAPI, the following dependencies must be installed on the system:

  • Linux kernel with support for UTS, IPC, user, PID and network namespaces
  • Linux userspace API headers
  • To compile your code: GCC 6 (version 7 or higher preferred) or Clang 7 (or higher)
  • For auto-generating header files: Clang Python Bindings
  • Bazel version 0.28.0 or CMake version 3.10 or higher.
  • CMake only: A version of the libcap library headers and a build tool such as Ninja (recommended) or GNU Make.
  • Python 3.5 or later

Sandboxed API supports building sandboxed libraries using both Bazel and CMake, depending on what your project uses.

Using Bazel

Bazel is the recommended build system and easiest to integrate with.

If you need a specific compiler/linker/etc., please refer to the Bazel documentation for information on how to change the default compiler toolchain.

Debian 10 "Buster"

To install build dependencies:

echo "deb http://storage.googleapis.com/bazel-apt stable jdk1.8" | \
sudo tee /etc/apt/sources.list.d/bazel.list
wget -qO - https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install -qy build-essential linux-libc-dev bazel python3 \
  python3-pip libclang-7-dev
pip3 install clang

Gentoo

Kernel options required:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

To install build dependencies:

emerge dev-util/bazel dev-python/typing dev-python/clang-python

Using CMake

CMake is a popular open source meta build system that generates project files for build tools such as Ninja or Make.

Debian 10 "Buster"

To install build dependencies:

sudo apt-get install -qy build-essential linux-libc-dev cmake ninja-build \
  python3 python3-pip libclang-7-dev libcap-dev
pip3 install clang

Gentoo

Kernel options required:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

Build dependencies:

emerge sys-kernel/linux-headers dev-util/cmake dev-util/ninja \
  dev-python/clang-python

Examples

Under Examples you can find a few libraries, previously prepared by the SAPI team.

Development Process

You will have to prepare two parts of your a sandbox library project. The sandboxed library part (SAPI library), and the host code which will make use of functionality exposed by your sandboxed library.

SAPI Library

The SAPI library is a sandboxed process, which exposes required functionality to the host code.

In order to create it, you'll need your C/C++ library, for example another open source project on GitHub. You will also have to create some supporting code (part of it will be automatically generated). This code will describe which functionality exactly you would like to contain (which library functions), and the sandbox policies you would like your library to run under.

All those steps are described in details under Library.

Host Code

The host code is making use of functions exported by your SAPI Library.

It makes calls to sandboxed functions, receives results, and can access memory of a SAPI library in order to make copies of remote variables and memory blocks (arrays, structures, protocol buffers, etc.). Those memory blocks can then be accessed by the local process.

The host code can also copy contents of local memory to the remote process if needed.

Read about writing host code here.