{"id":13482209,"url":"https://github.com/cfig/Android_boot_image_editor","last_synced_at":"2025-03-27T12:32:39.765Z","repository":{"id":38751841,"uuid":"56238465","full_name":"cfig/Android_boot_image_editor","owner":"cfig","description":"Parsing and re-packing Android boot.img/vbmeta.img/payload.bin, supporting Android 15","archived":false,"fork":false,"pushed_at":"2025-02-10T07:01:44.000Z","size":45020,"stargazers_count":1112,"open_issues_count":25,"forks_count":245,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-03-23T00:02:09.609Z","etag":null,"topics":["android-boot","avb","mkboot","mkbootimg","recovery","unpack","vbmeta","vendor-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-14T13:12:18.000Z","updated_at":"2025-03-22T10:13:16.000Z","dependencies_parsed_at":"2023-12-26T11:30:23.177Z","dependency_job_id":"37ddbce1-bc86-422e-9753-4c4e438cc968","html_url":"https://github.com/cfig/Android_boot_image_editor","commit_stats":{"total_commits":268,"total_committers":13,"mean_commits":"20.615384615384617","dds":0.05970149253731338,"last_synced_commit":"fc67140c2ddfc286b0121b49a5de1ebe0f1e40df"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfig%2FAndroid_boot_image_editor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfig%2FAndroid_boot_image_editor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfig%2FAndroid_boot_image_editor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfig%2FAndroid_boot_image_editor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfig","download_url":"https://codeload.github.com/cfig/Android_boot_image_editor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245845392,"owners_count":20681905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-boot","avb","mkboot","mkbootimg","recovery","unpack","vbmeta","vendor-boot"],"created_at":"2024-07-31T17:00:59.949Z","updated_at":"2025-03-27T12:32:37.592Z","avatar_url":"https://github.com/cfig.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Android_boot_image_editor\n[![CI](https://github.com/cfig/Android_boot_image_editor/actions/workflows/main.yml/badge.svg)](https://github.com/cfig/Android_boot_image_editor/actions/workflows/main.yml)\n[![License](http://img.shields.io/:license-apache-blue.svg?style=flat-square)](http://www.apache.org/licenses/LICENSE-2.0.html)\n\nA tool for reverse engineering Android ROM images.\n\n##  Requirements\nMake sure you have [JDK11+](https://www.oracle.com/java/technologies/downloads/#java17) and [Python3](https://www.python.org/downloads/).\n\n* 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`\n\n* Mac: `brew install lz4 xz dtc`\n\n* Windows: Install openssl and device-tree compiler with [chocolate](https://chocolatey.org/install)\n`choco install openssl dtc-msys2 zip vim`\n\n## Getting Started\nPut your boot.img to current directory, then start gradle 'unpack' task:\n\n```bash\ncp \u003coriginal_boot_image\u003e boot.img\n./gradlew unpack\n```\n\nYour get the flattened kernel and /root filesystem under **./build/unzip\\_boot**:\n\n    build/unzip_boot/\n    ├── boot.json     (boot image info)\n    ├── boot.avb.json (AVB only)\n    ├── kernel\n    ├── second        (2nd bootloader, if exists)\n    ├── dtb           (dtb, if exists)\n    ├── dtbo          (dtbo, if exists)\n    └── root          (extracted initramfs)\n\nThen you can edit the actual file contents, like rootfs or kernel.\nNow, pack the boot.img again\n\n    ./gradlew pack\n\nYou get the repacked boot.img at $(CURDIR):\n\n    boot.img.signed\n\nWell done you did it! The last step is to star this repo :smile\n\n\n### live demo\n\u003c!-- ![](doc/op.gif) --\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=doc/op.gif width=\"615\" height=\"492\"\u003e\n\u003c/p\u003e\n\n## Supported ROM image types\n\n| Image Type      | file names                                                     | platforms   | note                    |\n| --------------- |----------------------------------------------------------------|-------------|-------------------------|\n| boot            | boot.img, init_boot.img, boot-debug.img, boot-test-harness.img | all         |                         |\n|vendor boot      | vendor_boot.img, vendor_boot-debug.img, vendor_kernel_boot.img | all         |                         |\n| recovery        | recovery.img, recovery-two-step.img                            | all         |                         |\n| vbmeta          | vbmeta.img, vbmeta_system.img etc.                             | all         |                         |\n| dtbo            | dtbo.img                                                       | linux \u0026 mac |                         |\n| dtb             | *.dtb                                                          | linux \u0026 mac |                         |\n| sparse images   | system.img, vendor.img, product.img etc.                       | linux       |                         |\n| OTA payload     | payload.bin                                                    | all         | Windows git-bash        |\n\nPlease 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.\n\n## compatible devices\n\n| Device Model                   | Manufacturer | Compatible           | Android Version          | Note |\n|--------------------------------|--------------|----------------------|--------------------------|------|\n| Pixel 7 (panther)              | Google       | Y                    | 13 (TQ2A.230505.002) \u003cBr\u003e2023)| |\n| ADT-3 (adt3)                   | Askey/Google | Y                    | 12 (spp2.210219.010)     | amlogic inside, \u003cBr\u003eAndroid TV |\n| Pixel 3 (blueline)             | Google       | Y                    | 12 (spp2.210219.008, \u003cBr\u003e2021)| |\n| Pixel 3 (blueline)             | Google       | Y                    | 11 (RP1A.200720.009, \u003cBr\u003e2020)| [more ...](doc/additional_tricks.md#pixel-3-blueline) |\n| Pixel 3 (blueline)             | Google       | Y                    | Q preview (qpp2.190228.023, \u003cBr\u003e2019)| [more ...](doc/additional_tricks.md#pixel-3-blueline) |\n| Redmi K30 4G (phoenix[n])      | XiaoMi       | Y                    | 10 | [verified](https://github.com/cfig/Android_boot_image_editor/issues/17#issuecomment-817169307) by @eebssk1 |\n| TS10                           | Topway       | Y                    | 10                       | car headunit, @mariodantas |\n| Pixel XL (marlin)              | HTC          | Y                    | 9.0.0 (PPR2.180905.006, \u003cBr\u003eSep 2018)| [more ...](doc/additional_tricks.md#pixel-xl-marlin) |\n| K3 (CPH1955)                   | OPPO         | Y for recovery.img\u003cBr\u003e N for boot.img  | Pie    | [more](doc/additional_tricks.md#k3-cph1955) |\n| Z18 (NX606J)                   | ZTE          | Y                    | 8.1.0                    | [more...](doc/additional_tricks.md#nx606j) |\n| Nexus 9 (volantis/flounder)    | HTC          | Y(with some tricks)  | 7.1.1 (N9F27M, Oct 2017) | [tricks](doc/additional_tricks.md#tricks-for-nexus-9volantis)|\n| Nexus 5x (bullhead)            | LG           | Y                    | 6.0.0_r12 (MDA89E)       |      |\n| Moto X (2013) T-Mobile         | Motorola     | N                    |                          |      |\n| X7 (PD1602_A_3.12.8)           | VIVO         | N                    | ?                        | [Issue 35](https://github.com/cfig/Android_boot_image_editor/issues/35) |\n| Realme GT Neo 3                | Realme       | N                    | 12                       | [Issue 105](https://github.com/cfig/Android_boot_image_editor/issues/105) |\n\n## more examples\n\u003cdetails\u003e\n  \u003csummary\u003eworking with recovery.img\u003c/summary\u003e\n\nPlease remember to clean the work directory first.\n\n```bash\nrm *.img\ncp \u003cyour_recovery_image\u003e recovery.img\n./gradlew unpack\n./gradlew pack\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eworking with vbmeta.img\u003c/summary\u003e\n\n\n```bash\nrm *.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\n./gradlew pack\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eclean workspace\u003c/summary\u003e\nWhen you finished current work and need to clean the workspace for next image, it's a good idea to call the `clear` command:\n\n```bash\n./gradlew clear\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eworking with boot.img and vbmeta.img\u003c/summary\u003e\n\nIf your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.\n\n```bash\nrm *.img\ncp \u003cyour_boot_image\u003e boot.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\n./gradlew pack\n```\nYour boot.img.signed and vbmeta.img.signd will be updated together, then you can flash them to your device.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eworking with vendor_boot.img + vbmeta.img (Pixel 5 etc.)\u003c/summary\u003e\nMost 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.\n\n```bash\nrm *.img\ncp \u003cyour_vendor_boot_image\u003e vendor_boot.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\n./gradlew pack\n./gradlew flash\n```\n\nPlease note that to use 'gradle flash', your host machine must be connectted to your DUT with adb, and you already 'adb root'.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow to edit device tree blob(dtb) inside vendor_boot.img\u003c/summary\u003e\n\nIf you want to edit the device-tree blob in place:\n\n```bash\ncp \u003cyour_vendor_boot_image\u003e vendor_boot.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\n==\u003e now you can edit build/unzip_boot/dtb.dts directly\n./gradlew pack\n```\n\nDuring unpack stage, dtb will be dumped to file `build/unzip_boot/dtb`, dts will be decompiled to `build/unzip_boot/dtb.dts`.\nYou can edit `dtb.dts` directly, and it will be compiled to dtb duing repack stage.\n\nIf you just want to replace the dtb with the one that is compiled outside this tool, please\n\n```bash\ncp \u003cyour_vendor_boot_image\u003e vendor_boot.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\nrm build/unzip_boot/dtb.dts\ncp \u003cyour_dtb\u003e build/unzip_boot/dtb\n./gradlew pack\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n  \u003csummary\u003eHow to pull device tree blob(dtb) from a rooted device\u003c/summary\u003e\n\nIf you have a rooted device and want to pull /proc/device-tree\n```bash\ntouch fake.dtb\n./gradlew pull\n```\nThis tool will copy `dtc` to the target device via `adb`, and dump the dtb and dts file. Eventually you should get something like this\n```\n+--------+------------------------------+\n|  What  |            Where             |\n+--------+------------------------------+\n| source | /proc/device-tree            |\n+--------+------------------------------+\n| DTB    | panther.dtb                  |\n+--------+------------------------------+\n| DTS    | build/unzip_boot/panther.dts |\n+--------+------------------------------+\n\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n  \u003csummary\u003eHow to work edit device tree blob(dtb) file\u003c/summary\u003e\n\nIf you have a dtb file and want to edit its content\n```bash\ncp \u003cyour_dtb_file\u003e .\n./gradlew unpack\n```\nThis tool will decompile it and put the decompiled source to build/unzip_boot.\n\n```\n                        Unpack Summary of panther.dtb\n+------+------------------------------+\n| What |            Where             |\n+------+------------------------------+\n| DTB  | panther.dtb                  |\n+------+------------------------------+\n| DTS  | build/unzip_boot/panther.dts |\n+------+------------------------------+\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eworking with system.img\u003c/summary\u003e\n\n```bash\ncp \u003cyour_system_image\u003e system.img\n./gradlew unpack\n```\nYou get `system.img.unsparse`, that's a plain ext4 filesystem data.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow to disable AVB verification\u003c/summary\u003e\n\nThe idea is to set flag=2 in main vbmeta.\n\n```bash\nrm *.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\nvim -u NONE -N build/unzip_boot/vbmeta.avb.json  -c \":19s/0/2/g\" -c \":wq\"\n./gradlew pack\n```\nThen flash vbmeta.img.signed to your device.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n  \u003csummary\u003eHow to merge init_boot.img into boot.img\u003c/summary\u003e\n\n* unpack init_boot.img and copy out \"build/unzip_boot/root\".\n* clear workspace by `gradle clear`, then unpack boot.img\n* copy back the \"build/unzip_boot/root\"\n* edit build/unzip_boot/boot.json\n- change `ramdisk.size` to 1\n- change `ramdisk.file` from \"build/unzip_boot/ramdisk.img\" to \"build/unzip_boot/ramdisk.img.lz4\"\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n  \u003csummary\u003ework with payload.bin\u003c/summary\u003e\n\n- extract everything\n\nUsage:\n```\n    gradle unpack\n```\n\n- extract only 1 specified partition\nUsage:\n```\n    gradle unpack -Dpart=\u003cpart_name\u003e\n```\nExample:\n```\n    gradle unpack -Dpart=boot\n    gradle unpack -Dpart=system\n```\n\nNote:\n    \"build/payload/\" will be deleted before each \"unpack\" task\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\n  \u003csummary\u003ework with apex images\u003c/summary\u003e\n\nAOSP already has tools like apexer, deapexer, sign_apex.py, these should suffice the needs on .apex and .capex.\nRefer to Issue https://github.com/cfig/Android_boot_image_editor/issues/120\n\n- For those who may be interested in apex generation flow, there is a graph here\n![image](doc/apexer_generate_flow.png)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow to work with vendor_dlkm.img\u003c/summary\u003e\n\n```bash\ncp \u003cyour_vendor_dlkm.img\u003e vendor_dlkm.img\ncp \u003cyour_vbmeta_image\u003e vbmeta.img\n./gradlew unpack\n# replace your .ko\n./gradlew pack\n```\nThen flash `vbmeta.img.signed` and `vendor_dlkm.img.signed` to the device.\n\n\u003c/details\u003e\n\n## boot.img layout\nRead [boot layout](doc/layout.md) of Android boot.img and vendor\\_boot.img.\nRead [misc layout](doc/misc_image_layout.md) of misc\\.img\n\n## References and Acknowledgement\n\u003cdetails\u003e\n  \u003csummary\u003emore ...\u003c/summary\u003e\n\nAndroid version list https://source.android.com/source/build-numbers.html\u003cbr/\u003e\nAndroid build-numbers https://source.android.com/setup/start/build-numbers\n\ncpio \u0026 fs\\_config\u003cbr\u003e\nhttps://android.googlesource.com/platform/system/core\u003cbr/\u003e\nhttps://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt\u003cbr/\u003e\nAVB\u003cbr/\u003e\nhttps://android.googlesource.com/platform/external/avb/\u003cbr/\u003e\nboot\\_signer\u003cbr/\u003e\nhttps://android.googlesource.com/platform/system/extras\u003cbr/\u003e\nmkbootimg\u003cbr/\u003e\nhttps://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/\u003cbr/\u003e\nboot header definition\u003cbr/\u003e\nhttps://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h\u003cbr/\u003e\nkernel info extractor\u003cbr/\u003e\nhttps://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py\u003cbr/\u003e\nmkdtboimg\u003cbr/\u003e\nhttps://android.googlesource.com/platform/system/libufdt/\u003cbr/\u003e\nlibsparse\u003cbr/\u003e\nhttps://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/\u003cbr/\u003e\nAndroid Nexus/Pixle factory images\u003cbr/\u003e\nhttps://developers.google.cn/android/images\u003cbr/\u003e\n\n\u003c/details\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfig%2FAndroid_boot_image_editor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfig%2FAndroid_boot_image_editor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfig%2FAndroid_boot_image_editor/lists"}