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

1. Python3
2. pip3
3. make
4. git

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;

1. pip3 install -r requirements.txt
2. git submodule init && git submodule update
3. make all
4. make install

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"]
  }
}

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.

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

1. First argument should be the target model identifier, such as iPod9,1.
2. The second argument should be the target build numbers seperated by a comma like so, 17A878,17A860.
3. 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

Primary script that handles most of grandmaster's functionality.

--verbose enables verbose logging.

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

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"

Quickly identify a usb device in DFU or Recovery Mode.

./grandmaster.py --scanusb

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

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

./grandmaster.py --download FIRMWARE_OUTPUT_DIRECTORY

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

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

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

./grandmaster.py --decryptimages FIRMWARE_OUTPUT_DIRECTORY

Runs all of the above operations in sequence.

./grandmaster.py --automate FIRMWARE_OUTPUT_DIRECTORY