How to Analyze and Diff Sandbox Profiles Using the ipsw Tool

The ipsw CLI provides a hidden sandbox sub-command that compares Seatbelt (sandbox) profiles between two macOS or iOS IPSW files, extracting and diffing .sb policy files automatically.

The ipsw tool by blacktop/ipsw is a comprehensive utility for analyzing Apple firmware. Among its advanced features is the ability to analyze and diff sandbox profiles using the ipsw tool, which helps security researchers track policy changes between iOS or macOS versions.

What Are Sandbox Profiles in macOS and iOS?

Sandbox profiles, also known as Seatbelt profiles, define the security policy for processes running on Apple operating systems. These policies specify which files, network resources, and system calls a process can access. Each profile is stored as a .sb file within the IPSW firmware bundle, typically embedded within the AppOS, FileSystemOS, or SystemOS DMG volumes.

Prerequisites for Analyzing Sandbox Profiles

Enabling the Sandbox Build Tag

The sandbox functionality is implemented in the cmd/ipsw/cmd/sb package and is conditionally compiled using the sandbox build tag. To access these commands, you must install ipsw with the tag enabled:

go install -tags sandbox ./cmd/ipsw

Pre-built releases may already include this functionality. Verify availability by running ipsw sb --help.

How to Diff Sandbox Profiles Between IPSW Files

Basic Diff Command

To compare sandbox profiles between two firmware versions, use the sb diff sub-command. This extracts all .sb files from both IPSWs and generates a git-style diff:

ipsw sb diff iOS_15.7_19H2_Restore.ipsw iOS_16.1_20B29_Restore.ipsw

The command performs the following actions as implemented in cmd/ipsw/cmd/sb/sb_diff.go:

1. Parses both IPSWs using info.Parse from pkg/info to locate the OS DMGs
2. Extracts DMGs using utils.Unzip from internal/utils
3. Mounts each DMG read-only via utils.MountDMG
4. Recursively walks the mount points to collect all .sb files into a map[string]string
5. Generates diffs using utils.GitDiff with colorized output via fatih/color

Handling AEA-Encrypted DMGs

Modern IPSWs use AEA encryption for DMG files. When analyzing these, provide a PEM database to decrypt the volumes:

ipsw sb diff --pem-db ~/pemdb.json \
    iPadOS_15.4_19E240_Restore.ipsw \
    iPadOS_16.0_20A5395d_Restore.ipsw

The tool calls aea.Decrypt from pkg/aea to handle decryption using the provided PEM database before mounting.

Understanding the Output

The diff output uses distinct visual indicators for different change types:

• New profiles: Displayed with full syntax highlighting using quick.Highlight
• Modified profiles: Show git-style diffs with - (removed) and + (added) lines, colorized with fatih/color
• Removed profiles: Reported as warnings (e.g., WARN Sandbox Profile Removed profile=/System/Library/ExtensionKit/OldProfile.sb)

Example output structure:

🆕 Library/Apple/Preferences/com.apple.preference.security.sandbox.sb
 ╭───────────────────────────────────────────────────────────────────────
[syntax highlighted profile content]
 ╰───────────────────────────────────────────────────────────────────────

/System/Library/ExtensionKit/SandboxProfile.sb
 ╭───────────────────────────────────────────────────────────────────────
- (allow file-read-data (subpath "/System/Library/Frameworks"))
+ (allow file-read-data (subpath "/System/Library/Frameworks" (literal "/AppKit")))
 ╰───────────────────────────────────────────────────────────────────────

Technical Implementation Details

The sandbox analysis pipeline is implemented across several packages in the blacktop/ipsw repository:

• cmd/ipsw/cmd/sb/sb.go: Defines the hidden SbCmd root command
• cmd/ipsw/cmd/sb/sb_diff.go: Contains the sbDiffCmd implementation with the complete workflow from extraction to diffing
• pkg/info/info.go: Provides info.Parse for reading IPSW manifests and locating DMG paths
• pkg/aea/decrypt.go: Handles AEA decryption via aea.Decrypt
• internal/utils/mount.go: Implements utils.MountDMG and utils.Unmount for volume management
• internal/utils/diff.go: Provides utils.GitDiff for text comparison
• internal/utils/unzip.go: Contains utils.Unzip for extracting files from IPSW archives

The process is completely self-contained, requiring no external tools, and supports modern MH_FILESET kernelcache style IPSWs using the same mechanism as ipsw macho info --fileset-entry "com.apple.security.sandbox".

Summary

• The ipsw tool provides a hidden sb diff command to analyze and diff sandbox profiles between two IPSW firmware files.
• The functionality requires the sandbox build tag (go install -tags sandbox ./cmd/ipsw) and is implemented in cmd/ipsw/cmd/sb/sb_diff.go.
• The tool automatically extracts, decrypts (if AEA-encrypted), mounts, and walks DMG volumes to collect .sb files.
• Output includes syntax-highlighted new profiles, git-style diffs for modifications, and warnings for removed profiles.
• The entire pipeline is self-contained, using utils.GitDiff, quick.Highlight, and fatih/color for presentation.

Frequently Asked Questions

What is the ipsw sandbox command?

The ipsw sandbox command (aliased as ipsw sb) is a hidden sub-command in the blacktop/ipsw tool that provides utilities for analyzing Apple Seatbelt sandbox profiles. The primary functionality is the diff sub-command, which compares .sb policy files between two IPSW firmware versions to identify security policy changes.

How do I install ipsw with sandbox support?

To access the sandbox analysis features, you must compile ipsw with the sandbox build tag. Run the following command from the repository root:

go install -tags sandbox ./cmd/ipsw

Pre-built release binaries may already include this functionality. You can verify installation by running ipsw sb --help to see if the sandbox commands are available.

Can I diff sandbox profiles from encrypted IPSW files?

Yes, the ipsw sb diff command supports AEA-encrypted DMGs found in modern IPSW files. You must provide a PEM database JSON file using the --pem-db flag that maps certificates to decryption keys. The tool uses the aea.Decrypt function from pkg/aea to decrypt volumes before mounting and analysis.

Where are sandbox profiles stored in an IPSW?

Sandbox profiles (.sb files) are stored within the DMG volumes contained in the IPSW archive, specifically within the AppOS, FileSystemOS, and SystemOS DMGs. The ipsw sb diff command automatically mounts these DMGs and recursively searches for all .sb files to perform the comparison.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}