17 Apr, 2025

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 https://google.com

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