# Ipsw > Use this skill when reverse-engineering Apple platforms with the ipsw CLI — analyzing iOS/macOS Mach-O binaries, disassembling functions inside dyld_shared_cache (DSC), dumping Objective-C/Swift headers from private frameworks, extracting kernelcaches, KEXTs, SEP, iBoot, or DeviceTree from IPSWs/OTAs, decompiling/querying sandbox profiles (SBPL), querying entitlements, symbolicating crashes/panic… - **Type:** Skill - **Install:** `agentstack add skill-blacktop-ipsw-skill-ipsw` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [blacktop](https://agentstack.voostack.com/s/blacktop) - **Installs:** 0 - **Category:** [Security](https://agentstack.voostack.com/c/security) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [blacktop](https://github.com/blacktop) - **Source:** https://github.com/blacktop/ipsw-skill/tree/main/ipsw ## Install ```sh agentstack add skill-blacktop-ipsw-skill-ipsw ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # IPSW - Apple Reverse Engineering Toolkit **Install:** `brew install blacktop/tap/ipsw` (Linux: see https://github.com/blacktop/ipsw#install) ## Choose Your Workflow | Goal | Start Here | |------|------------| | Download/extract firmware | [Firmware Acquisition](#firmware-acquisition) | | Reverse engineer userspace | [Userspace RE](#userspace-re-dyld_shared_cache) | | Analyze kernel/KEXTs | [Kernel Analysis](#kernel-analysis) | | Research entitlements | [Entitlements](#entitlements) | | Dump private API headers | [Class Dump](#class-dump) | | Analyze standalone binary | [Mach-O Analysis](#mach-o-analysis) | | Diff two IPSWs/OTAs | [Firmware Diffing](#firmware-diffing) | | Symbolicate a crash / panic | [Symbolication](#symbolication) | | Parse IMG4/AEA/iBoot/SEP | [Firmware Components](#firmware-components-img4-aea-iboot-sep) | | Decompile / query sandbox profiles | [Sandbox Profile Analysis](#sandbox-profile-analysis-sb) | | Inspect / mount an IPSW | [IPSW Inspection](#ipsw-inspection) | --- ## Firmware Acquisition ```bash # Download latest IPSW for device ipsw download ipsw --device iPhone16,1 --latest # Download with automatic kernel/DSC extraction ipsw download ipsw --device iPhone16,1 --latest --kernel --dyld # Extract components from local IPSW ipsw extract --kernel iPhone16,1_18.0_Restore.ipsw ipsw extract --dyld --dyld-arch arm64e iPhone16,1_18.0_Restore.ipsw # Remote extraction (no full download) ipsw extract --kernel --remote ``` See [references/download.md](references/download.md) for device identifiers and advanced options. --- ## Userspace RE (dyld_shared_cache) **macOS DSC location:** - macOS 14+: `/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e` - macOS 13 and earlier: `/System/Library/dyld/dyld_shared_cache_arm64e` Examples below assume: ```bash export DSC=/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e ``` ### Essential Commands | Command | Purpose | |---------|---------| | `dyld a2s ` | Address → symbol (triage crash LR/PC) | | `dyld symaddr --image ` | Symbol → address | | `dyld disass --vaddr ` | Disassemble at address | | `dyld disass --symbol --image ` | Disassemble by symbol | | `dyld xref --all` | Find all references to address | | `dyld dump --size 256` | Dump raw bytes at address | | `dyld str "pattern" --image ` | Search strings | | `dyld objc --class --image ` | List ObjC classes | | `dyld extract -o ./out/` | Extract dylib for external tools | ### Common Workflow ```bash # 1. Resolve address from crash/trace ipsw dyld a2s $DSC 0x1bc39e1e0 # → -[SomeClass someMethod:] + 0x40 # 2. Disassemble around that address ipsw dyld disass $DSC --vaddr 0x1bc39e1e0 # 3. Find who calls this function ipsw dyld xref $DSC 0x1bc39e1a0 --all # 4. Extract string/data referenced in disassembly ipsw dyld dump $DSC 0x1bc39e200 --size 64 ``` See [references/dyld.md](references/dyld.md) for complete DSC commands. --- ## Kernel Analysis ```bash # List all KEXTs ipsw kernel kexts kernelcache.release.iPhone16,1 # Extract specific KEXT ipsw kernel extract kernelcache sandbox --output ./kexts/ # Dump syscalls ipsw kernel syscall kernelcache # Diff KEXTs between versions ipsw kernel kexts --diff kernelcache_17.0 kernelcache_18.0 ``` See [references/kernel.md](references/kernel.md) for KEXT extraction and kernel analysis. --- ## Entitlements ```bash # Single binary entitlements ipsw macho info --ent /path/to/binary # Build searchable database from IPSW ipsw ent --sqlite ent.db --ipsw iOS18.ipsw # Query database ipsw ent --sqlite ent.db --key "com.apple.private.security.no-sandbox" ipsw ent --sqlite ent.db --key "platform-application" ipsw ent --sqlite ent.db --key "com.apple.private.tcc.manager" ``` See [references/entitlements.md](references/entitlements.md) for common entitlements and query patterns. --- ## Class Dump Dump Objective-C headers from binaries or dyld_shared_cache: ```bash # Dump all headers from framework in DSC ipsw class-dump $DSC SpringBoardServices --headers -o ./headers/ # Dump specific class ipsw class-dump $DSC Security --class SecKey # Filter by pattern ipsw class-dump $DSC UIKit --class 'UIApplication.*' --headers -o ./headers/ # Include runtime addresses (for hooking) ipsw class-dump $DSC Security --re # Swift class-dump (separate command, same shape) ipsw swift-dump $DSC SwiftUI --headers -o ./headers/ ``` See [references/class-dump.md](references/class-dump.md) for filtering and output options. --- ## Mach-O Analysis ```bash # Full binary info ipsw macho info /path/to/binary # Disassemble function ipsw macho disass /path/to/binary --symbol _main # Get entitlements and signature ipsw macho info --ent /path/to/binary ipsw macho info --sig /path/to/binary ``` See [references/macho.md](references/macho.md) for complete Mach-O commands. --- ## Firmware Diffing Compare two IPSWs, OTAs, or patched OTA directories — surfaces added/removed binaries, entitlement changes, function-starts deltas, and KEXT diffs. ```bash # Diff two IPSWs (markdown report) ipsw diff old.ipsw new.ipsw --output ./diff/ --markdown # Include firmware components (iBoot, SEP, etc.) and launchd configs ipsw diff old.ipsw new.ipsw --fw --launchd --output ./diff/ --markdown # Diff with KDKs for kernel symbol resolution ipsw diff old.ipsw new.ipsw --output ./diff/ --markdown \ --kdk /System/Library/Kernels/kernel.release.t6031 \ --kdk /System/Library/Kernels/kernel.release.t6031 # Entitlement-only diff ipsw diff old.ipsw new.ipsw --ent --output ./diff/ # Diff two OTAs (macOS 14+ AEA-encrypted; supply key DB) ipsw diff old.ota new.ota --key-db keys.json --output ./diff/ --markdown ``` --- ## Symbolication ```bash # Symbolicate a panic / crash log against an IPSW ipsw symbolicate panic-full-2024-03-21.ips iPhone16,1_18.0_Restore.ipsw # Show disassembly around panic frames ipsw symbolicate panic.ips firmware.ipsw --peek --peek-count 10 # Symbolicate against a DSC instead ipsw symbolicate crash.ips $DSC ``` --- ## Firmware Components (IMG4, AEA, iBoot, SEP) For Apple firmware containers — IMG4/IM4P/IM4M, AEA1-encrypted DMGs, iBoot, SEP, AOP, DCP, baseband, and trust caches: ```bash # IMG4 / IM4P / IM4M operations ipsw img4 info my.img4 ipsw img4 extract --im4p my.img4 --output ./ # IM4P payload (decompressed) ipsw img4 extract --im4p --im4m --im4r my.img4 -o ./ # All components # Firmware sub-binaries (iBoot, exclave, AOP, GPU, DCP, baseband) ipsw fw iboot iBoot.img4 ipsw fw aea --info encrypted.dmg.aea # AEA1 DMG metadata ipsw fw aea --key encrypted.dmg.aea # Pull decryption key ipsw fw tc TrustCache.img4 # Dump trust cache entries ``` See `ipsw img4 --help` and `ipsw fw --help` for the full list of subcommands. --- ## Sandbox Profile Analysis (`sb`) Decode and query Apple sandbox profiles compiled into a kernelcache. Useful for capability analysis ("which profiles can open IOSurface?"), attack-surface mapping, and tracking sandbox changes between releases. ```bash # List every profile in a kernelcache ipsw sb list kernelcache.release.iPhone18,1 # Decompile one profile to SBPL (Sandbox Profile Language) ipsw sb dec kernelcache.release.iPhone18,1 com.apple.WebKit.WebContent -O WebContent.sb # Diff sandbox operations between two kernels (find new/removed checks) ipsw sb opts --diff kernelcache_old kernelcache_new # Build the cross-profile graph once, then query repeatedly (queries become sub-second) ipsw sb graph export kernelcache.release.iPhone18,1 -O graph.json # Capability queries against the graph ipsw sb query iokit-open IOSurfaceRootUserClient --graph graph.json ipsw sb query path-write /private/var/mobile/tmp --graph graph.json ipsw sb query syscall mmap --graph graph.json ipsw sb query mach-lookup com.apple.mobilegestalt.xpc --graph graph.json ``` Available query subcommands: `iokit-open`, `path-read`, `path-write`, `syscall`, `sysctl`, `mach-lookup`, `mach-register`, `preference`, `notification`, `cypher`. See [references/sandbox.md](references/sandbox.md) for the full sandbox toolkit. --- ## IPSW Inspection ```bash # Summarize an IPSW/OTA (devices, builds, file list) ipsw info iPhone16,1_18.0_Restore.ipsw ipsw info --list iPhone16,1_18.0_Restore.ipsw # full file listing ipsw info --remote # without downloading # Mount the filesystem / system / dyld_shared_cache DMG ipsw mount fs iPhone16,1_18.0_Restore.ipsw # filesystem ipsw mount sys iPhone16,1_18.0_Restore.ipsw # system ipsw mount exc iPhone16,1_18.0_Restore.ipsw # dyld_shared_cache (cryptex) # Parse the DeviceTree ipsw dtree iPhone16,1_18.0_Restore.ipsw --summary ipsw dtree iPhone16,1_18.0_Restore.ipsw --json | jq '.["device-tree"]["compatible"]' ``` For AEA-encrypted DMGs (macOS 14+), pass `--key-db keys.json` or `--pem-db pem.json`. --- ## Pitfalls 1. **Symbol cache must be primed.** First `dyld a2s`/`symaddr` on a DSC creates `.a2s`. Until then lookups appear to "find nothing". Run `dyld a2s $DSC ` once before scripting bulk lookups. 2. **AEA-encrypted IPSWs/OTAs.** Modern macOS OTAs can ship as AEA1 archives. Pass `--key-val ` or `--key-db keys.json` to commands that need to read them (`diff`, `extract`, `fw aea`). 3. **Always pass `--image `** for DSC ops. Without it, ipsw walks every dylib map — 10x+ slower. 4. **Multi-arch DSCs need `--dyld-arch`.** Without it, extraction may pick the wrong slice (arm64 vs arm64e) silently. --- ## Reference Files - [references/download.md](references/download.md) - Firmware download, device IDs, extraction - [references/dyld.md](references/dyld.md) - Complete DSC commands (a2s, xref, dump, str, extract) - [references/kernel.md](references/kernel.md) - Kernel and KEXT analysis - [references/entitlements.md](references/entitlements.md) - Entitlements database and queries - [references/class-dump.md](references/class-dump.md) - ObjC header dumping - [references/macho.md](references/macho.md) - Mach-O binary analysis - [references/sandbox.md](references/sandbox.md) - Sandbox profiles (`sb`): decompile, diff, graph, capability queries ## Tips 1. **JSON output:** Most commands support `--json` for scripting (e.g. `ipsw dyld info --dylibs --json $DSC | jq -r '.images[].name'`). 2. **Device IDs:** `ipsw device-list` lists every known identifier; `ipsw device-info iPhone16,1` describes a specific one. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [blacktop](https://github.com/blacktop) - **Source:** [blacktop/ipsw-skill](https://github.com/blacktop/ipsw-skill) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-blacktop-ipsw-skill-ipsw - Seller: https://agentstack.voostack.com/s/blacktop - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.