Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cfig/Android_boot_image_editor
Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 15
https://github.com/cfig/Android_boot_image_editor
android-boot avb mkboot mkbootimg recovery unpack vbmeta vendor-boot
Last synced: 3 months ago
JSON representation
Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 15
- Host: GitHub
- URL: https://github.com/cfig/Android_boot_image_editor
- Owner: cfig
- License: apache-2.0
- Created: 2016-04-14T13:12:18.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-28T15:26:15.000Z (3 months ago)
- Last Synced: 2024-10-28T17:43:10.408Z (3 months ago)
- Topics: android-boot, avb, mkboot, mkbootimg, recovery, unpack, vbmeta, vendor-boot
- Language: Java
- Homepage:
- Size: 42.9 MB
- Stars: 1,048
- Watchers: 35
- Forks: 235
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-rainmana - cfig/Android_boot_image_editor - Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 15 (Java)
README
# 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 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
## 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)
2023)| |
| ADT-3 (adt3) | Askey/Google | Y | 12 (spp2.210219.010) | amlogic inside,
Android TV |
| Pixel 3 (blueline) | Google | Y | 12 (spp2.210219.008,
2021)| |
| Pixel 3 (blueline) | Google | Y | 11 (RP1A.200720.009,
2020)| [more ...](doc/additional_tricks.md#pixel-3-blueline) |
| Pixel 3 (blueline) | Google | Y | Q preview (qpp2.190228.023,
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,
Sep 2018)| [more ...](doc/additional_tricks.md#pixel-xl-marlin) |
| K3 (CPH1955) | OPPO | Y for recovery.img
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
working with recovery.img
Please remember to clean the work directory first.
```bash
rm *.img
cp recovery.img
./gradlew unpack
./gradlew pack
```
working with vbmeta.img
```bash
rm *.img
cp vbmeta.img
./gradlew unpack
./gradlew pack
```
clean workspace
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
```
working with boot.img and vbmeta.img
If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.
```bash
rm *.img
cp boot.img
cp 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.
working with vendor_boot.img + vbmeta.img (Pixel 5 etc.)
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 vendor_boot.img
cp 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'.
How to edit device tree blob(dtb) inside vendor_boot.img
If you want to edit the device-tree blob in place:
```bash
cp vendor_boot.img
cp 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 vendor_boot.img
cp vbmeta.img
./gradlew unpack
rm build/unzip_boot/dtb.dts
cp build/unzip_boot/dtb
./gradlew pack
```
How to pull device tree blob(dtb) from a rooted device
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 |
+--------+------------------------------+
```
How to work edit device tree blob(dtb) file
If you have a dtb file and want to edit its content
```bash
cp .
./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 |
+------+------------------------------+
```
working with system.img
```bash
cp system.img
./gradlew unpack
```
You get `system.img.unsparse`, that's a plain ext4 filesystem data.
How to disable AVB verification
The idea is to set flag=2 in main vbmeta.
```bash
rm *.img
cp 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.
How to merge init_boot.img into boot.img
* 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"
work with payload.bin
- extract everything
Usage:
```
gradle unpack
```
- extract only 1 specified partition
Usage:
```
gradle unpack -Dpart=
```
Example:
```
gradle unpack -Dpart=boot
gradle unpack -Dpart=system
```
Note:
"build/payload/" will be deleted before each "unpack" task
work with apex images
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
How to work with vendor_dlkm.img
```bash
cp vendor_dlkm.img
cp vbmeta.img
./gradlew unpack
# replace your .ko
./gradlew pack
```
Then flash `vbmeta.img.signed` and `vendor_dlkm.img.signed` to the device.
## 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
more ...
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