seatbelt-sandboxer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macOS Seatbelt Sandbox Profiling

macOS Seatbelt沙箱配置生成

Generate minimally-permissioned allowlist-based Seatbelt sandbox configurations for applications.

生成具备最小权限的、基于白名单的Seatbelt沙箱配置文件，用于管控应用权限。

When to Use

适用场景

User asks to "sandbox", "isolate", or "restrict" an application on macOS
Sandboxing any macOS process that needs restricted file/network access
Creating defense-in-depth isolation if supply chain attacks are a concern

用户需要对macOS应用进行「沙箱隔离」「独立运行」或「权限限制」时
对任何需要限制文件/网络访问的macOS进程进行沙箱管控时
若担心供应链攻击，需要构建纵深防御隔离机制时

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

Linux容器（请改用seccomp-bpf、AppArmor或命名空间）
Windows应用
合法需要广泛系统访问权限的应用
一次性脚本，沙箱带来的开销得不偿失时

Profiling Methodology

配置生成方法

Step 1: Identify Application Requirements

步骤1：明确应用需求

Determine what the application needs across these resource categories:

Category	Operations	Common Use Cases
File Read	`file-read-data` , `file-read-metadata` , `file-read-xattr` , `file-test-existence` , `file-map-executable`	Reading source files, configs, libraries
File Write	`file-write-data` , `file-write-create` , `file-write-unlink` , `file-write-mode` , `file-write-xattr` , `file-clone` , `file-link`	Output files, caches, temp files
Network	`network-bind` , `network-inbound` , `network-outbound`	Servers, API calls, package downloads
Process	`process-fork` , `process-exec` , `process-exec-interpreter` , `process-info` , `process-codesigning`	Spawning child processes, scripts
Mach IPC	`mach-lookup` , `mach-register` , `mach-bootstrap` , `mach-task-name`	System services, XPC, notifications
POSIX IPC	`ipc-posix-shm` , `ipc-posix-sem`	Shared memory, semaphores
Sysctl	`sysctl-read` , `sysctl-write`	Reading system info (CPU, memory)
IOKit	`iokit-open` , `iokit-get-properties` , `iokit-set-properties`	Hardware access, device drivers
Signals	`signal`	Signal handling between processes
Pseudo-TTY	`pseudo-tty`	Terminal emulation
System	`system-fsctl` , `system-socket` , `system-audit` , `system-info`	Low-level system calls
User Prefs	`user-preference-read` , `user-preference-write`	Reading/writing user defaults
Notifications	`darwin-notification-post` , `distributed-notification-post`	System notifications
AppleEvents	`appleevent-send`	Inter-app communication (AppleScript)
Camera/Mic	`device-camera` , `device-microphone`	Media capture
Dynamic Code	`dynamic-code-generation`	JIT compilation
NVRAM	`nvram-get` , `nvram-set` , `nvram-delete`	Firmware variables

For each category, determine: Needed? and Specific scope (paths, services, etc.)

If the application has multiple subcommands that perform significantly different operations, such as

build

and

serve

commands for a Javascript bundler like Webpack, do the following:

Profile the subcommands separately
Create separate Sandbox configurations for each subcommand
Create a helper script that acts as a drop-in replacement for the original binary, executing the sandboxed application with the appropriate Seatbelt profile according to the subcommand passed.

确定应用在以下资源类别中的权限需求：

类别	操作权限	常见场景
文件读取	`file-read-data` , `file-read-metadata` , `file-read-xattr` , `file-test-existence` , `file-map-executable`	读取源文件、配置文件、库文件
文件写入	`file-write-data` , `file-write-create` , `file-write-unlink` , `file-write-mode` , `file-write-xattr` , `file-clone` , `file-link`	输出文件、缓存文件、临时文件
网络	`network-bind` , `network-inbound` , `network-outbound`	服务器运行、API调用、包下载
进程	`process-fork` , `process-exec` , `process-exec-interpreter` , `process-info` , `process-codesigning`	生成子进程、执行脚本
Mach进程间通信	`mach-lookup` , `mach-register` , `mach-bootstrap` , `mach-task-name`	系统服务、XPC、通知
POSIX进程间通信	`ipc-posix-shm` , `ipc-posix-sem`	共享内存、信号量
系统控制	`sysctl-read` , `sysctl-write`	读取系统信息（CPU、内存）
IOKit	`iokit-open` , `iokit-get-properties` , `iokit-set-properties`	硬件访问、设备驱动
信号	`signal`	进程间信号处理
伪终端	`pseudo-tty`	终端模拟
系统调用	`system-fsctl` , `system-socket` , `system-audit` , `system-info`	底层系统调用
用户偏好设置	`user-preference-read` , `user-preference-write`	读取/写入用户默认设置
通知	`darwin-notification-post` , `distributed-notification-post`	系统通知
Apple事件	`appleevent-send`	应用间通信（AppleScript）
摄像头/麦克风	`device-camera` , `device-microphone`	媒体捕获
动态代码	`dynamic-code-generation`	JIT编译
NVRAM	`nvram-get` , `nvram-set` , `nvram-delete`	固件变量

