Sandboxing subprocesses in Python on macOS

The Sandboxing API

macOS ships with a sandboxing API documented in the sandbox(7) manpage.

NAME sandbox – overview of the sandbox facility

SYNOPSIS
     #include <sandbox.h>

DESCRIPTION
     The sandbox facility allows applications to voluntarily restrict their
     access to operating system resources.  This safety mechanism is intended
     to limit potential damage in the event that a vulnerability is exploited.
     It is not a replacement for other operating system access controls.

     New processes inherit the sandbox of their parent.  Restrictions are
     generally enforced upon acquisition of operating system resources only.
     For example, if file system writes are restricted, an application will not
     be able to open(2) a file for writing.  However, if the application
     already has a file descriptor opened for writing, it may use that file
     descriptor regardless of restrictions.

Apple provides no documentation about these APIs and considers them deprecated. Despite that these APIs are used by Chrome/Chromium ¹, Firefox ², Nix ³ and more to sandbox processes on macOS. It’s very unlikely Apple will remove these APIs without providing an equivalent replacement.

The sandbox profile is described in a Scheme dialect where a basic profile can deny and allow capabilities.

(version 1)
(deny default) ; Deny everything by default
(allow process-fork) ; Allow forking

More sophisticated profiles can be parameterized through the param function.

(version 1)
(deny default)

(define dir (param "DIR")) ; get the value of the DIR parameter
(allow file-write* file-read*
  (subpath dir)
)

There is no documentation available on this Scheme dialect⁴ but Apple ships many example profiles /System/Library/Sandbox/Profiles/ and profiles in this directory can be imported by other profiles. The bsd.sb shipped by Apple contains the basic minimum of rules that will allow for a process to start.

(version 1)
(deny default)
(import "bsd.sb")

The API to setup a sandbox with a parameterized profile is not available in any public header but is called sandbox_init_with_parameters. The signature is below and can be accessed dynamically through libSystem.dylib

int sandbox_init_with_parameters(const char *profile,
                                 uint64_t flags,
                                 const char *const parameters[],
                                 char **errorbuf);

Sandboxing subprocesses

The above API can be used to sandbox subprocesses in Python. This can be really useful if you are executing arbitrary commands and want to ensure the command doesn’t do something unexpected. A build system might want to isolate reads and writes to a specific directory or prevent network access for example.

subprocess.run accepts preexec_fn which according to the documentation:

If preexec_fn is set to a callable object, this object will be called in the child process just before the child is executed.

Using a preexec_fn to configure the sandbox before execution ensures that the subprocess runs with restricted permissions.With ctypes it’s possible to call sandbox_init_with_parameters with just the standard library in Python.

import ctypes
libsystem = ctypes.CDLL("libSystem.dylib")

def get_pre_exec(profile, params={}):
    def inner():
      if len(params) != 0:
            param_array = (ctypes.c_char_p * (len(params.keys()) * 2))()
            # Null-terminate the array
            param_array[len(params.keys()) * 2 - 1] = None

            for i, (key, value) in enumerate(params.items()):
                param_array[i * 2] = key.encode('utf-8')
                param_array[i * 2 + 1] = value.encode('utf-8')
      else:
            param_array = None

      # Prepare the error buffer
      errbuf = ctypes.POINTER(ctypes.c_char_p)()

      # int sandbox_init_with_parameters(const char *profile, uint64_t flags, const char *const parameters[], char **errorbuf);
      ret = libsystem.sandbox_init_with_parameters(
        ctypes.create_string_buffer(profile.encode('utf-8')),
        0,
        ctypes.cast(param_array, ctypes.POINTER(ctypes.c_char_p)),
        ctypes.byref(errbuf))

      if ret != 0:
         if errbuf:
                msg = ctypes.cast(errbuf, ctypes.c_char_p).value.decode('utf-8')
                libsystem.free(errbuf)
                raise Exception(f"Sandbox error: {msg}")
         else:
                raise Exception("Unknown error occurred.")

    return inner

The above function can then create a preexec_fn that is passed into subprocess.run

import subprocess
import tempfile

def main():
    profile = """
(version 1)
(deny default)
(import "bsd.sb")

(define targetDir (param "DIR"))

(allow process-exec file-read*
  (subpath "/bin")
  (subpath "/private")
  (subpath "/sbin")
  (subpath "/usr/bin")
  (subpath "/usr/sbin"))

(allow file-write* file-read*
  (subpath targetDir)
)
    """

    with tempfile.TemporaryDirectory() as tmpdir:
      pre_exec = get_pre_exec(profile, params={"DIR": str(tmpdir)})
      cmd = ['ls', '.']
      subprocess.run(preexec_fn=pre_exec, args=cmd, cwd=tmpdir, check=True)

if __name__ == "__main__":
    main()

The above prints out nothing since the contents of the temporary directory is empty. If the cmd is changed to do something that accesses a directory outside of the sandbox such as ['ls', '/Users'] then the subprocess fails with the following output.

ls: /Users: Operation not permitted

Conclusion

On macOS it’s possible to sandbox processes with the sandbox_init_with_parameters API. Even though Apple considers this API to be deprecated it’s a powerful tool for process isolation on macOS. Combined with the preexec_fn argument to subprocess.run Python programs can sandbox arbitrary subprocesses.