4 Star 27 Fork 10

cfig / Android_boot_image_editor

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

Android_boot_image_editor

CI License

A tool for reverse engineering Android ROM images.

Requirements

Make sure you have JDK11+ and Python3.

  • 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 choco install openssl dtc-msys2

Getting Started

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

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 in VBoot 1.0 or AVB HASH footer (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 ...
Pixel 3 (blueline) Google 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

more examples

working with recovery.img

Please remember to clean the work directory first.

rm *.img
cp <your_recovery_image> recovery.img
./gradlew unpack
./gradlew pack
working with vbmeta.img
rm *.img
cp <your_vbmeta_image> 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:
./gradlew clear
working with boot.img and vbmeta.img

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.

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.
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'.

How to edit device tree blob(dtb) inside vendor_boot.img

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
How to pull device tree blob(dtb) from a rooted device

If you have a rooted device and want to pull /proc/device-tree

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

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 |
+------+------------------------------+
working with system.img
cp <your_system_image> 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.

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.

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=<part_name>

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 image
How to work with vendor_dlkm.img
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.

boot.img layout

Read boot layout of Android boot.img and vendor_boot.img. Read misc layout 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

This project is developed with products by Jetbrains.

drawing
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright {yyyy} {name of copyright owner} Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

修改Android boot.img/vbmeta.img最好的工具, 有需求/疑问/bug都可以提issue 展开 收起
Kotlin 等 6 种语言
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Kotlin
1
https://gitee.com/cfig/Android_boot_image_editor.git
git@gitee.com:cfig/Android_boot_image_editor.git
cfig
Android_boot_image_editor
Android_boot_image_editor
master

搜索帮助