mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 20:53:00 +00:00
* 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>
111 lines
5.6 KiB
Markdown
111 lines
5.6 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`. The page
|
|
padding after the last component carries no data and may be absent. 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.
|