{"id":13638823,"url":"https://github.com/malus-security/iextractor","last_synced_at":"2025-04-19T21:34:59.416Z","repository":{"id":27323623,"uuid":"113381902","full_name":"malus-security/iextractor","owner":"malus-security","description":"Automate extraction from iOS firmware files (.ipsw)","archived":false,"fork":false,"pushed_at":"2023-06-14T15:27:08.000Z","size":740,"stargazers_count":189,"open_issues_count":8,"forks_count":34,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-08-03T01:13:35.739Z","etag":null,"topics":["extracted-data","filesystem","firmware","hacktoberfest","ios","ipsw","kernelcache"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/malus-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-12-07T00:19:19.000Z","updated_at":"2024-06-18T20:05:31.000Z","dependencies_parsed_at":"2024-01-14T09:57:25.903Z","dependency_job_id":"82c50f26-5eee-44ed-bd1d-2cc4e9c18a86","html_url":"https://github.com/malus-security/iextractor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malus-security%2Fiextractor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malus-security%2Fiextractor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malus-security%2Fiextractor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malus-security%2Fiextractor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/malus-security","download_url":"https://codeload.github.com/malus-security/iextractor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810212,"owners_count":17206716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extracted-data","filesystem","firmware","hacktoberfest","ios","ipsw","kernelcache"],"created_at":"2024-08-02T01:00:54.247Z","updated_at":"2024-11-09T09:30:21.002Z","avatar_url":"https://github.com/malus-security.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# iExtractor: Automate Extraction from iOS Firmware Files\n\niExtractor is a collection of tools and scripts to automate data extraction from iOS firmware files (i.e. IPSW files). It runs on macOS and partially on Linux (certain tools and features only work on macOS).\n\nIPSW (*iPhone Software*) files are provided publicly by Apple for OTA (over-the-air) updates for devices running iOS. [ipsw.me](https://ipsw.me/) provides links to IPSW files by device and iOS version. Similar information is on [The iPhone Wiki](https://www.theiphonewiki.com/wiki/Firmware_Keys).\n\nIPSW files are ZIP files packing the filesystem, kernel image and other files. The filesystem image and kernel image files for iOS \u003c= 9 are encrypted; the firmware keys for most of these files are provided by the community on [The iPhone Wiki](https://www.theiphonewiki.com/wiki/Firmware_Keys). In the command output below `058-25512-331.dmg` (the largest file) is the filesystem image file and `kernelcache.release.n41` is the kernel image file or the *kernelcache*.\n\n```\n$ unzip -l iPhone5,1_9.3_13E237_Restore.ipsw\n  Length      Date    Time    Name\n---------  ---------- -----   ----\n  20660492  03-25-2016 08:55   058-25481-332.dmg\n1623427584  03-25-2016 09:03   058-25512-331.dmg\n  21491980  03-25-2016 08:55   058-25517-331.dmg\n[...]\n  10850444  03-25-2016 04:46   kernelcache.release.n41\n[...]\n```\n\niExtractor automates the unpacking, decryption and extraction of interesting data from IPSW files. Output data provided by iExtractor from IPSW files is:\n\n  * an archive of the entire filesystem content\n  * the kernelcache\n  * system dynamic library files (`.dylib`) from the unpacked dynamic library shared cache (`dyld_shared_cache`)\n  * reversed sandbox profiles\n\niExtractor is open source software released under the 3-clause BSD license.\n\n## Installation\n\niExtractor uses external tools and glue scripts. You have to run iExtractor in the Bourne-again Shell (Bash).\n\nAfter cloning the iExtractor repository, you have to clone some of the required tools as submodules:\n\n```\ngit submodule update --init tools/sandblaster\ngit submodule update --init tools/xpwn\n```\n\nIn order to install required packages use the commands below on Linux (Debian-based):\n\n```\nsudo apt-get update\nsudo apt-get install coreutils grep sed tar wget unzip build-essential\nsudo apt-get install libssl-dev python2.7 libz-dev libbz2-dev libusb-dev cmake libpng12-dev dmg2img\n```\n\nor the following commands on macOS using [Homebrew](https://brew.sh/):\n\n```\nbrew install coreutils grep wget unzip\nbrew install openssl python zlib bzip2 libpng cmake\nbrew install libusb coreutils\n```\n\nThe `dmg2img` tool and package isn't required on macOS. The `libusb` installation isn't required and it's not detected by the `xpwn` installation.\n\nThere should be similar commands on macOS if you are using [MacPorts](https://www.macports.org/). \n`coreutils` should be installed with `brew`, otherwise the scripts won't find `realpath` and `tac`.\n\n\nSome external tools in the `tools/` subfolder need to be built. You need to build:\n\n  * `vfdecrypt`\n\n    ```\n    cd tools/vfdecrypt/\n    make\n    ```\n\n  * `lzssdec`\n\n    ```\n    cd tools/lzssdec/\n    make\n    ```\n\n  * `dsc_extractor`\n\n    ```\n    cd tools/dyld/\n    make\n    ```\n\n  * `xpwn`\n\n    ```\n    cd tools/xpwn/\n    mkdir builddir\n    cd builddir/\n    cmake ..\n    make\n    ```\n\n    Use `builddir/` for the folder name as it is hardcoded inside scripts.\n\n  * `sandblaster` dependencies (only available on macOS):\n\n    ```\n    cd tools/sandblaster\n    git submodule update --init tools/sandbox_toolkit\n    # while in tools/sandblaster/\n    cd tools/sandbox_toolkit/extract_sbops\n    make\n    # while in tools/sandblaster/\n    cd tools/sandbox_toolkit/extract_sbprofiles\n    make\n    ```\n\n## Setup\n\nBefore running iExtractor scripts you need to create a `config` file in the root of the repository. You can make a copy of the `config.sample` file and update that:\n\n```\ncp config.sample config\n```\n\nIn the `config.sample` file downloaded and extracted data is stored in subfolders in the current directory (`STORE=.`). You can update the `STORE` variable to a different folder where you want the data stored.\n\nYou then need to create the storage subfolders. Assuming `STORE` points to the current directory (`.`), run the commands:\n\n```\nmkdir ipsw\nmkdir out\n```\n\nThe `ipsw/` folder stores downloaded IPSW files and the `out/` folder stores data extracted and processed by iExtractor. You will look in the `out/` folder for interesting data and copy data from/to the `out/` folder if you want to extract/process part of it on another system.\n\n## Usage\n\nIn order to do all processing for a given firmware, use the `run_all` wrapper script. You need to pass it a firmware id, i.e. one of the file names in the `firmware-metadata/` subfolder:\n\n```\n./run_all iPhone5,1_9.3_13E237\n```\n\nIf you want to do all steps except the lengthier (and more storage hungry) steps of packing the filesystem and extracting the system dynamic libraries files, you can use the `run_no_pack_fs_no_dyld` wrapper script:\n\n```\n./run_no_pack_fs_no_dyld iPhone5,1_9.3_13E237\n```\n\nSimilarly, if you downloaded and unpacked IPSW files elsewhere (on another system), you copied the interesting extracted data and you want to work on that data without going into the download and unpack steps, you can use the `run_no_download_no_unpack` script:\n\n```\n./run_no_download_no_unpack iPhone5,1_9.3_13E237\n```\n\nYou can run a single step by going to the `scripts/` subfolder and running a script there:\n\n```\ncd scripts/\n./decrypt_kernel iPhone5,1_9.3_13E237\n```\n\nOr you can create your own custom script based on `run_all` or `run_no_pack_no_fs_no_dyld`. Read more below.\n\nIf you want to check all files and folders corresponding to a given firmware ID, use the `list_files` wrapper script. It gives you information about the existence and basic properties of those files (IPSW input file, kernelcache, reversed sandbox profiles etc.):\n\n```\n./list_files iPhone5,1_9.3_13E237\n```\n\nSimilarly, if you want to remove all or some of the files and folders corresponding to a givn firmware ID, use the `clean.sample` script or create a script starting from that. The `clean.sample` script uses `rm -i` (i.e. interactive run) to prevent you from removing a file by mistake:\n\n```\n./clean.sample iPhone5,1_9.3_13E237\n```\n\n## Internals\n\nExternal tools are located in the `tools/` subfolder. They are to be run through two layers of scripts: a lower-layer set of scripts located in the `bin/` subfolder and a higher-layer set of scripts in the `scripts/` subfolder. The scripts in the `scripts/` subfolder are the ones you will work with.\n\nEach higher-layer script in the `scripts/` subfolder does a specific action: unpacking an IPSW file, extracting the dynamic library shared cache, extracting the sandbox extension etc.\n\nEach script uses a firmware id as an argument; supported firmware ids are files in the `firmware-metadata/` subfolder; each file in the `firmware-metadata/` subfolder uses the firmware id as a name and stores in plain text firmware-related information required by scripts. You can add support for a new firmware, by creating a file in the `firmware-metadata/` subfolder named after the firmware id and filling it with the required information (download URL and decryption keys) similar to existing files.\n\nYou can run each script in the `scripts/` subfolder either by itself, or by tying scripts together in a wrapper script, such as `run_all`, `run_no_pack_fs`, `run_no_pack_fs_no_dyld`, `run_no_download_no_unpack` and `run_sandblaster`. For debugging purposes or if you want to work on the lower layers, use the scripts in the `bin/` subfolder.\n\nWhen running a script, if previous output data exists it will prompt if you want to overwrite that. That is why, in a wrapper script, you would usually provide an `N` (for `no`) to the standard input of a script:\n\n```\nyes N | ./decrypt_kernel \"$firmware_id\"\n```\n\nYou can start from existing scripts to create new ones and extend iExtractor to extract and process other interesting data from IPSW files.\n\n## Documentation\n\nRead in-depth information about iExtractor on [the wiki](https://github.com/malus-security/iExtractor/wiki).\n\n## Community\n\nJoin us on [Discord](https://discord.gg/m3gjuyHYw9) for live discussions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalus-security%2Fiextractor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmalus-security%2Fiextractor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalus-security%2Fiextractor/lists"}