Files
reverse-engineering-anything/docs/specs/firmware/android-boot-image/spec.md
T
Anurag SinghandAnurag Singh bb5278c7e2 fix(artifacts): accept Android boot images without final page padding (#11857)
* fix(artifacts): accept Android boot images without final page padding

The truncation check required the file to reach the page-aligned end
after the last component, so an image holding every declared byte but
omitting the trailing zero padding was refused as truncated, and the
message named the padded end. Bound truncation by the last declared
header or component byte instead, keep the page-aligned end for
locating an AVB footer, and check the AVB original image size against
the declared bytes.

Fixes #11854

* test(artifacts): check boot image declared ends against the fixture layout

Derive each expected end from the fixture layout instead of the
parser's dataEnd, so a declared structure dropped from the coverage
check fails the test.

---------

Co-authored-by: Anurag Singh <211784907+Anurag-5ingh@users.noreply.github.com>
2026-11-17 15:06:28 -05:00

121 lines
7.1 KiB
Markdown

# Android boot and vendor_boot images
## Problem and outcome
Android firmware inspection starts from `boot.img`, `init_boot.img`,
`recovery.img`, and `vendor_boot.img`. REA inventories APKs, devicetree blobs,
legacy uImage containers, and FIT images. It has no reader for an Android boot
image, so `inspect_artifact` and `extract_artifact` cannot expose the kernel,
ramdisk, or DTB stored in one.
This feature adds a provider-less artifact reader for `ANDROID!` headers
(versions 0 through 4) and `VNDRBOOT` headers (versions 3 and 4). Header facts
and component children use the existing artifact inventory, extraction, CLI,
and MCP path.
[Android boot and vendor_boot images](../../../android-boot-image.md) describes
the current behavior and limitations. This directory is the feature
specification, implementation plan, and task list. The guide does not replace
these files.
## Requirements
1. Classification uses the 8-byte magic `ANDROID!` or `VNDRBOOT`, independent
of filename. `hasAndroidBootImageMagic` is the only magic owner. Target
resolution and artifact-graph construction call it.
2. `src/artifacts/AndroidBootImageFormat.ts` decodes the header, the vendor
ramdisk table, and the AVB footer once. The reader consumes those facts.
Header multi-byte fields are little-endian. AVB footer sizes and versions
are big-endian. `u64`, `alignUp`, and range ends reject values that are not
safe integers. Parse failures return `Result` with shared `ParseFailureError`
facts. The artifact error owner preserves `malformed`, `truncated`,
`unsupported`, and `limit` through CLI/MCP projection and cleanup retry.
3. Boot versions 0 through 2 take a power-of-two page size from 2048 through 65536. The header occupies the first page. Kernel, ramdisk, and second
stage follow, each padded 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. Boot versions 3 and 4 use a fixed
4096-byte page. Kernel and ramdisk follow the header page. Version 4 can
append a signature as a stored range with a size.
4. Vendor_boot versions 3 and 4 record kernel, ramdisk, and tags load
addresses, the board name, a 2048-byte command line, the vendor ramdisk,
and a DTB. The vendor page size is a power of two from 2048 through 65536.
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
stays metadata. 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. An empty name,
`.`, `..`, or a name containing `/` becomes `ramdisk-<index>`. A repeated
name gains `-<index>`, then further numeric suffixes until the path is
unique.
5. OS version and security patch level come from the packed `os_version` word
on a boot image. A month outside 1 through 12 leaves the patch level null
and keeps the raw word. Vendor_boot has no OS version field. Versions 0
through 2 concatenate `cmdline` and `extra_cmdline` with no separator.
Versions 3 and 4 store one combined command line. Invalid UTF-8 leaves the
text null and keeps the raw field bytes as hex. Command line, board name,
and vendor ramdisk names are target-derived and untrusted. An `ANDROID!`
image covers boot, init_boot, and recovery; the header leaves that role
unknown.
6. Non-empty components become children: `kernel`, `ramdisk`, `second`,
`recovery_dtbo`, `dtb`, `vendor_ramdisk`, `vendor_ramdisk/<name>`,
`bootconfig`, and `signature`. A prefix of 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. Any other prefix leaves compression null. Null
means none of those magics matched. Stored bytes stay compressed. A kernel
that starts with ELF magic is classified as `elf` by the existing content
check. A `dtb` child stays a file for a later `inspect-devicetree` on the
extracted file.
7. When bytes follow the page-aligned image, the last 64 bytes are compared
with `AVBf`. A match records footer version, original image size, and
vbmeta offset and size. The footer and vbmeta stay header facts. A shorter
tail, or a tail that does not start with `AVBf`, is undecoded trailing
bytes. A vbmeta range that overlaps the header, a component, or the footer
is malformed.
8. The header probe is at most 4096 bytes. The reader admits at most 4096
vendor ramdisk table entries, an entry size of at most 4096 bytes, and a
vendor `header_size` of at most 1 MiB. Those checks run before the table
is read. Truncated declared structures return `truncated`; the page
padding after the last component may be absent. Unsupported
revisions return `unsupported_target`; malformed layouts return
`invalid_request`. Gaps inside a vendor ramdisk
section, and bytes between the sequential layout and a recovery DTBO, are
named in limitations. Member bytes stream on demand.
9. CLI and MCP return the same Evidence shape, including the untrusted-string
limitation and the unknown boot role. `androidBootImageMetadataSchema` and
`androidBootImageEntryMetadataSchema` are `strictObject` members of the
kind-discriminated artifact metadata union. Summary detail retains
Evidence. `inspect_analysis_view` pages it.
10. The reader reuses `ArtifactFileSource`, `readArtifactFileBytes`,
`readFileHandleChunks`, and `ArtifactResourceScope`. Close rethrows a
scope or source close failure and keeps the handle for retry.
Cancellation applies during admission, paused inventory, buffered reads,
and multi-chunk reads. A source change after prepare fails closed.
## Acceptance
Synthetic fixtures cover a version 0 image, a version 2 image with a DTB,
version 3 and version 4 boot images, and a version 4 vendor_boot image with
two ramdisk table entries, plus truncated and overlapping-range inputs.
Parser tests, reader tests, boundary tests, the CLI acceptance test, and the
MCP boundary test cover those images, compression magics, capacity limits,
cancellation, and cleanup retry. CLI and MCP tests assert the same Evidence
limitations. Temp directories use `createTestTempDirectory` without an
`afterEach` root removal. The MCP extraction cleanup removes the extraction
output root.
Fixtures are synthetic headers and stored payloads. An independent offline
check also generates boot v0-v4 and vendor_boot v3-v4 images with pinned AOSP
`mkbootimg.py`, then compares REA ranges and digests with the known inputs and
official `unpack_bootimg.py` output. This feature includes no device-dumped
image. No signature check, AVB digest check, or payload decompressor runs.
## Non-goals
- Decompressing ramdisk, kernel, or bootconfig bytes.
- Checking the header digest, the version 4 boot signature, or the AVB footer.
- A separate `inspect_android_boot_image` tool.
- A Binwalk or Unblob adapter.
- Assigning boot, init_boot, or recovery from the header.
- Executing, booting, or modifying the image.