Seatbelt Sandboxer

Generate minimal macOS Seatbelt sandbox configurations

Author: Spencer Michaels (Trail of Bits)

Overview

Generate a macOS Seatbelt configuration that sandboxes the target with the minimum set of permissions necessary for it to operate normally. Uses an iterative profiling approach to create allowlist-based sandbox profiles for applications.

When to Use

Use this plugin when you need a targeted way to isolate a process on macOS without using containers. This can be helpful for:

Supply Chain Risk

Applications at high risk of supply chain attacks (package managers, bundlers)

Untrusted Code Execution

Trusted applications that execute potentially-untrusted third-party code (Javascript bundlers, build tools)

Blast Radius Reduction

Reducing the impact if an application is exploited

Defense in Depth

Adding isolation layers to sensitive processes

This plugin should NOT be used to run an untrusted process, since it requires running the target process to profile it in order to determine what permissions are actually needed.

How It Works

1. Profile the Target Application

   Identify the actual set of permissions required for the application to run normally.

2. Generate a Minimal Seatbelt Profile

   Start from a default-deny profile.

3. Iteratively Expand Permissions

   Test the application empirically to identify what calls fail with the minimal profile, and add the needed permissions until the application runs normally.

4. Create Helper Scripts if Needed

   If the application has multiple subcommands that perform highly different functions (such as “serve” and “build” tasks), create separate Seatbelt configurations for each, and create a helper script to switch configurations based on how the target application is invoked.

Profiling Methodology

Step 1: Identify Application Requirements

Determine what the application needs across these resource categories:

File Operations

Operation	Seatbelt Rule	Use Cases
Read	file-read-data, file-read-metadata	Reading source files, configs, libraries
Write	file-write-data, file-write-create	Output files, caches, temp files
Delete	file-write-unlink	Cleanup operations
Execute	file-map-executable	Loading dylibs

Network

Operation	Seatbelt Rule	Use Cases
Bind	network-bind	Server applications
Inbound	network-inbound	Accept connections
Outbound	network-outbound	API calls, package downloads

Process & IPC

Operation	Seatbelt Rule	Use Cases
Fork	process-fork	Spawning child processes
Exec	process-exec*	Running binaries
Mach IPC	mach-lookup	System services, XPC
POSIX IPC	ipc-posix-shm*	Shared memory

System

Operation	Seatbelt Rule	Use Cases
Sysctl	sysctl-read	Reading system info (CPU, memory)
IOKit	iokit-open	Hardware access, device drivers
Dynamic Code	dynamic-code-generation	JIT compilation
Signals	signal	Signal handling

Step 2: Start with Minimal Profile

Begin with deny-all and essential process operations:

(version 1)
(deny default)

;; Essential for any process
(allow process-exec*)
(allow process-fork)
(allow sysctl-read)

;; Metadata access (stat, readdir) - doesn't expose file contents
(allow file-read-metadata)

Step 3: Add File Read Access (Allowlist)

Why file-read-data instead of file-read*?

• file-read* allows ALL file read operations from any path
• file-read-data only allows reading file contents from listed paths
• Combined with file-read-metadata (allowed broadly), this gives:
  • ✅ Can stat/readdir anywhere (needed for path resolution)
  • ❌ Cannot read contents of files outside allowlist

(allow file-read-data
    ;; System paths (required for most runtimes)
    (subpath "/usr")
    (subpath "/bin")
    (subpath "/sbin")
    (subpath "/System")
    (subpath "/Library")
    (subpath "/opt")                    ;; Homebrew
    (subpath "/private/var")
    (subpath "/private/etc")
    (subpath "/private/tmp")
    (subpath "/dev")

    ;; Root symlinks for path resolution
    (literal "/")
    (literal "/var")
    (literal "/etc")
    (literal "/tmp")
    (literal "/private")

    ;; Application-specific config (customize as needed)
    (regex (string-append "^" (regex-quote (param "HOME")) "/\\.myapp(/.*)?$"))

    ;; Working directory
    (subpath (param "WORKING_DIR")))

Step 4: Configure Network

No Network (Most Restrictive)

Use for build tools that don’t need network access:

(deny network*)

Localhost Only

Use for dev servers and local services:

;; Bind to local ports
(allow network-bind (local tcp "*:*"))
;; Accept inbound connections
(allow network-inbound (local tcp "*:*"))
;; Outbound to localhost + DNS only
(allow network-outbound
    (literal "/private/var/run/mDNSResponder")  ;; DNS resolution
    (remote ip "localhost:*"))                   ;; localhost only

Full Network (Least Restrictive)

Avoid if possible:

(allow network*)

Step 5: Test Iteratively

1. Test Basic Execution

   sandbox-exec -f profile.sb -D WORKING_DIR=/path -D HOME=$HOME /bin/echo "test"
   
