Sandbox2 Explained  |  Code Sandboxing  |  Google for Developers (2025)

• Home
• Products
• Code Sandboxing
• Sandbox2

The Sandbox2 design builds on well-known and established technologies, a policyframework, and two processes: the Sandbox Executor and the Sandboxee.

Technologies Involved

The following sections cover the technologies that build the foundation layerfor Sandbox2.

Linux Namespaces

The Linux namespaces are an attempt to provide operating-system-levelvirtualization. While multiple userspaces run seemingly independently of eachother, they share a single kernel instance. Sandbox2 uses the following kinds ofnamespaces:

• IPC
• Network (unless explicitly disabled by callingPolicyBuilder::AllowUnrestrictedNetworking())
• Mount (using a custom view of the filesystem tree)
• PID
• User
• UTS

Read more about Linux namespaces onWikipedia or on the relatedman page.

IPC

Sandbox2 allows exchanging arbitrary data between the Sandbox Executor and theuntrusted Sandboxee. It supports Type-Length-Value (TLV) messages, passing filedescriptors, and credential exchange through tokens and handles.

Seccomp-BPF

Sandbox2 relies onseccomp-bpf, which is anextension to Secure Computing Mode (seccomp) that allows using Berkeley PacketFilter (BPF) rules to filter syscalls.

seccomp is a Linux kernel facility that restricts a process's system calls toonly allow exit, sigreturn, read, and write. If a process attempts toexecute another syscall, it will be terminated. The seccomp-bpf extension allowsmore flexibility than seccomp. Instead of allowing a fixed set of syscalls,seccomp-bpf runs a BPF program on the syscall data and depending on theprogram's return value, it can execute the syscall, skip the syscall and returna dummy value, terminate the process, generate a signal, or notify the tracer.

Ptrace

The ptrace (process trace) syscall provides functionality that allows the tracerprocess to observe and control the execution of the tracee process. The tracerprocess has full control over the tracee once attached. Read more about ptraceon Wikipedia or on the related man page.

Sandbox Policy

The SandboxPolicyis the most crucial part of a sandbox, as it specifies the actions which theSandboxee can and cannot execute. There are 2 parts to a sandbox policy:

• Syscall policy
• Namespace setup

Default Syscall Policy

The default policy blocks syscalls that are always dangerous and takesprecedence over the user-supplied extended policy.

Extended Syscall Policy

The extended syscall policy can be created using ourPolicyBuilderclass. This class defines a number of convenience rules (e.g.AllowStaticStartup, AllowDynamicStartup, AllowOpen) which can be used toimprove the readability of your policy.

If you want to further restrict syscalls or require more complex rules, you canspecify raw BPF macros with AddPolicyOnSyscall and AddPolicyOnSyscalls. Thecrc4 example makes use of thismechanism to restrict arguments for the read, write, and close syscalls.

In general, the tighter the Sandbox Policy, the better because the exploitationof any vulnerability present within the code will be confined by the policy. Ifyou're able to specify exactly which syscalls and arguments are required for thenormal operation of the program, then any attacker exploiting a code executionvulnerability is also restricted to the same limits.

A really tight Sandbox Policy could deny all syscalls except reads and writes onstandard input and output file descriptors. Inside this sandbox, a program couldtake input, process it, and return the output. However, if the process wouldattempt to make any other syscall, it would be terminated due to a policyviolation. Hence, if the process is compromised (code execution by a malicioususer), it cannot do anything more nefarious than producing bad output (that theexecutor and others still need to handle correctly).

Namespace Setup

The PolicyBuilder object is also used to set up a Sandboxee's individual view ofthe filesystem. Single files (AddFile / AddFileAt), whole directories(AddDirectory / AddDirectoryAt), as well as temporary storage (AddTmpfs)can be mapped into the Sandboxee's environment. Additionally,AddLibrariesForBinary can be used to automatically map all the librariesneeded by the specified dynamically linked executable.

Command-Line Flags

Any Sandbox2 policy can be disabled by specifying one of the followingcommand-line flags. These flags are intended for testing purposes (e.g. whilerefining the Extended Syscall Policy).

• --sandbox2_danger_danger_permit_all
• --sandbox2_danger_danger_permit_all_and_log

Sandbox Executor

The SandboxExecutoris a process that is not sandboxed itself. It's the ptrace tracer process thatattaches to the Sandboxee (ptrace tracee process). The Sandbox Executor alsosets up and runs aMonitorinstance which tracks the Sandboxee and provides status information.

Sandbox2 allows three execution modes: Stand-alone, Sandbox2 Forkserver, andCustom Forkserver. If you use a forkserver, the Sandboxee is created as a childprocess of the Sandbox Executor. These modes are explained in detail here.

Sandboxee

The Sandboxee is the process which runs in the restricted, sandboxed environmentwhich was defined by the Sandbox Policy. The Sandbox Executor sends the policyto the Sandboxee via IPC. The Sandboxee then applies the policy. Any violationof the policy will result in the termination of the process, unless configuredotherwise (see Sandbox Policy).