sandboxed-api/sandboxed_api/sandbox2/docs/howitworks.md

How it works

Overview

The sandbox technology is organized around 2 processes:

• An executor sets up and runs the monitor:

  • Also known as parent, supervisor or monitor
  • By itself is not sandboxed
  • Is regular C++ code using the Sandbox2 API

• The sandboxee, a child program running in the sandboxed environment:

  • Also known as child or sandboxed process
  • Receives its policy from the executor and applies it
  • Can come in different shapes:
    • Another binary, like in the crc4 and static examples
    • A third party binary for which you do not have the source

Purpose/goal:

• Restrict the sandboxee to a set of allowed syscalls and their arguments
• The tighter the policy, the better

Example:

A really tight policy could deny all except reads and writes on standard input and output file descriptors. Inside this sandbox, a program could take input, process it, and send the output back.

• The processing is not allowed to make any other syscall, or else it is killed for policy violation.
• If the processing is compromised (code execution by a malicious user), it cannot do anything bad other than producing bad output (that the executor and others still need to handle correctly).

Sandbox Policies

The sandbox relies on seccomp-bpf provided by the Linux kernel. seccomp is a Linux kernel facility for sandboxing and BPF is a way to write syscall filters (the very same used for network filters). Read more about seccomp-bpf on Wikipedia.

In practice, you will generate your policy using our PolicyBuilder class. If you need more complex rules, you can specify raw BPF macros, like in the crc4 example.

Filesystem accesses are restricted with the help of Linux user namespaces. User namespaces allow to drop the sandboxee into a custom chroot environment without requiring root privileges.

Getting Started

Read our Getting started page to set up your first sandbox.