2. Test the Actual Application

   sandbox-exec -f profile.sb -D WORKING_DIR=/path -D HOME=$HOME \
     /path/to/application --args
   
3. Test Security Restrictions

   sandbox-exec -f profile.sb -D WORKING_DIR=/tmp -D HOME=$HOME \
     cat ~/.ssh/id_rsa
   # Expected: Operation not permitted
   
4. Debug Failures

   Common failure modes:

   Symptom	Cause	Fix
   Exit code 134 (SIGABRT)	Sandbox violation	Check which operation is blocked
   Exit code 65 + syntax error	Invalid profile syntax	Check Seatbelt syntax
   ENOENT for existing files	Missing file-read-metadata	Add (allow file-read-metadata)
   Process hangs	Missing IPC permissions	Add (allow mach-lookup) if needed

5. Iterate Until Working

   Repeat this process iteratively until you have generated a minimally-permissioned Seatbelt file and have confirmed empirically that the application works normally.

If the program requires external input to function fully (such as a Javascript bundler that needs an application to bundle), find sample inputs from well-known, ideally official sources. For instance, Rspack example projects.

Seatbelt Syntax Reference

Path Filters

(subpath "/path")           ;; /path and all descendants
(literal "/path/file")      ;; Exact path only
(regex "^/path/.*\\.js$")   ;; Regex match

Parameter Substitution

(param "WORKING_DIR")                                    ;; Direct use
(subpath (param "WORKING_DIR"))                          ;; In subpath
(string-append (param "HOME") "/.config")                ;; Concatenation
(regex-quote (param "HOME"))                             ;; Escape for regex

File Operations

(allow file-read-data ...)          ;; Read file contents
(allow file-read-metadata)          ;; stat, lstat, readdir (no contents)
(allow file-read-xattr ...)         ;; Read extended attributes
(allow file-test-existence ...)     ;; Check if file exists
(allow file-map-executable ...)     ;; mmap executable (dylibs)
(allow file-write-data ...)         ;; Write to existing files
(allow file-write-create ...)       ;; Create new files
(allow file-write-unlink ...)       ;; Delete files
(allow file-write* ...)             ;; All write operations
(allow file-read* ...)              ;; All read operations (use sparingly)

Network Operations

(allow network-bind (local tcp "*:*"))              ;; Bind to any local TCP port
(allow network-bind (local tcp "*:8080"))           ;; Bind to specific port
(allow network-inbound (local tcp "*:*"))           ;; Accept TCP connections
(allow network-outbound (remote ip "localhost:*"))  ;; Outbound to localhost only
(allow network-outbound (remote tcp))               ;; Outbound TCP to any host
(allow network-outbound
    (literal "/private/var/run/mDNSResponder"))     ;; DNS via Unix socket
(allow network*)                                    ;; All network (use sparingly)
(deny network*)                                     ;; Block all network

Process Operations

(allow process-exec* ...)           ;; Execute binaries
(allow process-fork)                ;; Fork child processes
(allow process-info-pidinfo)        ;; Query process info
(allow signal)                      ;; Send/receive signals

Example: Generic CLI Application

(version 1)
(deny default)

;; Process
(allow process-exec*)
(allow process-fork)
(allow sysctl-read)

;; File metadata (path resolution)
(allow file-read-metadata)

;; File reads (allowlist)
(allow file-read-data
    (literal "/") (literal "/var") (literal "/etc") (literal "/tmp") (literal "/private")
    (subpath "/usr") (subpath "/bin") (subpath "/sbin") (subpath "/opt")
    (subpath "/System") (subpath "/Library") (subpath "/dev")
    (subpath "/private/var") (subpath "/private/etc") (subpath "/private/tmp")
    (subpath (param "WORKING_DIR")))

;; File writes (restricted)
(allow file-write*
    (subpath (param "WORKING_DIR"))
    (subpath "/private/tmp") (subpath "/tmp") (subpath "/private/var/folders")
    (literal "/dev/null") (literal "/dev/tty"))

;; Network disabled
(deny network*)

Usage:

sandbox-exec -f profile.sb \
  -D WORKING_DIR=/path/to/project \
  -D HOME=$HOME \
  /path/to/application

Known Limitations

1. Deprecated but functional: Apple deprecated sandbox-exec but it works through macOS 14+
2. Temp directory access often required: Many applications need /tmp and /var/folders

Installation

/plugin install trailofbits/skills/plugins/seatbelt-sandboxer

When NOT to Use

• Linux containers (use seccomp-bpf, AppArmor, or namespaces instead)
• Windows applications
• Applications that legitimately need broad system access
• Quick one-off scripts where sandboxing overhead isn’t justified

References

• Apple Sandbox Guide (reverse-engineered)
• sandbox-exec man page