Skip to main content
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:
OperationSeatbelt RuleResult
stat ~/.sshfile-read-metadataAllowed
test -d ~/.sshfile-read-metadataAllowed
ls ~/.sshfile-read-data (readdir)Blocked
cat ~/.ssh/id_rsafile-read-dataBlocked
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:
CategoryPathsPurpose
Executables/System/Library, /Library, /usr/libSystem binaries and libraries
Frameworks/System/Library/Frameworks, /Library/FrameworksmacOS frameworks
dyld/private/var/db/dyld, /var/dbDynamic linker cache
SSL/etc/ssl, /private/etc/sslCertificate stores
Locale/usr/share/zoneinfo, /usr/share/localeTimezone and locale data
System/var, /private/var, /System/VolumesSystem 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:
CategoryPaths
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
Users can override these with explicit --allow or --read flags.

​
System Operations

nono narrows system* permissions to only what’s commonly needed:
PermissionPurpose
system-socketNetwork socket operations
system-fsctlFilesystem control operations
system-infoReading 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 when a socket path appears in add_deny_access: 
; 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"))
The network-outbound rule uses (path ...) for an exact match rather than (subpath ...) because socket connections match on the precise path. Seatbelt evaluates this rule at connect(2) time, so it blocks connections to sockets that do not exist when the sandbox initializes.

​
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:
  1. IP allowlists - Fragile due to CDNs, load balancers, and changing IP addresses
  2. Application-layer proxy - Adds complexity, requires elevated permissions
  3. 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:
  1. Run with --dry-run to see what capabilities would be granted
  2. Run with -vvv for verbose logging (shows generated profile)
  3. Check Console.app for sandbox violation logs:
    • Filter by “sandbox” or your process name
    • Violations show the exact path and operation blocked

​
Common Issues

ErrorLikely CauseSolution
Abort (exit 134)Missing system pathCheck if a custom tool needs additional paths
Trace/BPT trap: 5Sandbox profile syntax errorRun with -vvv to see the generated profile
”Operation not permitted” on sensitive pathWorking as intendedUse --read ~/.path to explicitly allow
Python/Node failsInterpreter outside allowed pathsEnsure /usr/bin, /usr/local/bin are accessible
Missing env vars in subshellShell configs are read-blockedUse --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. 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.

​
References