# Android_boot_image_editor [](https://github.com/cfig/Android_boot_image_editor/actions/workflows/main.yml) [](http://www.apache.org/licenses/LICENSE-2.0.html) A tool for reverse engineering Android ROM images. ## Requirements Make sure you have [JDK11+](https://www.oracle.com/java/technologies/downloads/#java17) and [Python3](https://www.python.org/downloads/). * Linux / WSL: `sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-17-jdk gcc g++ python3 python-is-python3 p7zip-full android-sdk-libsparse-utils erofs-utils` * Mac: `brew install lz4 xz dtc` * Windows: Install openssl and device-tree compiler with [chocolate](https://chocolatey.org/install) `choco install openssl dtc-msys2 zip vim` ## Getting Started Put your boot.img to current directory, then start gradle 'unpack' task: ```bash cp <original_boot_image> boot.img ./gradlew unpack ``` Your get the flattened kernel and /root filesystem under **./build/unzip\_boot**: build/unzip_boot/ ├── boot.json (boot image info) ├── boot.avb.json (AVB only) ├── kernel ├── second (2nd bootloader, if exists) ├── dtb (dtb, if exists) ├── dtbo (dtbo, if exists) └── root (extracted initramfs) Then you can edit the actual file contents, like rootfs or kernel. Now, pack the boot.img again ./gradlew pack You get the repacked boot.img at $(CURDIR): boot.img.signed Well done you did it! The last step is to star this repo :smile ### live demo <!--  --> <p align="center"> <img src=doc/op.gif width="615" height="492"> </p> ## Supported ROM image types | Image Type | file names | platforms | note | | --------------- |----------------------------------------------------------------|-------------|-------------------------| | boot | boot.img, init_boot.img, boot-debug.img, boot-test-harness.img | all | | |vendor boot | vendor_boot.img, vendor_boot-debug.img, vendor_kernel_boot.img | all | | | recovery | recovery.img, recovery-two-step.img | all | | | vbmeta | vbmeta.img, vbmeta_system.img etc. | all | | | dtbo | dtbo.img | linux & mac | | | dtb | *.dtb | linux & mac | | | sparse images | system.img, vendor.img, product.img etc. | linux | | | OTA payload | payload.bin | all | Windows git-bash | Please note that the boot.img MUST follows AOSP verified boot flow, either [Boot image signature](https://source.android.com/security/verifiedboot/verified-boot#signature_format) in VBoot 1.0 or [AVB HASH footer](https://android.googlesource.com/platform/external/avb/+/master/README.md#The-VBMeta-struct) (a.k.a. AVB) in VBoot 2.0. ## compatible devices | Device Model | Manufacturer | Compatible | Android Version | Note | |--------------------------------|--------------|----------------------|--------------------------|------| | Pixel 7 (panther) | Google | Y | 13 (TQ2A.230505.002) <Br>2023)| | | ADT-3 (adt3) | Askey/Google | Y | 12 (spp2.210219.010) | amlogic inside, <Br>Android TV | | Pixel 3 (blueline) | Google | Y | 12 (spp2.210219.008, <Br>2021)| | | Pixel 3 (blueline) | Google | Y | 11 (RP1A.200720.009, <Br>2020)| [more ...](doc/additional_tricks.md#pixel-3-blueline) | | Pixel 3 (blueline) | Google | Y | Q preview (qpp2.190228.023, <Br>2019)| [more ...](doc/additional_tricks.md#pixel-3-blueline) | | Redmi K30 4G (phoenix[n]) | XiaoMi | Y | 10 | [verified](https://github.com/cfig/Android_boot_image_editor/issues/17#issuecomment-817169307) by @eebssk1 | | TS10 | Topway | Y | 10 | car headunit, @mariodantas | | Pixel XL (marlin) | HTC | Y | 9.0.0 (PPR2.180905.006, <Br>Sep 2018)| [more ...](doc/additional_tricks.md#pixel-xl-marlin) | | K3 (CPH1955) | OPPO | Y for recovery.img<Br> N for boot.img | Pie | [more](doc/additional_tricks.md#k3-cph1955) | | Z18 (NX606J) | ZTE | Y | 8.1.0 | [more...](doc/additional_tricks.md#nx606j) | | Nexus 9 (volantis/flounder) | HTC | Y(with some tricks) | 7.1.1 (N9F27M, Oct 2017) | [tricks](doc/additional_tricks.md#tricks-for-nexus-9volantis)| | Nexus 5x (bullhead) | LG | Y | 6.0.0_r12 (MDA89E) | | | Moto X (2013) T-Mobile | Motorola | N | | | | X7 (PD1602_A_3.12.8) | VIVO | N | ? | [Issue 35](https://github.com/cfig/Android_boot_image_editor/issues/35) | | Realme GT Neo 3 | Realme | N | 12 | [Issue 105](https://github.com/cfig/Android_boot_image_editor/issues/105) | ## more examples <details> <summary>working with recovery.img</summary> Please remember to clean the work directory first. ```bash rm *.img cp <your_recovery_image> recovery.img ./gradlew unpack ./gradlew pack ``` </details> <details> <summary>working with vbmeta.img</summary> ```bash rm *.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack ./gradlew pack ``` </details> <details> <summary>clean workspace</summary> When you finished current work and need to clean the workspace for next image, it's a good idea to call the `clear` command: ```bash ./gradlew clear ``` </details> <details> <summary>working with boot.img and vbmeta.img</summary> If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together. ```bash rm *.img cp <your_boot_image> boot.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack ./gradlew pack ``` Your boot.img.signed and vbmeta.img.signd will be updated together, then you can flash them to your device. </details> <details> <summary>working with vendor_boot.img + vbmeta.img (Pixel 5 etc.)</summary> Most devices include hash descriptor of vendor_boot.img in vbmeta.img, so if you need to modify vendor_boot.img, you need to update vbmeta.img together. ```bash rm *.img cp <your_vendor_boot_image> vendor_boot.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack ./gradlew pack ./gradlew flash ``` Please note that to use 'gradle flash', your host machine must be connectted to your DUT with adb, and you already 'adb root'. </details> <details> <summary>How to edit device tree blob(dtb) inside vendor_boot.img</summary> If you want to edit the device-tree blob in place: ```bash cp <your_vendor_boot_image> vendor_boot.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack ==> now you can edit build/unzip_boot/dtb.dts directly ./gradlew pack ``` During unpack stage, dtb will be dumped to file `build/unzip_boot/dtb`, dts will be decompiled to `build/unzip_boot/dtb.dts`. You can edit `dtb.dts` directly, and it will be compiled to dtb duing repack stage. If you just want to replace the dtb with the one that is compiled outside this tool, please ```bash cp <your_vendor_boot_image> vendor_boot.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack rm build/unzip_boot/dtb.dts cp <your_dtb> build/unzip_boot/dtb ./gradlew pack ``` </details> <details> <summary>How to pull device tree blob(dtb) from a rooted device</summary> If you have a rooted device and want to pull /proc/device-tree ```bash touch fake.dtb ./gradlew pull ``` This tool will copy `dtc` to the target device via `adb`, and dump the dtb and dts file. Eventually you should get something like this ``` +--------+------------------------------+ | What | Where | +--------+------------------------------+ | source | /proc/device-tree | +--------+------------------------------+ | DTB | panther.dtb | +--------+------------------------------+ | DTS | build/unzip_boot/panther.dts | +--------+------------------------------+ ``` </details> <details> <summary>How to work edit device tree blob(dtb) file</summary> If you have a dtb file and want to edit its content ```bash cp <your_dtb_file> . ./gradlew unpack ``` This tool will decompile it and put the decompiled source to build/unzip_boot. ``` Unpack Summary of panther.dtb +------+------------------------------+ | What | Where | +------+------------------------------+ | DTB | panther.dtb | +------+------------------------------+ | DTS | build/unzip_boot/panther.dts | +------+------------------------------+ ``` </details> <details> <summary>working with system.img</summary> ```bash cp <your_system_image> system.img ./gradlew unpack ``` You get `system.img.unsparse`, that's a plain ext4 filesystem data. </details> <details> <summary>How to disable AVB verification</summary> The idea is to set flag=2 in main vbmeta. ```bash rm *.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack vim -u NONE -N build/unzip_boot/vbmeta.avb.json -c ":19s/0/2/g" -c ":wq" ./gradlew pack ``` Then flash vbmeta.img.signed to your device. </details> <details> <summary>How to merge init_boot.img into boot.img</summary> * unpack init_boot.img and copy out "build/unzip_boot/root". * clear workspace by `gradle clear`, then unpack boot.img * copy back the "build/unzip_boot/root" * edit build/unzip_boot/boot.json - change `ramdisk.size` to 1 - change `ramdisk.file` from "build/unzip_boot/ramdisk.img" to "build/unzip_boot/ramdisk.img.lz4" </details> <details> <summary>work with payload.bin</summary> - extract everything Usage: ``` gradle unpack ``` - extract only 1 specified partition Usage: ``` gradle unpack -Dpart=<part_name> ``` Example: ``` gradle unpack -Dpart=boot gradle unpack -Dpart=system ``` Note: "build/payload/" will be deleted before each "unpack" task </details> <details> <summary>work with apex images</summary> AOSP already has tools like apexer, deapexer, sign_apex.py, these should suffice the needs on .apex and .capex. Refer to Issue https://github.com/cfig/Android_boot_image_editor/issues/120 - For those who may be interested in apex generation flow, there is a graph here  </details> <details> <summary>How to work with vendor_dlkm.img</summary> ```bash cp <your_vendor_dlkm.img> vendor_dlkm.img cp <your_vbmeta_image> vbmeta.img ./gradlew unpack # replace your .ko ./gradlew pack ``` Then flash `vbmeta.img.signed` and `vendor_dlkm.img.signed` to the device. </details> ## boot.img layout Read [boot layout](doc/layout.md) of Android boot.img and vendor\_boot.img. Read [misc layout](doc/misc_image_layout.md) of misc\.img ## References and Acknowledgement <details> <summary>more ...</summary> Android version list https://source.android.com/source/build-numbers.html<br/> Android build-numbers https://source.android.com/setup/start/build-numbers cpio & fs\_config<br> https://android.googlesource.com/platform/system/core<br/> https://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt<br/> AVB<br/> https://android.googlesource.com/platform/external/avb/<br/> boot\_signer<br/> https://android.googlesource.com/platform/system/extras<br/> mkbootimg<br/> https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/<br/> boot header definition<br/> https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h<br/> kernel info extractor<br/> https://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py<br/> mkdtboimg<br/> https://android.googlesource.com/platform/system/libufdt/<br/> libsparse<br/> https://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/<br/> Android Nexus/Pixle factory images<br/> https://developers.google.cn/android/images<br/> </details>