ipsw

ipsw

ipsw は Apple ファームウェア作業のための CLI で、コマンドグループ（download、 extract、dyld、kernel、macho、fw、sb、ent、diff、symbolicate、idev、…） で構成されています。brew install blacktop/tap/ipsw でインストールできます（その他の プラットフォーム：github.com/blacktop/ipsw のリリース）。リモートコマンドとダウンロード コマンドにはネットワーク接続が必要です。idev には USB 接続されたデバイスが必要です。 このスキルの説明は、コミット 6e0291a8f（リリース 3.1.725 以降）時点の ipsw を対象として います。3.1.725 以前では、以下の「旧リリース」表を適用してください。フラグはリリースごとに 変わります。インストール済みビルドは ipsw version で確認でき、正確な情報は ipsw <group> <command> --help を参照してください。--help で 🚧 が付いているコマンドは 開発中です。

例では、以下のシェル変数（POSIX sh/bash/zsh 構文）を使用します。

IPSW=./iPhone18,1_26.4_23E246_Restore.ipsw   # local IPSW or OTA
URL=https://updates.cdn-apple.com/...          # remote IPSW or OTA (see "Triage a release")
DSC=./dyld_shared_cache_arm64e                 # main file of an extracted cache; subcaches beside it
KC=./kernelcache.release.iPhone18,1            # extracted kernelcache
DEVICE=iPhone18,1                              # any product type from `ipsw device-list`

作業上のルール

ipsw でエージェントが最も間違えやすい点を以下に示します。

1. コマンドラインですべての選択を明示します。 ターミナルがないと、ipsw はプロンプトを 表示できません。コマンドは「use --confirm to proceed unattended」（無人で続行するには --confirm を使用してください）などのエラーで停止します（旧リリースではこの手順を黙って 省略します。以下の「旧リリース」を参照してください）。代わりに選択内容を渡します。
   • 複数のイメージに一致する短い dylib 名（UIKit、SwiftUI、SpringBoard）は失敗します。 次のコマンドで確認できる、完全なインストールパスを渡してください。 ipsw dyld info --dylibs --json "$DSC" | jq -r '.dylibs[].name' | grep -i <name>。
   • Fat Mach-O では --arch arm64e、複数デバイス対応 IPSW では --device <product-type> が必要です。
   • ダウンロードとペイロード検索では -y／--confirm が必要です（download、 ota extract --pattern）。
   • ipsw mount は Ctrl+C が押されるまで停止しません。--detach を渡し、表示された hdiutil detach … コマンドを実行してください。
   • idev crash pull にはパスまたは --all が必要です。idev syslog は -t <seconds> を指定しない限り、永続的にストリーミングします。
2. ダウンロードする前にリモートで確認します。 現在の IPSW は 10～15 GB ですが、 --remote コマンドは必要なものだけを取得します。info --remote（KB）、 extract --kernel --remote（約 75 MB）、fw <component> --remote（数 MB～数十 MB）。 リモートでの extract --dyld は数 GB になります。ファイルシステム全体を対象とする作業に 限り、イメージ全体をダウンロードしてください。
3. 大量の出力を会話に含めないようにします。 --json | jq を優先し、-o／--output でファイルに書き込み、まず先頭部分や件数を確認してください。DSC 全体やカーネルのダンプは 数百万行に及びます。
4. 一度だけ発生するコストを想定し、計画します。
   • キャッシュに対する最初の dyld disass／xref では <DSC>.a2s が構築されます（数分、 約 1.5 GB）。
   • sb graph export は約 30 秒かかり、約 500 MB を書き込みます。その後、クエリの所要時間は 約 3 秒になります。
   • ファイルシステムのスキャン（ent --fs、macho search <IPSW>、diff）では、複数 GB の DMG が作業ディレクトリに展開・復号されます。
   • 最初の download appledb では約 600 MB が ~/.config/ipsw/appledb にクローンされます。 --no-update（download tss でも使用可能）を指定すると、既存のチェックアウトを再利用します。
5. 報告する前に検証します。 アドレスとシンボルの対応結果は、逆方向のコマンド（a2s と symaddr）で相互確認してください。シンボル化を信頼する前に、クラッシュログのビルドが ファームウェアと一致することを確認してください。また、ファイル名を推測するのではなく、 展開結果を一覧表示するか、extract --json を使用してください。

ワークフローを選ぶ

タスク	まず使うコマンド	詳細
ファームウェアを検索、リモートで読み取り、ダウンロード、または抽出する	ipsw download appledb ... --urls、ipsw extract	references/download.md
コプロセッサ、exclave、iBoot、SEP、IMG4、AEA、OTA の内部構造	ipsw fw <component>、ipsw img4、ipsw ota	references/firmware.md
dyld_shared_cache 内のユーザー空間コード	ipsw dyld a2s / disass / xref	references/dyld.md
プライベートフレームワークの ObjC/Swift インターフェース	ipsw class-dump、ipsw swift-dump	references/class-dump.md
スタンドアロンバイナリ：情報、エンタイトルメント、署名	ipsw macho info / disass / search	references/macho.md
Kernelcache：KEXT、シンボル、C++ クラス、システムコール	ipsw kernel ...	references/kernel.md
サンドボックスプロファイルと機能に関する質問	ipsw sb ...	references/sandbox.md
ファームウェアイメージ全体からエンタイトルメントを検索	ipsw ent ...	references/entitlements.md
2 つのビルド間の変更点	ipsw diff、--diff／--delta 系のコマンド	references/diffing.md
クラッシュログとパニック	ipsw symbolicate	references/symbolication.md
USB 接続された iPhone/iPad	ipsw idev ...	references/device.md