针对每个类别，确定：是否需要？以及具体范围（路径、服务等）

如果应用包含多个操作差异显著的子命令（例如Webpack这类JavaScript打包工具的

build

和

serve

命令），请执行以下操作：

分别为每个子命令生成配置
为每个子命令创建独立的沙箱配置文件
编写一个辅助脚本替代原二进制文件，根据传入的子命令自动加载对应的Seatbelt配置并执行沙箱化的应用

Step 2: Start with Minimal Profile

步骤2：从最小权限配置开始

Begin with deny-all and essential process operations, saved in a suitably-named Seatbelt profile file with the

.sb

extension.

scheme

(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)

从拒绝所有操作+必要进程权限的配置开始，保存为以

.sb

为后缀的Seatbelt配置文件。

scheme

(version 1)
(deny default)

;; 所有进程的必要权限
(allow process-exec*)
(allow process-fork)
(allow sysctl-read)

;; 元数据访问（stat、readdir）- 不会暴露文件内容
(allow file-read-metadata)

Step 3: Add File Read Access (Allowlist)

步骤3：添加文件读取权限（白名单模式）

Use

file-read-data

(not

file-read*

) for allowlist-based reads:

scheme

(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")))

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

```
file-read*
```
allows ALL file read operations including 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

使用

file-read-data

（而非

file-read*

）实现白名单式读取：

scheme

(allow file-read-data
    ;; 系统路径（多数运行时环境必需）
    (subpath "/usr")
    (subpath "/bin")
    (subpath "/sbin")
    (subpath "/System")
    (subpath "/Library")
    (subpath "/opt")                    ;; Homebrew路径
    (subpath "/private/var")
    (subpath "/private/etc")
    (subpath "/private/tmp")
    (subpath "/dev")

    ;; 根目录符号链接（用于路径解析）
    (literal "/")
    (literal "/var")
    (literal "/etc")
    (literal "/tmp")
    (literal "/private")

    ;; 应用专属配置（根据需要自定义）
    (regex (string-append "^" (regex-quote (param "HOME")) "/\\.myapp(/.*)?$"))

    ;; 工作目录
    (subpath (param "WORKING_DIR")))

为什么用
file-read-data
而非
file-read*
？

```
file-read*
```
允许所有文件读取操作，包括任意路径
```
file-read-data
```
仅允许读取白名单路径下的文件内容
结合全局允许的
```
file-read-metadata
```
，可实现：
- ✅ 可在任意路径执行stat/readdir（路径解析必需）
- ❌ 无法读取白名单外的文件内容

Step 4: Add File Write Access (Restricted)

步骤4：添加文件写入权限（受限模式）

scheme

(allow file-write*
    ;; Working directory only
    (subpath (param "WORKING_DIR"))

    ;; Temp directories
    (subpath "/private/tmp")
    (subpath "/tmp")
    (subpath "/private/var/folders")

    ;; Device files for output
    (literal "/dev/null")
    (literal "/dev/tty"))

scheme

(allow file-write*
    ;; 仅允许工作目录
    (subpath (param "WORKING_DIR"))

    ;; 临时目录
    (subpath "/private/tmp")
    (subpath "/tmp")
    (subpath "/private/var/folders")

    ;; 输出设备文件
    (literal "/dev/null")
    (literal "/dev/tty"))

Step 5: Configure Network

步骤5：配置网络权限

Three levels of network access:

scheme

;; OPTION 1: Block all network (most restrictive - use for build tools)
(deny network*)

;; OPTION 2: Localhost only (use for dev servers, 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

;; OPTION 3: Allow all network (least restrictive - avoid if possible)
(allow network*)

Network filter syntax:

```
(local tcp "*:*")
```
- any local TCP port
```
(local tcp "*:8080")
```
- specific local port
```
(remote ip "localhost:*")
```
- outbound to localhost only
```
(remote tcp)
```
- outbound TCP to any host

(literal "/private/var/run/mDNSResponder")

- Unix socket for DNS

提供三种网络访问级别：

scheme

;; 选项1：完全禁用网络（最严格 - 适用于构建工具）
(deny network*)

;; 选项2：仅允许本地访问（适用于开发服务器、本地服务）
;; 绑定本地端口
(allow network-bind (local tcp "*:*"))
;; 接受本地入站连接
(allow network-inbound (local tcp "*:*"))
;; 仅允许出站到本地主机+DNS
(allow network-outbound
    (literal "/private/var/run/mDNSResponder")  ;; DNS解析
    (remote ip "localhost:*"))                   ;; 仅本地主机

;; 选项3：允许所有网络（最宽松 - 尽量避免使用）
(allow network*)

网络过滤语法说明：

```
(local tcp "*:*")
```
- 任意本地TCP端口
```
(local tcp "*:8080")
```
- 指定本地端口
```
(remote ip "localhost:*")
```
- 仅允许出站到本地主机
```
(remote tcp)
```
- 允许出站到任意主机的TCP连接

(literal "/private/var/run/mDNSResponder")

- 用于DNS解析的Unix套接字

Step 6: Test Iteratively

步骤6：迭代测试

After you generate or edit the Seatbelt profile, test the functionality of the target application in the sandbox. If anything fails to work, revise the Seatbelt profile. Repeat this process iteratively until you have generated a minimally-permissioned Seatbelt file and have confirmed empirically that the application works normally when sandboxed using the Seatbelt profile you generated.

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, these example projects for the Rspack bundler: https://github.com/rstackjs/rstack-examples/tree/main/rspack/

bash

undefined

生成或修改Seatbelt配置后，测试目标应用在沙箱中的运行情况。若功能异常，调整配置文件。重复此过程，直到生成具备最小权限的Seatbelt文件，且应用在沙箱中可正常运行。

如果程序需要外部输入才能完整运行（例如需要待打包应用的JavaScript打包工具），请从知名的官方来源获取测试用例。例如Rspack打包工具的示例项目：https://github.com/rstackjs/rstack-examples/tree/main/rspack/

bash

undefined

Test basic execution

测试基础执行

sandbox-exec -f profile.sb -D WORKING_DIR=/path -D HOME=$HOME /bin/echo "test"

Test the actual application

测试目标应用

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

Test security restrictions

测试安全限制

sandbox-exec -f profile.sb -D WORKING_DIR=/tmp -D HOME=$HOME
cat ~/.ssh/id_rsa

Expected: Operation not permitted

预期结果：Operation not permitted（操作不被允许）


**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 |


**常见故障模式：**

| 症状 | 原因 | 解决方法 |
|---------|-------|-----|
| 退出码134（SIGABRT） | 沙箱权限违规 | 检查被阻止的操作 |
| 退出码65+语法错误 | 配置文件语法无效 | 检查Seatbelt语法 |
| 存在的文件返回`ENOENT` | 缺少`file-read-metadata`权限 | 添加`(allow file-read-metadata)` |
| 进程挂起 | 缺少进程间通信权限 | 若需要，添加`(allow mach-lookup)` |

Seatbelt Syntax Reference

Seatbelt语法参考

Path Filters

路径过滤器

scheme

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

scheme

(subpath "/path")           ;; /path及其所有子路径
(literal "/path/file")      ;; 仅精确匹配该路径
(regex "^/path/.*\\.js$")   ;; 正则表达式匹配

Parameter Substitution

参数替换

scheme

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

scheme

(param "WORKING_DIR")                                    ;; 直接使用参数
(subpath (param "WORKING_DIR"))                          ;; 在子路径中使用参数
(string-append (param "HOME") "/.config")                ;; 字符串拼接
(regex-quote (param "HOME"))                             ;; 正则转义

Operations

操作权限

File operations:

scheme

(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)

Process operations:

scheme

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

Network operations:

scheme

(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

IPC operations:

scheme

(allow mach-lookup ...)             ;; Mach IPC lookups
(allow mach-register ...)           ;; Register Mach services
(allow ipc-posix-shm* ...)          ;; POSIX shared memory
(allow ipc-posix-sem* ...)          ;; POSIX semaphores

System operations:

scheme

(allow sysctl-read)                 ;; Read system info
(allow sysctl-write ...)            ;; Modify sysctl (rare)
(allow iokit-open ...)              ;; IOKit device access
(allow pseudo-tty)                  ;; Terminal emulation
(allow dynamic-code-generation)     ;; JIT compilation
(allow user-preference-read ...)    ;; Read user defaults

文件操作：

scheme

(allow file-read-data ...)          ;; 读取文件内容
(allow file-read-metadata)          ;; stat、lstat、readdir（不读取内容）
(allow file-read-xattr ...)         ;; 读取扩展属性
(allow file-test-existence ...)     ;; 检查文件是否存在
(allow file-map-executable ...)     ;; 映射可执行文件（动态库）
(allow file-write-data ...)         ;; 写入已有文件
(allow file-write-create ...)       ;; 创建新文件
(allow file-write-unlink ...)       ;; 删除文件
(allow file-write* ...)             ;; 所有写入操作
(allow file-read* ...)              ;; 所有读取操作（谨慎使用）

进程操作：

scheme

(allow process-exec* ...)           ;; 执行二进制文件
(allow process-fork)                ;; 生成子进程
(allow process-info-pidinfo)        ;; 查询进程信息
(allow signal)                      ;; 发送/接收信号

网络操作：

scheme

(allow network-bind (local tcp "*:*"))              ;; 绑定任意本地TCP端口
(allow network-bind (local tcp "*:8080"))           ;; 绑定指定端口
(allow network-inbound (local tcp "*:*"))           ;; 接受TCP入站连接
(allow network-outbound (remote ip "localhost:*"))  ;; 仅允许出站到本地主机
(allow network-outbound (remote tcp))               ;; 允许出站到任意主机的TCP连接
(allow network-outbound
    (literal "/private/var/run/mDNSResponder"))     ;; 通过Unix套接字进行DNS解析
(allow network*)                                    ;; 允许所有网络操作（谨慎使用）
(deny network*)                                     ;; 阻止所有网络操作

进程间通信操作：

scheme

(allow mach-lookup ...)             ;; Mach进程间通信查找
(allow mach-register ...)           ;; 注册Mach服务
(allow ipc-posix-shm* ...)          ;; POSIX共享内存
(allow ipc-posix-sem* ...)          ;; POSIX信号量

系统操作：

scheme

(allow sysctl-read)                 ;; 读取系统信息
(allow sysctl-write ...)            ;; 修改系统控制参数（罕见需求）
(allow iokit-open ...)              ;; IOKit设备访问
(allow pseudo-tty)                  ;; 终端模拟
(allow dynamic-code-generation)     ;; JIT编译
(allow user-preference-read ...)    ;; 读取用户默认设置

Known Limitations

已知限制

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

已废弃但仍可用：Apple已弃用sandbox-exec，但在macOS 14+版本中仍可正常工作
通常需要临时目录访问权限：多数应用需要访问
```
/tmp
```
和
```
/var/folders
```

Example: Generic CLI Application

示例：通用CLI应用配置

scheme

(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:

bash

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

scheme

(version 1)
(deny default)

;; 进程权限
(allow process-exec*)
(allow process-fork)
(allow sysctl-read)

;; 文件元数据（路径解析）
(allow file-read-metadata)

;; 文件读取（白名单）
(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")))

;; 文件写入（受限）
(allow file-write*
    (subpath (param "WORKING_DIR"))
    (subpath "/private/tmp") (subpath "/tmp") (subpath "/private/var/folders")
    (literal "/dev/null") (literal "/dev/tty"))

;; 禁用网络
(deny network*)

使用方法：

bash

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

seatbelt-sandboxer

Original

Translation

macOS Seatbelt Sandbox Profiling

macOS Seatbelt沙箱配置生成

When to Use

适用场景

When NOT to Use

不适用场景

Profiling Methodology

配置生成方法

Step 1: Identify Application Requirements

步骤1：明确应用需求

Step 2: Start with Minimal Profile

步骤2：从最小权限配置开始

Step 3: Add File Read Access (Allowlist)

步骤3：添加文件读取权限（白名单模式）

Step 4: Add File Write Access (Restricted)

步骤4：添加文件写入权限（受限模式）

Step 5: Configure Network

步骤5：配置网络权限

Step 6: Test Iteratively

步骤6：迭代测试

Test basic execution

测试基础执行

Test the actual application

测试目标应用

Test security restrictions

测试安全限制

Expected: Operation not permitted

预期结果：Operation not permitted（操作不被允许）

Seatbelt Syntax Reference

Seatbelt语法参考

Path Filters

路径过滤器

Parameter Substitution

参数替换

Operations

操作权限

Known Limitations

已知限制

Example: Generic CLI Application

示例：通用CLI应用配置

References

参考资料