macOS Seatbelt

nono uses Apple’s Seatbelt sandbox framework on macOS to enforce capability restrictions at the kernel level.

What is Seatbelt?

Seatbelt is macOS’s mandatory access control (MAC) framework. It’s the same technology that sandboxes App Store applications and Safari. Seatbelt policies are enforced by the XNU kernel - they cannot be bypassed by userspace code.

Note: nono uses Apple’s private sandbox_init() API rather than the newer sandbox_apply_container(). While technically undocumented, this API has been stable for over a decade and is widely used by third-party tools. Apple’s public sandbox-exec command uses the same underlying mechanism.

How nono Uses Seatbelt

nono generates a Seatbelt profile (a Scheme-like DSL) based on your capability flags, then calls sandbox_init() to apply it before executing the target command.

// Simplified: what nono does internally
sandbox_init(profile_string, 0, &error);
exec(command, args);
// After sandbox_init(), restrictions are permanent for this process

Profile Structure

A nono-generated Seatbelt profile follows this structure:

(version 1)
(deny default)

; Process operations (narrowed - no blanket process*)
(allow process-exec*)                    ; Execute programs
(allow process-fork)                     ; Fork child processes
(allow process-info* (target self))      ; Self-inspection (dyld, code signing)
(deny process-info* (target others))     ; Block inspecting other processes

; System operations
(allow sysctl-read)
(allow mach*)
(allow ipc*)
(allow signal)
(allow system-socket)
(allow system-fsctl)
(allow system-info)

; Root directory access for path resolution
(allow file-read* (literal "/"))

; Executable mapping (required for dyld)
(allow file-map-executable)

; System paths from security-lists.toml
(allow file-read* (subpath "/System/Library"))
(allow file-read* (subpath "/usr/lib"))
(allow file-read* (subpath "/private/var/db/dyld"))
; ... more system paths

; User-granted paths
(allow file-read* (subpath "/Users/luke/project"))

; Sensitive paths: "Allow Discovery, Deny Content"
(allow file-read-metadata (subpath "/Users/luke/.ssh"))
(deny file-read-data (subpath "/Users/luke/.ssh"))
; ... more sensitive paths

; Network (default: allowed)
(allow network-outbound)
(allow network-inbound)
(allow network-bind)

Security Model: “Allow Discovery, Deny Content”

nono uses a nuanced approach to sensitive path protection:

Operation	Seatbelt Rule	Result
`stat ~/.ssh`	`file-read-metadata`	Allowed
`test -d ~/.ssh`	`file-read-metadata`	Allowed
`ls ~/.ssh`	`file-read-data` (readdir)	Blocked
`cat ~/.ssh/id_rsa`	`file-read-data`	Blocked

This approach:

Prevents data exfiltration - actual file contents cannot be read
Allows graceful error handling - programs can check if files exist without crashing
Mirrors TCC behavior - feels native to macOS users

System Paths

nono allows read access to system paths required for running executables. These are loaded from security-lists.toml:

Category	Paths	Purpose
Executables	`/System/Library`, `/Library`, `/usr/lib`	System binaries and libraries
Frameworks	`/System/Library/Frameworks`, `/Library/Frameworks`	macOS frameworks
dyld	`/private/var/db/dyld`, `/var/db`	Dynamic linker cache
SSL	`/etc/ssl`, `/private/etc/ssl`	Certificate stores
Locale	`/usr/share/zoneinfo`, `/usr/share/locale`	Timezone and locale data
System	`/var`, `/private/var`, `/System/Volumes`	System paths and APFS volumes

The file-map-executable permission is also granted globally, which is required for dyld to map executables and shared libraries into memory.

Sensitive Paths

nono explicitly denies data access to credential storage:

Category	Paths
Cloud Credentials	`~/.aws`, `~/.azure`, `~/.gcloud`, `~/.kube`
SSH/GPG	`~/.ssh`, `~/.gnupg`
Password Managers	`~/Library/Keychains`, `~/.password-store`, `~/.1password`
Browser Data	`~/Library/Application Support/Google/Chrome`, Firefox, Safari, etc.
macOS Private	`~/Library/Messages`, `~/Library/Mail`, `~/Library/Cookies`
Shell Configs	`~/.zshrc`, `~/.bashrc`, `~/.profile`, etc. (read-blocked; may contain API keys)
History Files	`~/.zsh_history`, `~/.bash_history` (read-blocked; may contain secrets)
Credential Files	`~/.git-credentials`, `~/.netrc`, `~/.npmrc`

To access a protected path, provide both a matching filesystem or Unix socket grant and a --bypass-protection path. A grant alone does not lift a deny rule. The bypass reopens only the access modes and socket scope granted for that path; a read-only grant does not permit writes, and an exact socket exception does not reopen sibling sockets.

System Operations

nono narrows system* permissions to only what’s commonly needed:

Permission	Purpose
`system-socket`	Network socket operations
`system-fsctl`	Filesystem control operations
`system-info`	Reading system information (uname, etc.)

Notably omitted: system-audit, system-privilege, system-reboot, system-set-time

Network Control

Network access is allowed by default:

; Default (network allowed)
(allow network-outbound)
(allow network-inbound)
(allow network-bind)

; If --block-net is specified
(deny network*)

Unix Socket Connections

