grandmaster

A simplistic python wrapper for img4lib, ipwndfu, and partialZipBrowser that assists in automating iOS firmware decryption.

Prerequisites

Python3
pip3
make
git

Installing

Begin by running git clone https://github.com/GuardianFirewall/grandmaster.git in a directory convenient to you. cd into the grandmaster directory and prepare it by running the following commands;

pip3 install -r requirements.txt
git submodule init && git submodule update
make all
make install

Grandmaster Configuration

gm.config will serve as a configuration file along with acting as a storage file for KBAGs and IVKeys for a bundle. Structure for the config file is as follows.

{
  "device": "",
  "download": "IPSW_URL",
  "build": "",
  "images": {
    "Firmware/all_flash/LLB.XXXX.RELEASE.im4p": "DECRYPTION_KEY",
    "Firmware/all_flash/iBoot.XXXX.RELEASE.im4p": "DECRYPTION_KEY",
    "Firmware/dfu/iBEC.XXXX.RELEASE.im4p": "DECRYPTION_KEY",
    "Firmware/dfu/iBSS.XXXX.RELEASE.im4p": "DECRYPTION_KEY"
  },
  "kbags": {
    "Firmware/all_flash/LLB.XXXX.RELEASE.im4p": ["KBAG_PRODUCTION", "KBAG_DEVELOPMENT"],
    "Firmware/all_flash/iBoot.XXXX.RELEASE.im4p": ["KBAG_PRODUCTION", "KBAG_DEVELOPMENT"],
    "Firmware/dfu/iBEC.XXXX.RELEASE.im4p": ["KBAG_PRODUCTION", "KBAG_DEVELOPMENT"],
    "Firmware/dfu/iBSS.XXXX.RELEASE.im4p": ["KBAG_PRODUCTION", "KBAG_DEVELOPMENT"]
  }
}

Config Specifiers

device is the device (aka device identifier), ex. iPod9,1 or iPhone10,2.

build is the iOS firmware build number, ex. 17A860 for iOS 13.1.2 or 16G77 for iOS 12.4.

iosver is the iOS firmware version number, ex. 13.1.2, 12.4, 9.2.1, etc.

images holds a dictionary of firmware images, where each key is the firmware path (as it is in the IPSW) and the dictionary value is the decryption IVKey string for that firmware image.

kbags is similar to images but instead it specifies the extracted KBAGs. It holds a dictionary of firmware images, where each key is the firmware path (as it is in the IPSW) and the dictionary value is an array that holds the KBAG values.

`multi_grandmaster.py`

Super simple script to help further automate grandmaster into full "batch processing" mode.

First argument should be the target model identifier, such as iPod9,1.
The second argument should be the target build numbers seperated by a comma like so, 17A878,17A860.
Our third and final argument should be the directory where you'd like grandmaster to output files into.

./multi_grandmaster.py iPod9,1 17A878,17A860 examples

`grandmaster.py`

Primary script that handles most of grandmaster's functionality.

Additional Arguments

--verbose enables verbose logging.

--overwrite automatically overwrite a gm.config if it already exists during --generate

Foreman API Tokens

The Foreman keystore server can be configured for either authenticated use by using the primary branch or with no authentication using the 'noauth' branch, if using a Foreman server configured with authentication you will need to specify a FOREMAN_TOKEN for Grandmaster to use in requests, which can be generated by the Foreman server admin.

Specify a token for Foreman server requests by adding the environment variable FOREMAN_TOKEN. An alternate Foreman host can be specified using the FOREMAN_HOST variable.

FOREMAN_TOKEN="GENERATED_FOREMAN_TOKEN" ./grandmaster.py --automate FIRMWARE_OUTPUT_DIRECTORY

Or simply add the following to your shell profile.

export FOREMAN_TOKEN="GENERATED_FOREMAN_TOKEN"

Scan for USB devices

Quickly identify a usb device in DFU or Recovery Mode.

./grandmaster.py --scanusb

Generate a `gm.config`

Generate a gm.config file by running the command ./grandmaster.py --generate FIRMWARE_OUTPUT_DIRECTORY along with --model or --boardconfig and --build or --iosver.

./grandmaster.py --generate FIRMWARE_OUTPUT_DIRECTORY --model iPod9,1 --build 17A878
./grandmaster.py --generate FIRMWARE_OUTPUT_DIRECTORY --boardconfig n112ap --iosver 13.1.3

Download Firmware Images

Downloads each firmware defined in gm.config's images dictionary.

./grandmaster.py --download FIRMWARE_OUTPUT_DIRECTORY

Extract KBAGs

Extracts KBAGs for each firmware defined in gm.config's images dictionary and stashes them in the kbags dictionary for later use with --decryptkbags.

./grandmaster.py --extractkbags FIRMWARE_OUTPUT_DIRECTORY

Decrypt KBAGs

Decrypts KBAGs for each firmware defined in gm.config's images dictionary and stashes the resulting IVKey in the images dictionary for later use with --decryptimages. Optionally, --devkbags uses KBAG_DEVELOPMENT for KBAG decryption.

./grandmaster.py --decryptkbags FIRMWARE_OUTPUT_DIRECTORY

Decrypt Firmware Images

Decrypts KBAGs for each firmware defined in gm.config's images dictionary

./grandmaster.py --decryptimages FIRMWARE_OUTPUT_DIRECTORY

Automation

Runs all of the above operations in sequence.

./grandmaster.py --automate FIRMWARE_OUTPUT_DIRECTORY