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

110 lines
5.5 KiB
Markdown

# 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.
## AVB footer
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.
```sh
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.