When a process calls connect(2) on a Unix socket (e.g., /var/run/docker.sock), Seatbelt classifies the operation as network-outbound, not a file operation. This means a file-read-data or file-write-data deny rule for the socket path will not block the connection. To block Unix socket connections, nono emits an additional rule alongside the standard file deny rules. Exact socket or file targets use path; denied directories use subpath so sockets anywhere below the directory are also blocked:

; File deny (blocks open/read/write on the socket file itself)
(allow file-read-metadata (literal "/private/var/run/docker.sock"))
(deny file-read-data (literal "/private/var/run/docker.sock"))
(deny file-write-data (literal "/private/var/run/docker.sock"))

; Network deny (blocks connect(2) to the socket)
(deny network-outbound (path "/private/var/run/docker.sock"))

; Recursive directory deny
(deny network-outbound (subpath "/private/var/run/private-agents"))

Seatbelt evaluates these rules at connect(2) time, so they also block connections to sockets created after the sandbox initializes. Non-existent deny targets use the fail-secure recursive form because they may later become directories.

Granular Filtering Limitations

Seatbelt supports filtering by protocol (TCP/UDP), direction (inbound/outbound), and even IP address via remote ip filters. However, it does not provide per-hostname or per-domain filtering. Since DNS resolution happens before the connection, filtering by domain would require:

IP allowlists - Fragile due to CDNs, load balancers, and changing IP addresses
Application-layer proxy - Adds complexity, requires elevated permissions
Packet filtering (pf) - Requires root, conflicts with nono’s design

For now, nono uses binary network control (all or nothing). Granular filtering may be explored in future releases.

Irreversibility

Once sandbox_init() is called, restrictions are permanent:

There is no sandbox_remove() or sandbox_expand() API
The process cannot modify its own sandbox
All child processes inherit the restrictions
The only way to escape is to exploit a kernel vulnerability

This is the core security guarantee.

Debugging

If a command fails with permission errors:

Run with --dry-run to see what capabilities would be granted
Run with -vvv for verbose logging (shows generated profile)
Check Console.app for sandbox violation logs:
- Filter by “sandbox” or your process name
- Violations show the exact path and operation blocked

Common Issues

Error	Likely Cause	Solution
Abort (exit 134)	Missing system path	Check if a custom tool needs additional paths
Trace/BPT trap: 5	Sandbox profile syntax error	Run with `-vvv` to see the generated profile
”Operation not permitted” on sensitive path	Working as intended	Use `--read ~/.path` to explicitly allow
Python/Node fails	Interpreter outside allowed paths	Ensure `/usr/bin`, `/usr/local/bin` are accessible
Missing env vars in subshell	Shell configs are read-blocked	Use `--read-file ~/.zshrc` if shell init is needed

Limitations

macOS Version Support

Seatbelt is available on macOS 10.5+, but nono is tested on macOS 10.15 (Catalina) and later.

APFS Firmlinks

macOS 10.15+ uses APFS with firmlinks - bidirectional hard links that make /System/Volumes/Data/Users appear as /Users. nono’s security lists include /System/Volumes to handle path resolution across firmlink boundaries. Without this, sandbox rules written for /Users/luke might not match the kernel’s resolved path /System/Volumes/Data/Users/luke.

TCC Interaction

macOS TCC (Transparency, Consent, and Control) may still block access to certain paths if the terminal running nono doesn’t have “Full Disk Access.” nono’s “Allow Discovery, Deny Content” approach mirrors TCC behavior.

App Sandbox Interaction

If nono runs inside an App Sandbox (e.g., from a sandboxed terminal), restrictions stack. The inner sandbox cannot grant more permissions than the outer sandbox allows.

Code Signing

Some macOS security features interact with code signing. Building nono from source without signing may trigger Gatekeeper warnings, but this doesn’t affect sandbox enforcement.

Getting Started

Policy

Sessions

Packaging

Networking

Secrets

Audit

Supply Chain Security

Rollback

Resource Limits

Architecture

Reference

Development

What is Seatbelt?

How nono Uses Seatbelt

Profile Structure

Security Model: “Allow Discovery, Deny Content”

System Paths

Sensitive Paths

System Operations

Network Control

Unix Socket Connections

Granular Filtering Limitations

Irreversibility

Debugging

Common Issues

Limitations

macOS Version Support

APFS Firmlinks

TCC Interaction

App Sandbox Interaction

Code Signing

References

​What is Seatbelt?

​How nono Uses Seatbelt

​Profile Structure

​Security Model: “Allow Discovery, Deny Content”

​System Paths

​Sensitive Paths

​System Operations

​Network Control

​Unix Socket Connections

​Granular Filtering Limitations

​Irreversibility

​Debugging

​Common Issues

​Limitations

​macOS Version Support

​APFS Firmlinks

​TCC Interaction

​App Sandbox Interaction

​Code Signing

​References

What is Seatbelt?

How nono Uses Seatbelt

Profile Structure

Security Model: “Allow Discovery, Deny Content”

System Paths

Sensitive Paths

System Operations

Network Control

Unix Socket Connections

Granular Filtering Limitations

Irreversibility

Debugging

Common Issues

Limitations

macOS Version Support

APFS Firmlinks

TCC Interaction

App Sandbox Interaction

Code Signing

References