What is sandbox-exec?

sandbox-exec is a built-in macOS command-line utility that enables users to execute applications within a sandboxed environment. In essence, it creates a secure, isolated space where applications can run with limited access to system resources – only accessing what you explicitly permit.

The concept behind sandboxing is fundamental to modern security: by restricting what an application can access, you minimize the potential damage from malicious code or unintended behavior. Think of it as putting an application in a secure room where it can only interact with specific objects you've placed there.

Benefits of Application Sandboxing

Before diving into usage, let's understand why sandboxing matters:

1. Protection from malicious code: If you're testing an unfamiliar application or script, sandboxing can prevent it from accessing sensitive files or sending data across the network.

2. Damage limitation: Even trusted applications can have vulnerabilities. Sandboxing limits the potential impact if an application is compromised.

3. Privacy control: You can explicitly deny applications access to personal directories like Documents, Photos, or Contacts.

4. Testing environment: Developers can test how applications function with limited permissions before implementing formal App Sandbox entitlements.

5. Resource restriction: Beyond security, sandboxing can limit an application's resource consumption or network access.

Getting Started with sandbox-exec

Using sandbox-exec requires creating a sandbox profile (configuration file) that defines the rules for your secure environment. The basic syntax is:

sandbox-exec -f profile.sb command_to_run

Where profile.sb contains the rules defining what the sandboxed application can and cannot do, and command_to_run is the application you want to run within those constraints.

Understanding Sandbox Profiles

Sandbox profiles use a Scheme-like syntax (a LISP dialect) with parentheses grouping expressions. The basic structure includes:

• A version declaration: (version 1)
• Default policy: (deny default) or (allow default)
• Specific rules allowing or denying operations

Rules can target specific resources using:

• Literal paths: (literal "/path/to/file")
• Regular expressions: (regex "^/System")
• Glob patterns: (subpath "/Library")

See Appendix for more complete list of available rules

Two Fundamental Approaches to Sandboxing

There are two primary philosophies when creating sandbox profiles:

1. Deny by Default (Most Secure)

This approach starts by denying everything and explicitly allowing only required operations:

(version 1)
(deny default)
(allow file-read-data (regex "^/usr/lib"))
(allow process-exec (literal "/usr/bin/python3"))

This is the most secure approach, ideal for running untrusted code, but requires careful configuration to make applications functional.

2. Allow by Default (More Permissive)

Alternatively, you can allow everything except specific operations:

(version 1)
(allow default)
(deny network*)
(deny file-write* (regex "^/Users"))

This approach is easier to implement but less secure, as you must anticipate every potential risky operation.

Practical Examples of sandbox-exec in Action

Let's explore some real-world examples to demonstrate the power of custom sandboxing.

Example: Sandboxed Terminal Session

Create a sandboxed terminal session that can't access the network:

# Create terminal-sandbox.sb:
(version 1)
(allow default)
(deny network*)
(deny file-read-data (regex "^/Users/[^/]+/(Documents|Pictures|Desktop)"))

# Run a sandboxed terminal
sandbox-exec -f terminal-sandbox.sb zsh

This creates a terminal session that functions normally but cannot access the network or read from your personal directories.

Example: Using Pre-built System Profiles

macOS includes several pre-built sandbox profiles in /System/Library/Sandbox/Profiles:

# Run a command with the system's no-network profile
sandbox-exec -f /System/Library/Sandbox/Profiles/weatherd.sb command

These system profiles provide configurations for common restriction scenarios and applications. Some of them have quite good comments so you can use it as basis for your future profiles.

Debugging Sandbox Issues

When applications fail in a sandbox, determining the cause can be challenging. Here are effective debugging techniques:

Using the Console App

1. Open Console.app (Applications → Utilities → Console)
2. Search for "sandbox" and your application name
3. Look for lines containing "deny" to identify blocked operations

Using Terminal for Real-time Logs

For real-time monitoring of sandbox violations:

log stream --style compact --predicate 'sender=="Sandbox"'

To filter for a specific application:

log stream --style compact --predicate 'sender=="Sandbox" and eventMessage contains "python"'

These logs show exactly which operations are being denied, helping you refine your sandbox profile.

Advanced Sandbox Techniques

Creating a Sandbox Alias

For frequent sandboxing, add an alias to your shell configuration:

# Add to ~/.zshrc or ~/.bash_profile
alias sandbox-no-network='sandbox-exec -p "(version 1)(allow default)(deny network*)"'

# Then use it as:
sandbox-no-network curl -v <a href="https://google.com" rel="nofollow">https://google.com</a>

but when I did the same for UI applications it didn't work for some reason (I can still open Google.com):

sandbox-no-network /Applications/Firefox.app/Contents/MacOS/firefox

Importing Existing Profiles

You can import and extend existing profiles:

(version 1)
(import "/System/Library/Sandbox/Profiles/bsd.sb")
(deny network*)  # Add additional restrictions

Limitations and Considerations

Despite its power, sandbox-exec has some limitations to consider:

1. Deprecation status: While functional, Apple discourages its direct use in favor of App Sandbox for developers.

2. Complex applications: Modern applications often have complex requirements that make comprehensive sandboxing challenging without extensive testing.

3. Trial and error: Creating effective sandbox profiles often requires iterative testing to identify all necessary permissions.

4. No GUI: Unlike App Sandbox in Xcode, sandbox-exec has no graphical interface for configuration.

5. System updates: Major macOS updates might change how sandbox-exec works or what rules are effective.

While Apple has moved toward more user-friendly security models, sandbox-exec remains a powerful tool for those willing to invest time in learning its intricacies. It offers a level of control and customization that GUI-based solutions simply cannot match.

