DOCSEARCHbyAlgolia
Submit Docs

ipsw Documentation

repository·master·Indexed 25 days ago

https://github.com/blacktop/ipsw

A comprehensive command-line research framework for iOS and macOS designed for security researchers, reverse engineers, and jailbreak developers. ipsw provides tools to download, parse, and analyze Apple firmware, analyze Mach-O binaries and dyld_shared_cache, and interact with iOS devices via the idev subcommand. It also includes utilities for managing App Store Connect resources, such as certificates, device registrations, and provisioning profiles.

Tokens
140.1K
Snippets
512
Records
1K
Agent score
84%

What's inside ipsw

  1. Overview of ipsw capabilities

    master

    ipsw is a command-line research framework for Apple platforms (iOS and macOS) designed for security researchers, reverse engineers, and developers.

    Core Capabilities

    • IPSW/OTA Analysis: Download, extract, and analyze iOS firmware.
    • Binary Analysis: Mach-O parsing, ARM disassembly, and AI-powered decompilation.
    • dyld_shared_cache: Analysis and ObjC/Swift class dumping.
    • Kernel Analysis: Kernelcache parsing, KEXT extraction, and symbolication.
    • Device Interaction: Management and debugging via idev.
    • Firmware Research: Analysis of IMG4, iBoot, SEP, and co-processor firmware.
    • App Store Connect: API integration for app and certificate management.
    • AI-Powered Analysis: Integrated decompiler supporting Claude, OpenAI, Gemini, and Ollama.

  2. Dump SHSH Blobs using ipsw ssh

    master

    To dump SHSH blobs (which allows for future iOS downgrades), you must first jailbreak your iDevice and install openssh.

    1. Establish a proxy connection between your computer and the device using ipsw idev proxy.
    2. Run the ipsw ssh shsh command to connect to the device via the proxy and extract the blobs.

    Note: The proxy command requires specifying a local port (--lport) and the remote port on the device (--rport), which is typically 22 for SSH.

    ❯ ipsw idev proxy --lport 2222 --rport 22
❯ ipsw ssh shsh

  3. Install ipsw on macOS

    master

    You can install ipsw on macOS using Homebrew or MacPorts.

    Via Homebrew

    Use the following command to install the standard version. You can optionally include --with-git-delta to install git-delta for improved diff formatting.

    To install the version with Frida support (for tracing ObjC methods), use ipsw-frida instead.

    Via MacPorts

    Install the standard version using port install ipsw.

    To install a development version via MacPorts, you must first clone the blacktop ports repository and add it to your sources.conf.

  4. Run headless IDA Pro analysis in Docker

    master

    Once a licensed IDA Pro Docker image is built, you can perform headless analysis using ipsw. This is useful for generating IDB files that can later be opened in a local IDA Pro GUI.

    Prerequisite for macOS users: To support GUI applications from Docker on macOS, you must:

    1. Install XQuartz: brew install --cask xquartz.
    2. Open XQuartz and enable "Allow connections from network clients" in the Security tab.
    3. Authorize the connection: xhost + 127.0.0.1 or xhost + $(ipconfig getifaddr en0).

    Headless Command: Use the --docker and --docker-image flags to execute the analysis.

    ❯ ipsw dyld ida dyld_shared_cache_arm64e Email --delete-db --output . \
                     --docker --docker-image blacktop/idapro:8.2-pro

  5. Lookup dyld shared cache symbols using a JSON lookup file

    master

    You can perform targeted symbol lookups within a dyld_shared_cache by providing a JSON file containing regex patterns. This is useful for finding specific symbols or groups of symbols across multiple images in the cache without dumping the entire symbol table.

    1. Create a JSON file (e.g., sym_lookup.json) containing an array of objects. Each object must have a pattern (a regex string) and an image (the name of the dylib to search in).
    2. Run the ipsw dyld symaddr command with the --in flag pointing to your JSON file.

  6. List files in a remote IPSW or OTA

    master

    To see the file structure and sizes within a remote IPSW or OTA without downloading it, combine the --remote flag with the --list flag.

    ❯ ipsw info --remote https://updates.cdn-apple.com/../iPodtouch_7_13.3_17C54_Restore.ipsw --list

  8. Extract AEA PEMs and DMG files from IPSWs

    master

    You can extract AEA (Apple Encrypted Archive) PEM keys and the underlying .dmg.aea files from local or remote IPSW files using the extract command.

    To extract only the AEA1 DMG fcs-keys (PEMs):

    ipsw extract --fcs-key <device_identifier>_<version>_<build>_Restore.ipsw

    To extract the DMG and its associated AEA files:

    ipsw extract --dmg sys <ipsw_file>
    ❯ ipsw extract --fcs-key iPhone16,2_18.0_22A5307f_Restore.ipsw
❯ ipsw extract --dmg sys iPhone16,2_18.0_22A5307f_Restore.ipsw

  9. Build ipsw in an offline environment

    master

    If you need to build ipsw on a machine without internet access, you must first prepare the dependencies on an internet-connected machine.

    Steps

    1. On the connected machine:

      • Clone the repository.
      • Run go mod vendor to download all dependencies into a vendor folder.
      • Transfer the entire project directory to the offline machine.

    2. On the offline machine:

      • Run the build command using the --mod=vendor flag to instruct Go to use the local vendor directory instead of attempting to fetch from the internet.

  10. Enhance Decompiler Context

    master

    To improve the quality of the AI-generated code, provide more context to the model using the following flags:

    • --symbol <name>: Include specific symbol information.
    • --demangle: Use demangling for C++ symbols to provide clearer names.
    • --vaddr <address>: Specify a virtual address.
    • --size <bytes>: Include a specific amount of surrounding code (bytes) for context. Increasing this value provides more context but may hit token limits.

  11. Create a dedicated PostgreSQL writer role for automation

    master

    For automated tasks (like GitHub Actions), do not use the postgres owner password or the browser-exposed anon key. Instead, create a dedicated PostgreSQL login role with restricted permissions. This role should be used with direct PostgreSQL credentials stored in your CI/CD secrets.

    Required permissions include USAGE on the public schema, specific CRUD permissions on entitlement tables, and USAGE, SELECT, and UPDATE on relevant sequences.

    CREATE ROLE entitlements_writer WITH LOGIN PASSWORD '<generated-long-password>';

GRANT USAGE ON SCHEMA public TO entitlements_writer;
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE
  ipsws,
  devices,
  ipsw_devices,
  entitlement_keys,
  entitlement_values,
  paths,
  entitlements
TO entitlements_writer;

GRANT USAGE, SELECT, UPDATE ON SEQUENCE
  entitlement_keys_id_seq,
  entitlement_values_id_seq,
  paths_id_seq,
  entitlements_id_seq
TO entitlements_writer;