A tool for reverse engineering Android ROM images.
Linux: sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-17-jdk gcc g++ python3 python-is-python3 p7zip-full
Mac: brew install lz4 xz dtc
Mac: Make sure you have JDK9+
properly installed. JDK 17 is recommended.
Windows Subsystem for Linux(WSL): sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-17-jdk gcc g++ python
Windows: Make sure you have python3
, JDK9+
and openssl
properly installed.
An easy way is to install Anaconda and Oracle JDK 17, then run the program under anaconda PowerShell.
Or install them with chocolate: choco install openssl dtc-msys2
Put your boot.img to current directory, then start gradle 'unpack' task:
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
Image Type | file names | platforms | note |
---|---|---|---|
boot | boot.img, init_boot.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 | |
sparse images | system.img, vendor.img, product.img etc. | linux & mac | need hacking mode* |
OTA payload | payload.bin | linux & mac |
Please note that the boot.img MUST follows AOSP verified boot flow, either Boot image signature in VBoot 1.0 or AVB HASH footer (a.k.a. AVB) in VBoot 2.0.
hacking mode*:
Open build.gradle.kts, Line #8, change
val bHackingMode = false
to
val bHackingMode = true
This will enable c++ modules, which is necessary for working with sparse images.
Device Model | Manufacturer | Compatible | Android Version | Note |
---|---|---|---|---|
ADT-3 (adt3) | Askey/Google | Y | 12 (spp2.210219.010) | amlogic inside, Android TV |
Pixel 3 (blueline) | Y | 12 (spp2.210219.008, 2021) |
||
Pixel 3 (blueline) | Y | 11 (RP1A.200720.009, 2020) |
more ... | |
Pixel 3 (blueline) | Y | Q preview (qpp2.190228.023, 2019) |
more ... | |
Redmi K30 4G (phoenix[n]) | XiaoMi | Y | 10 | verified by @eebssk1 |
TS10 | Topway | Y | 10 | car headunit, @mariodantas |
Pixel XL (marlin) | HTC | Y | 9.0.0 (PPR2.180905.006, Sep 2018) |
more ... |
K3 (CPH1955) | OPPO | Y for recovery.img N for boot.img |
Pie | more |
Z18 (NX606J) | ZTE | Y | 8.1.0 | more... |
Nexus 9 (volantis/flounder) | HTC | Y(with some tricks) | 7.1.1 (N9F27M, Oct 2017) | tricks |
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 |
Realme GT Neo 3 | Realme | N | 12 | Issue 105 |
Please remember to clean the work directory first.
rm *.img
cp <your_recovery_image> recovery.img
./gradlew unpack
./gradlew pack
rm *.img
cp <your_vbmeta_image> vbmeta.img
./gradlew unpack
./gradlew pack
./gradlew clear
If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.
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.
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'.
If you want to edit the device-tree blob in place:
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
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
First enable hacking mode by setting bHackingMode = true
in file build.gradle.kts
, then
cp <your_system_image> system.img
./gradlew unpack
You get system.img.unsparse
, that's a plain ext4 filesystem data.
The idea is to set flag=2 in main vbmeta.
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.
gradle clear
, then unpack boot.imgramdisk.size
to 1ramdisk.file
from "build/unzip_boot/ramdisk.img" to "build/unzip_boot/ramdisk.img.lz4"Read boot layout of Android boot.img and vendor_boot.img. Read miac layout of misc.img
Android version list https://source.android.com/source/build-numbers.html
Android build-numbers https://source.android.com/setup/start/build-numbers
cpio & fs_config
https://android.googlesource.com/platform/system/core
https://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt
AVB
https://android.googlesource.com/platform/external/avb/
boot_signer
https://android.googlesource.com/platform/system/extras
mkbootimg
https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/
boot header definition
https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h
kernel info extractor
https://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py
mkdtboimg
https://android.googlesource.com/platform/system/libufdt/
libsparse
https://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/
Android Nexus/Pixle factory images
https://developers.google.cn/android/images
This project is developed with products by Jetbrains.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。