Files
reverse-engineering-anything/docs/specs/firmware/android-boot-image/plan.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

56 lines
3.0 KiB
Markdown

# Implementation plan
One format-aware parser normalizes the header, vendor ramdisk table, and AVB
footer. The artifact reader consumes that result. Registration follows the
uImage reader. Requirements are numbered in [spec.md](spec.md).
## Boundary and contract
1. Keep parsing in `src/artifacts/AndroidBootImageFormat.ts`, using shared
`Result`, `ParseFailureError`, and bounded `BinaryReader` primitives.
Keep magic recognition in `src/domain/androidBootImageFormat.ts`. Export
`parseAndroidBootHeader`, `parseVendorRamdiskTable`, `inspectAvbFooter`,
and `compressionFromPrefix` from the parser. Preserve parser failure kinds
through the shared artifact failure owner.
2. Add `AndroidBootImageArtifactReader` with format `android-boot-image`. It
probes at most 4096 header bytes, reads a 64-byte tail for the AVB check,
and streams member bytes on demand. Table admission uses the 4096-entry,
4096-byte entry, and 1 MiB header caps before any table read.
3. Add `androidBootImageMetadataSchema` and
`androidBootImageEntryMetadataSchema` as `strictObject` members of the
kind-discriminated artifact metadata union. Catalog order does not select
the schema.
4. Add `android-boot-image` to `ARTIFACT_FORMATS` with the same container
flags as uImage: `roleContainer`, `retainClassifiedSource`, `extractable`,
and `absentInventory: "unavailable"`. `createArtifactReader`, inventory
classification, and extraction follow that registry.
`ArtifactGraphConstruction` and `BinaryTargetResolver` call
`hasAndroidBootImageMagic`. Add the kind to `ArtifactReader`, the artifact
graph, evidence subject, analysis snapshot, live target summary, and
binary target types.
5. Carry untrusted target-derived strings and the unknown boot, init_boot, or
recovery role in reader limitations. CLI and MCP preserve that Evidence.
Summary detail keeps the full Evidence and uses `inspect_analysis_view`
for paging.
6. Reuse `ArtifactFileSource`, ranged reads, chunk reads, and
`ArtifactResourceScope`. A failed close stays owned so a later close can
retry. Cancellation covers admission, paused inventory, buffered bytes,
and multi-chunk reads.
## Validation
Synthetic fixtures live in `tests/fixtures/androidBootImage.ts`: version 0,
version 2 with a DTB, versions 3 and 4 boot, version 4 vendor_boot with two
ramdisk table entries, and truncated and overlapping-range negatives. Cover
the parser, the reader, filesystem boundaries, CLI acceptance, and MCP
boundary output, including matching Evidence limitations and unsupported,
truncated, and malformed refusals. Use pinned AOSP generation and unpacking
with small inert component inputs as an independent byte oracle. State that
no device-dumped image was checked.
## Effects and compatibility
The reader only reads an admitted local file. It introduces no execution,
boot, decompression, digest check, or signature check. The new metadata kinds
are additive. Other artifact formats keep their existing schemas.