mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 05:02:40 +00:00
112 lines
5.7 KiB
Markdown
112 lines
5.7 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
|
|
|
|
The reader checks the final 64 bytes for an `AVBf` footer when those bytes
|
|
begin at or after the end of the last declared image component, even if they
|
|
start before the page-rounded image end. A matching footer records its version,
|
|
original image size, and vbmeta offset and size. The footer and vbmeta remain
|
|
unverified metadata. If no footer is recognized, the reader reports undecoded
|
|
trailing bytes beyond the page-rounded image end. 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.
|