ダウンロードせずにリリースをトリアージする

URL="$(ipsw download appledb --os iOS --device "$DEVICE" --latest --release --urls | head -1)"
ipsw info --remote "$URL"                          # version, build, devices, CPU
ipsw info --remote --list "$URL"                   # every file in the IPSW, with sizes
ipsw fw exclave --remote "$URL" --info             # exclave bundle sections (~50 MB fetched)
KC="$(ipsw extract --kernel --remote --json -o ./fw/ "$URL" | jq -r 'keys[0]')"   # just the kernelcache
ipsw dtree --remote "$URL" --summary               # DeviceTree identity

dl と db はそれぞれ download と appledb のエイリアスです。--latest だけを指定すると、任意のチャンネルで最新のビルドが選ばれます（多くの場合ベータ版です）。--release、--beta、--rc を追加するか、--build <BUILD>／--version <X.Y> で指定してください。--type ota は OTA URL を返します。ipsw download ipsw --device "$DEVICE" --latest --urls を実行すると、AppleDB にアクセスせずに、最新の署名済み公開 IPSW を取得できます。

ユーザー空間：アドレスから説明へ

ipsw dyld a2s "$DSC" 0x18ebfa9c8                                      # symbol + offset
ipsw dyld disass "$DSC" --vaddr 0x18ebfa9a8 --count 60                 # first run builds the .a2s cache
ipsw dyld xref "$DSC" 0x18ebfa9a8 --imports                            # callers in this and dependent dylibs
ipsw dyld imports "$DSC" /System/Library/PrivateFrameworks/SpringBoardServices.framework/SpringBoardServices
ipsw class-dump "$DSC" /System/Library/PrivateFrameworks/UIKitCore.framework/UIKitCore \
  --class '^UIApplication$' --re -V | grep -B1 'BackgroundTask'

--re（-V／--verbose が必要です）を指定すると、各メソッドの実装アドレスが、そのメソッドの直前の行に // 0x… コメントとして出力されるため、フィルタリングする際は直前のコンテキスト行も残してください。アドレスは dyld disass --vaddr に渡して使用できます。UIKit のクラスは UIKitCore に含まれています。UIKit.framework/UIKit は ObjC を含まないシムです。

カーネル：名前を調べ、検索し、逆アセンブルする

ipsw kernel version "$KC"
mkdir -p ./syms && ipsw kernel symbolicate --signatures symbolicator/kernel --json -o ./syms/ "$KC"   # names for a stripped kernel
ipsw kernel cpp "$KC" --class IOSurfaceRootUserClient --inheritance                 # C++ classes (no ObjC in kernels)
ipsw kernel syscall "$KC"                                                           # also: mach, mig, kexts
ipsw macho disass "$KC" --fileset-entry com.apple.kernel --vaddr 0xfffffe000ab90040 --count 40

シグネチャは git clone https://github.com/blacktop/symbolicator から取得します。--signatures を指定しなくても、symbolicate はシステムコール、Mach トラップ、MIG ルーチン、C++ メソッドの名前を表示します。リリースカーネルはシンボルが削除されているため、--vaddr を指定して逆アセンブルしてください。KEXT は完全なバンドル ID で指定します。短い名前はサフィックスで照合されます（IOKit は com.apple.driver.ASIOKit に解決されます）。

2 つのビルド間の変更点

ipsw dyld info --dylibs --delta "$OLD_DSC" "$NEW_DSC"          # added/removed/re-versioned dylibs
ipsw class-dump "$NEW_DSC" <DYLIB_PATH> --diff "$OLD_DSC"       # ObjC API diff (new first, --diff old)
ipsw swift-dump "$NEW_DSC" <DYLIB_PATH> --diff "$OLD_DSC" > api.diff.md   # Swift API diff (long)
ipsw kernel kexts --diff "$OLD_KC" "$NEW_KC"
ipsw sb opts --diff "$OLD_KC" "$NEW_KC"
ipsw diff "$OLD_IPSW" "$NEW_IPSW" -o ./diff/ --markdown --starts --ent   # full report (slow, local IPSWs)

パッチを探す手順については、references/diffing.md のチェックリストを参照してください。

機能：エンタイトルメントとサンドボックス

ipsw ent --fs --has com.apple.private.security.no-sandbox --file-only "$IPSW"   # no database needed
ipsw sb graph export "$KC" -O graph.json
ipsw sb query iokit-open IOSurfaceRootUserClient --graph graph.json -O json \
  | jq -r '.matches[] | select(.decision=="allow") | .profile' | sort -u

クラッシュとパニック