For security-conscious users, developers testing applications, or anyone working with potentially untrusted code, sandbox-exec provides a native macOS solution for creating finely-tuned security environments. Though it requires knowledge of all it's possibility, despite lack of documentation, the security benefits make it well worth the effort.

The most powerful aspect of sandbox-exec is its flexibility – you can create custom security profiles tailored to specific applications and use cases, going far beyond the one-size-fits-all approach of most security tools.

What's Next

If you're interested in learning more about macOS security tools and techniques, check out Apple's official documentation on App Sandbox or explore the pre-built sandbox profiles in /System/Library/Sandbox/Profiles to see how Apple implements sandboxing for system services

Window interactions

When ⌘↹-ing between apps, mouse over an app and release ⌘ to switch to that app without having to spam ↹ or ⇧↹.

Relatedly, while ⌘↹-ing, hit Q to quit or H to hide an app.

⌥⌘-click an app in the Dock to switch to that app and hide all other apps at the same time. This is great when screen sharing.

Hold ⌘ to interact with background windows without bringing them into focus.

Text selection

When using the cursor to select text, double-click to select a word. Triple-click to select a paragraph.

Relatedly, double-click and drag to select word-by-word. Triple-click and drag to select paragraph-by-paragraph.

Screenshots

When taking screenshots, hold ⌃ to copy the image instead saving it to your desktop.

Relatedly, you can make screenshots save somewhere else.

When using ⇧⌘4 to take screenshots, press space to capture by window. In this mode, you can also:

• hold ⌥ to take the window screenshot sans-shadow; and/or
• hold ⌘ to capture child views within a window (such as New/Open/Save dialogues, alert windows, et al).

Relatedly, you can make shadowless default for window screenshots. Hold ⌥ to add the shadow.

⌘-drag to reorder icons in the menu bar.

Click and hold the Spotlight button in the menu bar to reset its location on screen.

Any self-respecting Mac app opens the Help menu when you press ⌘?. (Safari, for some god-forsaken reason opens the Tips app instead. 🤬)

Function keys

Hold ⇧⌥ to adjust display brightness, volume or keyboard brightness in quarter-increments. This is useful when the lowest click is still too bright or loud.

A quick way to access your Displays settings is to ⌥-press either brightness up or brightness down.

• Same goes for Sound settings: ⌥-press mute or volume up/down.
• Again with Keyboard settings: ⌥keyboard brightness up/down.

(Works with Touch Bar too! ⌥-tap the corresponding button in the Control Strip.)

Finder

When using drag & drop to copy/move a file, hold ⌘ to force Finder to move the file, or hold ⌥ to force Finder to copy the file. (Yes, you can ⌥-drag to duplicate a file within a single folder.)

In Finder, hold ⌥ to Get Info on all selected items in one Inspector window, rather than in a barrage of individual Info windows. This also works with ⌥⌘I (instead of ⌘I).

In any Save sheet, drag and drop a folder onto the sheet to navigate there in the Save sheet. Drag and drop a file to navigate there and prepopulate the Save As field with its filename.

You may already know about the Go to Folder… menu item (⇧⌘G) in a normal Finder window. This is even quicker to invoke from an New/Open/Save dialogue: just hit /. (The usual shortcut still works.)

Tabs

Middle-click a tab to close it.

Hold ⌥ when closing a tab to close all other tabs instead.

Custom shortcuts

For any menu item (that is, anything in the menu bar), you can set a custom keyboard shortcut in System Settings → Keyboard → Keyboard Shortcuts… → App Shortcuts. Take care to spell the name of the command exactly—including special characters.

Column views

With any standard column view (such as in Finder), hold ⌥ to resize all columns equally.

Right-click with keyboard

⌃⏎ to right-click whatever is currently focused. (Though, strictly speaking, there’s no clicking involved here.)

Custom icons

Change the icon of any Finder item: Copy any image or .icns file, Get Info on any item in Finder, click to select the icon in the top left, and paste! Or simply drag & drop an image or .icns onto the icon.

Relatedly, you can even copy the icon from one file’s Info panel to paste into another.

Also relatedly, a bunch of the system icons live in /System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/.

Spelling dictionary

When macOS says you’ve spelled something wrong, and you right-click then choose Learn Spelling, it just adds the word to the ~/Library/Spelling/LocalDictionary file. If you’ve added a word to your dictionary that you no longer want, just open up the file and delete the word.

Relatedly, ⇧⌘G in any Finder window and paste a pathname to go straight to that file or folder. (See the Go to folder… tip.)

Dock

⌘-click items in the Dock to reveal them in Finder.

Ditto in Spotlight, where ⌘⏎ also works—and is probably more useful.

Don’t want to accidentally add/remove apps from your Dock? Lock its contents by running:

defaults write com.apple.dock contents-immutable -bool true && killall Dock

Set it back to normal with:

defaults delete com.apple.dock contents-immutable && killall Dock

Terminal

Drag and drop a folder onto the Terminal icon to open a terminal directly to that directory.

Relatedly, ⌘-drag a folder onto a Terminal window to cd there without typing anything.

Network quality

Test your network capacity without any third party things (like speedtest.net or fast.com) by running networkQuality from the command line, optionally using the -v flag for verbose output very nerdy details.

> networkQuality

==== SUMMARY ====
Uplink capacity: 34.685 Mbps
Downlink capacity: 225.857 Mbps
Responsiveness: Low (485.706 milliseconds | 123 RPM)
Idle Latency: 38.958 milliseconds | 1540 RPM