Files
reverse-engineering-anything/docs/android-boot-image.md
T
Matt Van Hornandgensokyo-dev a88c0a5554 feat(artifacts): inspect Android boot image components
Inventory Android boot and vendor_boot images through shared artifact workflows. Preserve parser failure kinds and bounded stored-component extraction.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 12:08:42 +00:00

5.5 KiB

Android boot and vendor_boot images

inspect-artifact and extract-artifact recognize ANDROID! boot images (header versions 0 through 4) and VNDRBOOT vendor_boot images (header versions 3 and 4) regardless of filename. They read local stored bytes without booting, executing, decompressing, or modifying the image.

The same header facts and artifact reader serve CLI and MCP. The root is an archive with unknown executable architecture. ANDROID! covers boot, init_boot, and recovery images; the header does not record which role the file had.

Header facts

Versions 0 through 2 store a page size from 2048 through 65536, a power of two. The header occupies the first page. Kernel, ramdisk, and second stage follow, each padded up to the next page. Version 1 adds a recovery DTBO at a page-aligned file offset. Version 2 adds a DTB after that offset. The 32-byte header digest is recorded and not checked.

Versions 3 and 4 use a fixed 4096-byte page. The kernel and ramdisk follow the header page. Version 4 can append a signature. That signature is a stored range with a size. It is not verified.

Vendor_boot versions 3 and 4 record the kernel, ramdisk, and tags load addresses, the board name, a 2048-byte command line, the vendor ramdisk, and a DTB. Version 3 exposes one vendor_ramdisk child when that section is non-empty. Version 4 exposes each ramdisk table entry as vendor_ramdisk/<name>, then the DTB, then bootconfig. The table itself is not a child. Each entry is at least the 108-byte v4 structure: size, offset, type, a 32-byte name, and 16 board-id words. A larger entry_size keeps those fields and leaves the trailing bytes undecoded. Entry names that are empty, ., .., or contain / become ramdisk-<index>. A repeated name gains -<index>. If that name is already used, the suffix gains another number until the path is unique.

OS version and security patch level are decoded from the packed os_version word. A month outside 1 through 12 leaves the patch level null and keeps the raw word. Vendor_boot has no OS version field.

Command line, board name, and vendor ramdisk names are target-derived and untrusted. Versions 0 through 2 concatenate cmdline and extra_cmdline with no separator. Versions 3 and 4 store one combined command line. Invalid UTF-8 stays null and the raw field bytes are kept as hex.

Children

Non-empty components become children:

Path Role
kernel kernel
ramdisk ramdisk
second second stage
recovery_dtbo recovery DTBO
dtb devicetree blob
vendor_ramdisk version 3 vendor ramdisk section
vendor_ramdisk/<name> version 4 ramdisk table entry
bootconfig bootconfig
signature version 4 boot signature

A child whose first bytes match gzip (1f 8b), an lz4 frame (04 22 4d 18), legacy lz4 (02 21 4c 18), or zstd (28 b5 2f fd) records that compression. Other prefixes stay unknown, which does not prove the bytes are uncompressed. Nothing in this reader decompresses a payload. A kernel that starts with the ELF magic is classified as elf by the existing content check. A dtb child stays a file; extract it and run inspect-devicetree on the extracted file.

When bytes follow the page-aligned image, the last 64 bytes are compared with the AVBf footer. A matching footer records its version, original image size, and vbmeta offset and size. The footer and vbmeta are not children and are not verified. A shorter tail, or a tail that does not start with AVBf, is reported as undecoded trailing bytes. A vbmeta range that overlaps the header, a component, or the footer is malformed.

Bounded work

The reader admits at most 4,096 vendor ramdisk table entries and an entry size of at most 4,096 bytes. A vendor header_size above 1 MiB is the same kind of capacity limit. Those checks happen before the table is read. Unsupported header revisions return unsupported_target; truncated declared structures return truncated; malformed layouts return invalid_request. These refusals do not produce an empty successful inventory. Gaps inside a vendor ramdisk section, or bytes between the sequential layout and a recovery DTBO, are named in limitations instead of being invented as entries.

rea inspect-artifact boot.img --detail summary \
  --evidence_output boot.evidence.json --json
rea extract-artifact vendor_boot.img --json

With MCP, inspect_artifact with detail: "summary" retains the complete Evidence. Use inspect_analysis_view and its parent_evidence_id for exact logical paths, batches of occurrence/content IDs, selected fields and pages.

Verification scope

Source and compiled CLI/MCP tests cover stored component bytes, compression magics, unsupported revisions, truncation, overlapping ranges, capacity, cancellation, and cleanup. An independent offline check used AOSP mkbootimg.py and unpack_bootimg.py at commit d2bb0af5ba6d3198a3e99529c97eda1be0b5a093: boot versions 0 through 4 and vendor_boot versions 3 and 4 had component ranges and digests matching their small inert input files and official unpacked output. Version 4 vendor_boot extraction also matched those inputs. No device-dumped image, signature verification, AVB digest verification, or payload decompression was checked.