ipsw symbolicate panic-full-<date>.ips "$IPSW" --peek       # kernel + userspace frames, with disassembly
ipsw symbolicate crash.ips "$DSC" --unslide                  # userspace, addresses usable in static tools

ファームウェアは、ログのヘッダーに記載されたビルドと完全に一致している必要があります（head -1 <log>.ips | jq -r .os_version）。 ローカルにファームウェアがない場合、--server <URL> を指定すると ipswd シンボルサーバーに問い合わせます。ベアラートークンは IPSW_SYMBOLICATE_API_TOKEN で渡してください（references/symbolication.md を参照）。

注意点

• dyld symaddr と dyld disass --symbol は正規表現ではなく、完全一致の名前を照合します。パターンには symaddr --in <json> を使用してください。disass でシンボルを検索する際のヒントは --symbol-image です（--image は逆アセンブルする dylib 全体を選択します）。
• ObjC のインスタンスメソッド名は - で始まり、フラグとして解析されます。-- の後に指定してください（ipsw dyld symaddr "$DSC" --image <DYLIB> -- '-[UIApplication endBackgroundTask:]'）。
• dyld str はキャッシュ全体を検索し、イメージごとのフィルターはありません。
• dyld xref --all はすべてのイメージを逆アセンブルするため、非常に時間がかかります。まずは指定せずに実行してください。
• --dyld-arch を指定せずに extract --dyld を実行すると、イメージ内のすべてのアーキテクチャが抽出されます。
• class-dump --re には -V が必要です。アドレスは各メソッドの直前の行に // 0x… として出力されます。
• sb コマンドでは、-o は操作のリスト、-O は出力を指定します。
• download git と device-info では、位置引数ではなく --product／--prod を指定します。

古いリリース（ipsw 3.1.725 以前）

ipsw version を確認してください。これらのリリースでは動作が異なります。右側の回避策を使用してください。

3.1.725 以前の動作	回避策
ターミナルがない状態でプロンプトが表示されると、ステップをスキップして終了コード 0 で終了します（download appledb/ota の「Continue?」、ota extract のペイロード検索）	常に --confirm/-y を渡し、終了ステータスではなく出力を確認します
download tss --signed は署名されていない場合に終了コード 0 で終了します。--no-update はありません	出力内の Is still being signed / No longer being signed に一致するか確認します
セレクターを指定せずに download kdk を実行すると、何もせず終了コード 0 で終了します	--host、--build、--latest、または --all を渡します
dyld a2f <DSC> <ADDR> は failed to find image containing stub target で失敗します	echo <ADDR> | ipsw dyld a2f "$DSC" --in /dev/stdin
dyld webkit --diff は 2 つ目の引数を拒否します	各キャッシュに対して ipsw dyld webkit --json "$DSC" | jq -r .version を実行します
dyld info --dylibs --diff/--delta に --json がありません。--diff と kernel kexts --diff は --no-color を指定しても ANSI を出力します	--delta（Markdown）と、references/kernel.md の kexts --json の手順を使用します
class-dump --diff は @property の変更を無視します	両方のキャッシュからクラスをダンプし、diff -u を実行します
kernel symbolicate -o <dir> は <dir> が存在しない場合に失敗します	先に mkdir -p <dir> を実行します
fw exclave/dcp/c1 --info は取得したファームウェアを ./<BUILD>__<DEVICE>/ に残します	一時ディレクトリから実行します
extract --remote --kbag は各 IM4P 全体（約 150 MB）をダウンロードします	必要な容量を確保するか、必要な IM4P のみを抽出します
extract に --json-format artifacts がありません	通常の --json を使用します。--kernel の後は jq -r 'keys[0]'、--sptm/--pattern の後は .[] を使用します
ota ls --payload --json は JSON の前にバナーを出力します	jq の前に sed -n '/^\[/,$p' を実行します
dyld search objc は、あるイメージで relative method selectors エラーを出力します	無視してください。他の結果は有効です
device-info と download git は位置引数を黙って無視します	--prod / --product を使用します

リファレンスファイル

タスクに合ったものを読んでください。各ファイルの先頭には目次があります。

• references/download.md：URL の検索、リモート読み取り、ダウンロード、抽出、AEA キー、設定
• references/firmware.md：info、mount、dtree、fw コンポーネント、IMG4、AEA、OTA ペイロード
• references/dyld.md：DSC アドレス、逆アセンブル、クロスリファレンス、インポート、ソフトリンク、抽出
• references/class-dump.md：ObjC/Swift のダンプ、ヘッダー生成、API の差分
• references/macho.md：Mach-O 情報、エンタイトルメント、署名、検索、lipo/sign/patch
• references/kernel.md：カーネルシンボル、C++ クラス、システムコール/MIG、KEXT 抽出、KDK 型
• references/sandbox.md：プロファイルの逆コンパイル、機能の照会、サンドボックスの差分
• references/entitlements.md：エンタイトルメントの検索とデータベース
• references/diffing.md：リリース間の差分とパッチ調査チェックリスト
• references/symbolication.md：クラッシュとパニックのシンボリケーション
• references/device.md：USB 接続デバイス向けの idev コマンド