diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index c663e5f50f..3675007ac4 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -910,6 +910,15 @@ Multi-file components retain their aligned physical ranges; the full payload is also materialized. Unknown name text retains its original 32 bytes. See [U-Boot uImage](https://github.com/morluto/rea/blob/main/docs/uimage.md). +Android boot, init_boot, recovery, and vendor_boot images use the same +inspection and extraction workflows. `ANDROID!` versions 0-4 and `VNDRBOOT` +versions 3-4 expose header facts and stored component bytes. The header does +not record whether an `ANDROID!` image is boot, init_boot, or recovery. +Command lines and names are target-derived. gzip, lz4, and zstd payloads stay +stored. The v4 signature and any AVB footer are reported with sizes and are +not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See +[Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md). + ## ESP images For an ESP32-family app or bootloader image, `open_binary` then diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index c663e5f50f..3675007ac4 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -910,6 +910,15 @@ Multi-file components retain their aligned physical ranges; the full payload is also materialized. Unknown name text retains its original 32 bytes. See [U-Boot uImage](https://github.com/morluto/rea/blob/main/docs/uimage.md). +Android boot, init_boot, recovery, and vendor_boot images use the same +inspection and extraction workflows. `ANDROID!` versions 0-4 and `VNDRBOOT` +versions 3-4 expose header facts and stored component bytes. The header does +not record whether an `ANDROID!` image is boot, init_boot, or recovery. +Command lines and names are target-derived. gzip, lz4, and zstd payloads stay +stored. The v4 signature and any AVB footer are reported with sizes and are +not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See +[Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md). + ## ESP images For an ESP32-family app or bootloader image, `open_binary` then diff --git a/docs/.vitepress/documentation.ts b/docs/.vitepress/documentation.ts index 1e55dd645f..9af8cc4ae3 100644 --- a/docs/.vitepress/documentation.ts +++ b/docs/.vitepress/documentation.ts @@ -538,6 +538,11 @@ export const documentationSections = [ source: "agent-environments.md", route: "/agent-environments", }, + { + text: "Android boot and vendor_boot images", + source: "android-boot-image.md", + route: "/android-boot-image", + }, { text: "APK signature schemes", source: "apk-signature.md", diff --git a/docs/README.md b/docs/README.md index 8f41c16a5d..caabcc1de4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -173,6 +173,7 @@ the exact commit messages and references from the release they describe. - [iNES containers](ines-containers.md) - [Build RL environments with REA](agent-environments-quickstart.md) - [Agent environments from recorded captures](agent-environments.md) +- [Android boot and vendor_boot images](android-boot-image.md) - [APK signature schemes](apk-signature.md) - [Apple IPS crash reports](apple-ips.md) - [Static analysis in GitHub Actions](ci-analysis.md) diff --git a/docs/android-boot-image.md b/docs/android-boot-image.md new file mode 100644 index 0000000000..effacdfec3 --- /dev/null +++ b/docs/android-boot-image.md @@ -0,0 +1,109 @@ +# 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/`, 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-`. A repeated name gains `-`. 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/` | 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. diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index d190528389..96fd1c4ace 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -403,6 +403,17 @@ rea extract-artifact ./boot.itb --json See [U-Boot FIT images](../fit-images.md) for recognition, data sources, hashes and limits. +Inspect and extract an Android boot or vendor_boot image: + +```sh +rea inspect-artifact ./boot.img --detail summary --evidence_output boot.json --json +rea extract-artifact ./vendor_boot.img --json +``` + +See [Android boot images](../android-boot-image.md) for header versions 0 through +4, vendor ramdisk table entries, stored compression, and the unverified AVB +footer. `ANDROID!` does not record boot versus init_boot versus recovery. + Inspect local model declarations without loading weights: ```bash diff --git a/docs/guides/firmware/firmware-analysis.md b/docs/guides/firmware/firmware-analysis.md index 01d4861033..bb584d2bdf 100644 --- a/docs/guides/firmware/firmware-analysis.md +++ b/docs/guides/firmware/firmware-analysis.md @@ -375,3 +375,16 @@ images, declared load and entry addresses, configurations and verified hashes, then `extract-artifact` / `extract_artifact` for one raw file per image. Decoding is portable and requires no external tool. See [U-Boot FIT images](../../fit-images.md). + +## Inspect Android boot and vendor_boot images + +`inspect-artifact` / `extract-artifact` recognize `ANDROID!` (header versions +0 through 4) and `VNDRBOOT` (vendor_boot versions 3 and 4) by magic. The root +records page size, component sizes, the command line, OS version and security +patch level when the header has them, the board name, and the header digest. +Children are the stored kernel, ramdisk, second stage, recovery DTBO, DTB, +vendor ramdisk table entries, bootconfig, and v4 signature. gzip, lz4, and +zstd are recorded from leading magic and left compressed. An AVB footer is +reported with its sizes and is not verified. `ANDROID!` does not say whether +the file was boot, init_boot, or recovery. Extract `dtb` and pass that file +to `inspect-devicetree`. See [Android boot images](../../android-boot-image.md). diff --git a/docs/index.md b/docs/index.md index 33224467f0..3bf652a571 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,19 +49,19 @@ For runtime instrumentation, see the [Frida guide](guides/runtime/frida-instrume The [documentation directory](README.md) lists every guide by domain. -| Task | Guides | -| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | -| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | -| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | -| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | -| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | -| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [.NET](guides/managed/managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | -| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | -| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | -| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | -| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | -| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | +| Task | Guides | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | +| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | +| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | +| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | +| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | +| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | +| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | +| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | +| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | +| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | +| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | For development, use [testing](development/testing.md), [client verification](development/client-verification.md), [tool design](development/tool-design.md), [admission limits and recovery](design/limits-and-recovery.md), diff --git a/docs/specs/README.md b/docs/specs/README.md index f21640b384..38b123831b 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -22,6 +22,7 @@ for new work, roadmap granularity and producer-owned contracts. - [Core WebAssembly interface comparison (#2356)](2356-wasm-interface-comparison/spec.md) ([plan](2356-wasm-interface-comparison/plan.md), [tasks](2356-wasm-interface-comparison/tasks.md), [verification](2356-wasm-interface-comparison/verification.md)) - [Inspect APK signature schemes (v1–v3.1)](apk-signature/spec.md) - [Documentation organization](documentation/organization/spec.md) ([plan](documentation/organization/plan.md), [tasks](documentation/organization/tasks.md), [verification](documentation/organization/verification.md)) +- [Android boot and vendor_boot images](firmware/android-boot-image/spec.md) ([plan](firmware/android-boot-image/plan.md), [tasks](firmware/android-boot-image/tasks.md)) - [V8 cached-data compilation boundaries](javascript/v8-cached-data/spec.md) ([plan](javascript/v8-cached-data/plan.md), [tasks](javascript/v8-cached-data/tasks.md)) - [Android `.note.android.ident` ELF note decoding](native/android-elf-ident-note/spec.md) ([plan](native/android-elf-ident-note/plan.md), [tasks](native/android-elf-ident-note/tasks.md)) - [Native call source coordinates](native/call-source-locations/spec.md) ([plan](native/call-source-locations/plan.md), [tasks](native/call-source-locations/tasks.md), [verification](native/call-source-locations/verification.md)) diff --git a/docs/specs/firmware/android-boot-image/plan.md b/docs/specs/firmware/android-boot-image/plan.md new file mode 100644 index 0000000000..eae12f681f --- /dev/null +++ b/docs/specs/firmware/android-boot-image/plan.md @@ -0,0 +1,55 @@ +# 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. diff --git a/docs/specs/firmware/android-boot-image/spec.md b/docs/specs/firmware/android-boot-image/spec.md new file mode 100644 index 0000000000..436fa478bb --- /dev/null +++ b/docs/specs/firmware/android-boot-image/spec.md @@ -0,0 +1,119 @@ +# 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/`, 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-`. A repeated + name gains `-`, 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/`, + `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`; 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. diff --git a/docs/specs/firmware/android-boot-image/tasks.md b/docs/specs/firmware/android-boot-image/tasks.md new file mode 100644 index 0000000000..3dee56f01c --- /dev/null +++ b/docs/specs/firmware/android-boot-image/tasks.md @@ -0,0 +1,30 @@ +# Tasks + +Requirement numbers refer to [spec.md](spec.md). Verification names the test +that covers the step. + +- [x] Record this specification, [plan](plan.md), and task list for the + Android boot image reader. (Requirements 1-10) +- [x] Decode `ANDROID!` versions 0-4 and `VNDRBOOT` versions 3-4 in the artifact + parser, including safe integer ranges, packed `os_version`, UTF-8 + failure, vendor ramdisk names, and tagged parse errors. + (Requirements 1-5, 7-8; `src/artifacts/AndroidBootImageFormat.test.ts`) +- [x] Map non-empty components to children, record compression from the + leading magic, stream member bytes, and enforce probe and table caps + before the table read. (Requirements 6 and 8; + `src/artifacts/AndroidBootImageArtifactReader.test.ts`) +- [x] Register metadata schemas and the reader on the uImage inventory, + extraction, and target-resolution path. (Requirement 9; + `src/artifacts/artifactFormats.test.ts`, + `src/application/binary/TargetFormatVocabularies.test.ts`) +- [x] Preserve untrusted-string and unknown-role limitations through CLI and + MCP Evidence. (Requirements 5 and 9; + `tests/acceptance/androidBootImageCli.test.ts`, + `tests/boundary/mcp/androidBootImageMcp.test.ts`) +- [x] Cover close retry, cancellation during admission and paused inventory, + cancel with buffered bytes, source change after prepare, and multi-chunk + cancel. (Requirement 10; + `src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts`) +- [x] Describe current behavior and the capacity bounds in + `docs/android-boot-image.md`, and link that guide from the documentation + directory, CLI guide, and firmware guide. (Acceptance) diff --git a/docs/user-visible-errors.csv b/docs/user-visible-errors.csv index 4f9e6d2873..42d89b0654 100644 --- a/docs/user-visible-errors.csv +++ b/docs/user-visible-errors.csv @@ -15,6 +15,9 @@ EvidenceIntegrityError,,evidence_integrity_mismatch,integrity_mismatch,false ProviderAdapterError,,execution_failure,execution_failure,false AnalysisCapabilityUnavailableError,retryable=true,capability_unavailable,unavailable,true ArtifactOperationError,reason=cancelled,cancelled,cancelled,true +ArtifactOperationError,reason=malformed,invalid_request,invalid_input,false +ArtifactOperationError,reason=truncated,truncated,truncated,false +ArtifactOperationError,reason=unsupported,unsupported_target,unsupported_target,false ArtifactOperationError,reason=format,artifact_operation_failed,execution_failure,false ArtifactOperationError,reason=integrity,artifact_operation_failed,integrity_mismatch,false ArtifactOperationError,reason=limit,truncated,truncated,false diff --git a/scripts/verify/advertised-schemas/tools/open_binary.json b/scripts/verify/advertised-schemas/tools/open_binary.json index 6fbdedd92e..cb11208ca2 100644 --- a/scripts/verify/advertised-schemas/tools/open_binary.json +++ b/scripts/verify/advertised-schemas/tools/open_binary.json @@ -1,7 +1,7 @@ { "schemas": { "input compact": "706f1985ca397688", - "output compact": "52860f8f8ed909d0" + "output compact": "c100ceae46994f08" }, "patterns": { "input": [ diff --git a/src/application/binary/TargetFormatVocabularies.test.ts b/src/application/binary/TargetFormatVocabularies.test.ts index 1657d91e53..8278e1fb83 100644 --- a/src/application/binary/TargetFormatVocabularies.test.ts +++ b/src/application/binary/TargetFormatVocabularies.test.ts @@ -122,6 +122,7 @@ const TARGETS: TargetFixtures = { unityfs: { ...archive, format: "unityfs" }, wxapkg: { ...archive, format: "wxapkg" }, uimage: { ...archive, format: "uimage" }, + "android-boot-image": { ...archive, format: "android-boot-image" }, uf2: { ...archive, format: "uf2" }, dfuse: { ...archive, format: "dfuse" }, dmg: { ...archive, format: "dmg" }, diff --git a/src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts b/src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts new file mode 100644 index 0000000000..4bda72eaac --- /dev/null +++ b/src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts @@ -0,0 +1,245 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { buffer } from "node:stream/consumers"; + +import { expect, it, vi } from "vitest"; + +import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js"; +import { + ArtifactReaderFailure, + artifactFixedLimitFailure, +} from "../resources/index.js"; +import { openRegularFile } from "../filesystem/RegularFile.js"; +import { + buildBootImage, + buildVendorBootImage, +} from "../../tests/fixtures/androidBootImage.js"; +import { artifactReaderLifecycleCases } from "../../tests/fixtures/artifactReaderLifecycle.js"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; + +const fixture = async (bytes: Buffer): Promise => { + const path = join( + await createTestTempDirectory("rea-android-boot-boundary-"), + "image", + ); + await writeFile(path, bytes); + return path; +}; + +const entries = async (reader: AndroidBootImageArtifactReader) => { + const result = []; + for await (const entry of reader.entries()) result.push(entry); + return result; +}; + +it("does not publish preparation metadata or coverage after carrier mutation", async () => { + const bytes = buildBootImage({ version: 0 }); + const path = await fixture(bytes); + class ChangedDuringPreparation extends AndroidBootImageArtifactReader { + protected override async prepareEntries(signal?: AbortSignal) { + const prepared = await super.prepareEntries(signal); + await writeFile(path, Buffer.concat([bytes, Buffer.from([0])])); + return prepared; + } + } + const reader = new ChangedDuringPreparation(path); + const onCoverage = vi.fn(); + let yielded = 0; + try { + await expect( + (async () => { + for await (const _entry of reader.entries(undefined, { onCoverage })) + yielded += 1; + })(), + ).rejects.toMatchObject({ reason: "integrity" }); + expect(yielded).toBe(0); + expect(onCoverage).not.toHaveBeenCalled(); + expect(reader.formatMetadata()).toBeUndefined(); + } finally { + await reader.close(); + } +}); + +it.each(["invalid", "cancelled"] as const)( + "retries a first %s preparation without publishing its metadata", + async (mode) => { + const path = await fixture(buildBootImage({ version: 0 })); + const controller = new AbortController(); + let refuse = true; + class InterruptedPreparation extends AndroidBootImageArtifactReader { + protected override async prepareEntries(signal?: AbortSignal) { + const prepared = await super.prepareEntries(signal); + if (refuse) { + refuse = false; + if (mode === "invalid") + throw new ArtifactReaderFailure( + "malformed", + "injected preparation failure", + ); + controller.abort(new Error("cancel final preparation validation")); + } + return prepared; + } + } + const reader = new InterruptedPreparation(path); + try { + const onCoverage = vi.fn(); + await expect( + (async () => { + for await (const _entry of reader.entries(controller.signal, { + onCoverage, + })) { + throw new Error("Failed preparation yielded an entry"); + } + })(), + ).rejects.toMatchObject({ + reason: mode === "invalid" ? "malformed" : "cancelled", + }); + expect(onCoverage).not.toHaveBeenCalled(); + expect(reader.formatMetadata()).toBeUndefined(); + expect(await entries(reader)).toHaveLength(2); + expect(reader.formatMetadata()).toMatchObject({ + header_version: 0, + component_count: 2, + }); + } finally { + await reader.close(); + } + }, +); + +it("preserves cancellation during header admission", async () => { + const path = await fixture(buildBootImage({ version: 0 })); + const admitted = await openRegularFile(path, { symlinks: "reject" }); + const reader = new AndroidBootImageArtifactReader(path, admitted); + const controller = new AbortController(); + const reason = new Error("cancel header admission"); + const nativeRead = admitted.handle.read.bind(admitted.handle); + const reads = vi.spyOn(admitted.handle, "read").mockImplementation((async ( + ...args: unknown[] + ) => { + const result = await Reflect.apply(nativeRead, admitted.handle, args); + if (args[3] === 0) controller.abort(reason); + return result; + }) as typeof admitted.handle.read); + try { + await expect( + (async () => { + for await (const _entry of reader.entries(controller.signal)) { + /* Exhaust the admitted operation. */ + } + })(), + ).rejects.toMatchObject({ reason: "cancelled", cause: reason }); + } finally { + await reader.close(); + reads.mockRestore(); + await admitted.handle.close(); + } +}); + +const vendorBootWithRamdisks = (count: number): Buffer => + buildVendorBootImage({ + version: 4, + ramdisks: Array.from({ length: count }, (_, index) => ({ + name: `ramdisk${String(index)}`, + bytes: Buffer.from([index & 0xff]), + })), + }); + +it("inventories a vendor ramdisk table at its 4096-entry allowance", async () => { + const path = await fixture(vendorBootWithRamdisks(4096)); + const admitted = await openRegularFile(path, { symlinks: "reject" }); + const reader = new AndroidBootImageArtifactReader(path, admitted); + try { + const listed = await entries(reader); + expect( + listed.filter((entry) => entry.path.startsWith("vendor_ramdisk")), + ).toHaveLength(4096); + } finally { + await reader.close(); + await admitted.handle.close(); + } +}); + +it("rejects an excessive vendor ramdisk count before reading the table", async () => { + const path = await fixture(vendorBootWithRamdisks(4097)); + const admitted = await openRegularFile(path, { symlinks: "reject" }); + const reader = new AndroidBootImageArtifactReader(path, admitted); + const reads = vi.spyOn(admitted.handle, "read"); + try { + const failure: unknown = await entries(reader).then( + () => undefined, + (cause: unknown) => cause, + ); + // The limit's facts and the recovery its owning formatter produces. + expect(failure).toMatchObject({ + reason: "limit", + boundary: "capacity", + fixedAllowance: artifactFixedLimitFailure( + { + name: "Android vendor ramdisk table entry count", + kind: "parser", + limit: 4096, + unit: "entries", + }, + "table count", + ).fixedAllowance, + cause: { + kind: "limit", + failure: { limit: { maximum: 4096 } }, + }, + }); + expect(reads).toHaveBeenCalledTimes(1); + } finally { + await reader.close(); + reads.mockRestore(); + await admitted.handle.close(); + } +}); + +artifactReaderLifecycleCases({ + image: () => buildBootImage({ version: 0 }), + createReader: (path, admitted) => + new AndroidBootImageArtifactReader(path, admitted), +}); + +it("rejects a source changed after its header was prepared", async () => { + const bytes = buildBootImage({ version: 0 }); + const path = await fixture(bytes); + const reader = new AndroidBootImageArtifactReader(path); + try { + const [entry] = await entries(reader); + await writeFile(path, Buffer.concat([bytes, Buffer.from([0])])); + await expect(reader.open(entry!)).rejects.toMatchObject({ + reason: "integrity", + }); + } finally { + await reader.close(); + } +}); + +it("checks a multi-chunk member and preserves read cancellation", async () => { + const kernel = Buffer.alloc(128 * 1024, 0x61); + const bytes = buildBootImage({ + version: 0, + kernel, + ramdisk: Buffer.alloc(0), + }); + const reader = new AndroidBootImageArtifactReader(await fixture(bytes)); + try { + const [entry] = await entries(reader); + const controller = new AbortController(); + const reason = new Error("cancel member bytes"); + const stream = await reader.open(entry!, controller.signal); + const iterator = stream[Symbol.asyncIterator](); + await iterator.next(); + controller.abort(reason); + await expect(iterator.next()).rejects.toMatchObject({ + reason: "cancelled", + cause: reason, + }); + expect((await buffer(await reader.open(entry!))).equals(kernel)).toBe(true); + } finally { + await reader.close(); + } +}); diff --git a/src/artifacts/AndroidBootImageArtifactReader.test.ts b/src/artifacts/AndroidBootImageArtifactReader.test.ts new file mode 100644 index 0000000000..bb3ec0f79d --- /dev/null +++ b/src/artifacts/AndroidBootImageArtifactReader.test.ts @@ -0,0 +1,330 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import type { Readable } from "node:stream"; + +import { expect, it } from "vitest"; + +import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js"; +import { classifyArtifactBytesAtPath } from "../../tests/fixtures/artifactClassification.js"; +import { scanCanonicalArtifactInventory } from "../../tests/fixtures/artifactInventory.js"; +import { + appendAvbFooter, + buildBootImage, + buildVendorBootImage, + osVersionRaw, + truncateImage, +} from "../../tests/fixtures/androidBootImage.js"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { elf } from "../domain/binaryTarget.fixture.js"; + +const collect = async (stream: Readable): Promise => { + const chunks: Buffer[] = []; + for await (const chunk of stream) chunks.push(chunk as Buffer); + return Buffer.concat(chunks); +}; + +const writeCarrier = async (name: string, bytes: Buffer): Promise => { + const directory = await createTestTempDirectory("rea-android-boot-"); + const path = join(directory, name); + await writeFile(path, bytes); + return path; +}; + +const openAll = async (path: string): Promise> => { + const reader = new AndroidBootImageArtifactReader(path); + const out = new Map(); + try { + const entries = []; + for await (const entry of reader.entries()) entries.push(entry); + for (const entry of entries) + out.set(entry.path, await collect(await reader.open(entry))); + return out; + } finally { + await reader.close(); + } +}; + +it("classifies boot and vendor_boot bytes by content, not by suffix", () => { + expect( + classifyArtifactBytesAtPath("notes.txt", buildBootImage({ version: 0 })), + ).toEqual({ kind: "container", format: "android-boot-image" }); + expect( + classifyArtifactBytesAtPath( + "vendor.bin", + buildVendorBootImage({ version: 4 }), + ), + ).toEqual({ kind: "container", format: "android-boot-image" }); + expect(classifyArtifactBytesAtPath("notes.txt", Buffer.from("nope"))).toEqual( + { kind: "resource", format: "file" }, + ); +}); + +it("inventories and extracts a v0 image", async () => { + const kernel = Buffer.from("kernel-bytes"); + const ramdisk = Buffer.from("ramdisk-bytes"); + const path = await writeCarrier( + "boot.img", + buildBootImage({ + version: 0, + kernel, + ramdisk, + osVersion: osVersionRaw(13, 0, 0, 2024, 11), + }), + ); + const snapshot = await scanCanonicalArtifactInventory(path); + expect(snapshot.manifest.root_format).toBe("android-boot-image"); + expect(snapshot.coverage.status).toBe("complete"); + expect(snapshot.limitations.join(" ")).toContain("not decompressed"); + expect(snapshot.limitations.join(" ")).toContain("untrusted"); + const root = snapshot.occurrences.find((row) => row.logical_path === "."); + expect(root).toMatchObject({ artifact_kind: "container" }); + expect(root?.format_metadata).toMatchObject({ + kind: "android-boot-image", + image_kind: "boot", + header_version: 0, + os_version: "13.0.0", + security_patch_level: "2024-11", + command_line: "console=tty0 androidboot.hardware=test", + component_count: 2, + avb_footer_present: false, + avb_footer_size: null, + }); + const stored = await openAll(path); + expect(stored.get("kernel")?.equals(kernel)).toBe(true); + expect(stored.get("ramdisk")?.equals(ramdisk)).toBe(true); + const carrier = await readFile(path); + expect(carrier.subarray(2048, 2048 + kernel.length).equals(kernel)).toBe( + true, + ); +}); + +it("extracts a v2 DTB, a v4 signature, and compressed ramdisks as stored", async () => { + const dtb = Buffer.from("dtb-payload"); + const v2 = await writeCarrier( + "v2.img", + buildBootImage({ + version: 2, + // A decodable ELF64 little-endian x86-64 header, as classification requires. + kernel: elf(2, 1, 62), + ramdisk: Buffer.alloc(0), + dtb, + }), + ); + const v2Graph = await scanCanonicalArtifactInventory(v2); + expect( + v2Graph.occurrences.find((row) => row.logical_path === "kernel"), + ).toMatchObject({ artifact_format: "elf" }); + expect( + v2Graph.occurrences.find((row) => row.logical_path === "dtb"), + ).toMatchObject({ + artifact_format: "file", + source_location: { offset: 4096, length: dtb.length }, + }); + expect((await openAll(v2)).get("dtb")?.equals(dtb)).toBe(true); + + const signature = Buffer.from("boot-signature"); + const v4 = await writeCarrier( + "v4.img", + buildBootImage({ + version: 4, + kernel: Buffer.from("kern"), + ramdisk: Buffer.alloc(0), + signature, + }), + ); + const v4Root = (await scanCanonicalArtifactInventory(v4)).occurrences.find( + (row) => row.logical_path === ".", + ); + expect(v4Root?.format_metadata).toMatchObject({ + header_version: 4, + signature_size: signature.length, + page_size: 4096, + }); + expect((await openAll(v4)).get("signature")?.equals(signature)).toBe(true); + + const gzip = Buffer.from([0x1f, 0x8b, 0x08, 0]); + const lz4 = Buffer.from([0x04, 0x22, 0x4d, 0x18, 1]); + const zstd = Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 2]); + const compressed = await writeCarrier( + "compressed.img", + buildBootImage({ version: 0, kernel: lz4, ramdisk: gzip, second: zstd }), + ); + const graph = await scanCanonicalArtifactInventory(compressed); + expect( + graph.occurrences.find((row) => row.logical_path === "ramdisk") + ?.format_metadata, + ).toMatchObject({ compression: "gzip" }); + expect( + graph.occurrences.find((row) => row.logical_path === "kernel") + ?.format_metadata, + ).toMatchObject({ compression: "lz4" }); + expect( + graph.occurrences.find((row) => row.logical_path === "second") + ?.format_metadata, + ).toMatchObject({ compression: "zstd" }); + const stored = await openAll(compressed); + expect(stored.get("ramdisk")?.equals(gzip)).toBe(true); + expect(stored.get("kernel")?.equals(lz4)).toBe(true); + expect(stored.get("second")?.equals(zstd)).toBe(true); + expect( + graph.occurrences + .find((row) => row.logical_path === "ramdisk") + ?.limitations.join(" "), + ).toContain("not decompressed"); +}); + +it("extracts two vendor ramdisks without inventing fragment load addresses", async () => { + const platform = Buffer.from("platform-bytes"); + const recovery = Buffer.from("recovery-bytes"); + const dtb = Buffer.from("vendor-dtb"); + const bootconfig = Buffer.from("androidboot.hardware=test\n"); + const path = await writeCarrier( + "vendor_boot.img", + buildVendorBootImage({ + version: 4, + ramdisks: [ + { name: "platform", type: 1, bytes: platform }, + { name: "recovery", type: 2, bytes: recovery }, + ], + dtb, + bootconfig, + }), + ); + const snapshot = await scanCanonicalArtifactInventory(path); + expect( + snapshot.occurrences.find((row) => row.logical_path === ".") + ?.format_metadata, + ).toMatchObject({ + image_kind: "vendor-boot", + vendor_ramdisk_table_entry_count: 2, + component_count: 4, + ramdisk_addr: 0x8100_0000, + }); + const platformEntry = snapshot.occurrences.find( + (row) => row.logical_path === "vendor_ramdisk/platform", + ); + expect(platformEntry?.format_metadata).toMatchObject({ + role: "vendor-ramdisk", + ramdisk_type: 1, + ramdisk_type_name: "platform", + load_address: null, + }); + expect( + snapshot.occurrences.find( + (row) => row.logical_path === "vendor_ramdisk/recovery", + )?.format_metadata, + ).toMatchObject({ ramdisk_type_name: "recovery", load_address: null }); + expect(platformEntry?.source_location).toEqual({ + offset: 4096, + length: platform.length, + }); + const stored = await openAll(path); + expect(stored.get("vendor_ramdisk/platform")?.equals(platform)).toBe(true); + expect(stored.get("vendor_ramdisk/recovery")?.equals(recovery)).toBe(true); + expect(stored.get("dtb")?.equals(dtb)).toBe(true); + expect(stored.get("bootconfig")?.equals(bootconfig)).toBe(true); +}); + +it("keeps canonically equivalent ramdisk names distinct after normalization", async () => { + const composed = "\u00e9"; + const decomposed = "e\u0301"; + const first = Buffer.from("composed-bytes"); + const second = Buffer.from("decomposed-bytes"); + const path = await writeCarrier( + "vendor_boot.img", + buildVendorBootImage({ + version: 4, + ramdisks: [ + { name: composed, type: 1, bytes: first }, + { name: decomposed, type: 1, bytes: second }, + ], + }), + ); + const snapshot = await scanCanonicalArtifactInventory(path); + const fragments = snapshot.occurrences.filter((row) => + row.logical_path.startsWith("vendor_ramdisk/"), + ); + expect(fragments.map((row) => row.logical_path)).toEqual([ + `vendor_ramdisk/${composed}`, + `vendor_ramdisk/${composed}-1`, + ]); + const hex = (name: string): string => + Buffer.concat([Buffer.from(name, "utf8"), Buffer.alloc(32)]) + .subarray(0, 32) + .toString("hex"); + expect( + fragments.map( + (row) => + (row.format_metadata as { name_bytes_hex?: string }).name_bytes_hex, + ), + ).toEqual([hex(composed), hex(decomposed)]); + const stored = await openAll(path); + expect(stored.get(`vendor_ramdisk/${composed}`)?.equals(first)).toBe(true); + expect(stored.get(`vendor_ramdisk/${composed}-1`)?.equals(second)).toBe(true); +}); + +it("records an AVB footer without treating it as a child", async () => { + const image = buildBootImage({ version: 3, cmdline: "console=tty0" }); + const path = await writeCarrier("avb.img", appendAvbFooter(image)); + const root = (await scanCanonicalArtifactInventory(path)).occurrences.find( + (row) => row.logical_path === ".", + ); + expect(root?.format_metadata).toMatchObject({ + avb_footer_present: true, + avb_footer_size: 64, + avb_version_major: 1, + avb_original_image_size: image.length, + avb_vbmeta_offset: image.length, + command_line: "console=tty0", + }); + const paths = (await openAll(path)).keys(); + expect([...paths]).not.toContain("vbmeta"); + const unrecognized = await writeCarrier( + "trailing.img", + Buffer.concat([image, Buffer.alloc(64)]), + ); + const trailing = ( + await scanCanonicalArtifactInventory(unrecognized) + ).occurrences.find((row) => row.logical_path === "."); + expect(trailing?.format_metadata).toMatchObject({ + avb_footer_present: false, + avb_footer_size: null, + }); +}); + +it("fails closed on truncation and overlapping ranges", async () => { + const truncated = await writeCarrier( + "truncated.img", + truncateImage(buildBootImage({ version: 0 })), + ); + await expect(scanCanonicalArtifactInventory(truncated)).rejects.toThrow( + /truncated/u, + ); + const overlap = await writeCarrier( + "overlap.img", + buildBootImage({ + version: 2, + recoveryDtbo: Buffer.from("dtbo"), + recoveryDtboOffset: 2048, + dtb: Buffer.from("dtb"), + }), + ); + await expect(scanCanonicalArtifactInventory(overlap)).rejects.toThrow( + /overlaps an earlier component/u, + ); + const vendor = buildVendorBootImage({ + version: 4, + ramdisks: [ + { name: "one", type: 1, bytes: Buffer.from("aaa") }, + { name: "two", type: 1, bytes: Buffer.from("bbbbb") }, + ], + }); + const overlapped = Buffer.from(vendor); + const entrySize = overlapped.readUInt32LE(2120); + overlapped.writeUInt32LE(0, 8192 + entrySize + 4); + await expect( + scanCanonicalArtifactInventory( + await writeCarrier("vendor-overlap.img", overlapped), + ), + ).rejects.toThrow(/overlaps entry/u); +}); diff --git a/src/artifacts/AndroidBootImageArtifactReader.ts b/src/artifacts/AndroidBootImageArtifactReader.ts new file mode 100644 index 0000000000..bc84a0a0f1 --- /dev/null +++ b/src/artifacts/AndroidBootImageArtifactReader.ts @@ -0,0 +1,297 @@ +import type { FileHandle } from "node:fs/promises"; +import type { ParseFailureError } from "../domain/parseFailure.js"; + +import { readArtifactFileBytes } from "./ArtifactFileRange.js"; +import { + ArtifactReaderFailure, + artifactFixedLimitFailure, + artifactParseFailure, +} from "../resources/index.js"; +import { + PositionalArtifactReader, + type PositionalArtifactEntries, + type PositionalArtifactEntry, +} from "./PositionalArtifactReader.js"; +import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js"; +import type { + AndroidBootImageEntryMetadata, + AndroidBootImageMetadata, +} from "../domain/artifactFormatMetadata.js"; +import { + ANDROID_BOOT_HEADER_PROBE_BYTES, + ANDROID_BOOT_FIXED_LIMITS, + AVB_FOOTER_SIZE, + compressionFromPrefix, + inspectAvbFooter, + parseAndroidBootHeader, + parseVendorRamdiskTable, + type AndroidBootComponentPlan, + type AndroidBootCompression, + type AndroidBootParse, + type AvbFooterFacts, + type VendorRamdiskTableParse, +} from "./AndroidBootImageFormat.js"; + +type BootEntry = PositionalArtifactEntry & { + readonly formatMetadata: AndroidBootImageEntryMetadata; +}; + +const COMPRESSION_LIMITATION = + "Compression was identified from the leading magic only and the stored bytes were not decompressed."; + +/** Read an Android boot or vendor_boot image without unpacking or verifying it. */ +export class AndroidBootImageArtifactReader extends PositionalArtifactReader { + override readonly format = "android-boot-image" as const; + + constructor(path: string, admitted?: StableRegularFileDescriptor) { + super(path, "Android boot image", admitted); + } + + formatMetadata(): AndroidBootImageMetadata | undefined { + const metadata = this.preparedFormatMetadata; + return metadata === undefined ? undefined : { ...metadata }; + } + + protected override async prepareEntries( + signal?: AbortSignal, + ): Promise> { + const { handle, initial } = await this.verifyCarrier(signal); + const headerBytes = await readArtifactFileBytes( + handle, + 0, + Math.min(initial.size, ANDROID_BOOT_HEADER_PROBE_BYTES), + initial.size, + signal, + ); + this.assertOpen(signal); + const parsed = parseAndroidBootHeader(headerBytes, initial.size); + if (!parsed.ok) throw parseFailure(parsed.error); + const header = parsed.value; + const table = await this.#vendorTable(handle, initial.size, header, signal); + const plans = [...(table?.components ?? []), ...header.components]; + const avb = await this.#footer(handle, initial.size, header, plans, signal); + const compressions = await this.#compression( + handle, + initial.size, + plans, + signal, + ); + const entries = new Map(); + for (const plan of plans) { + const entry = entryFor(plan, compressions.get(plan.path) ?? null); + if (entries.has(entry.adapterKey)) + throw formatFailure(`duplicate component path ${plan.path}`); + entries.set(entry.adapterKey, entry); + } + return { + entries: [...entries.values()], + formatMetadata: toMetadata(header, avb, plans.length), + coverage: { + status: "complete", + limitations: [ + ...header.limitations, + ...(table?.limitations ?? []), + ...avb.limitations, + ], + }, + }; + } + + async #vendorTable( + handle: Pick, + fileSize: number, + header: AndroidBootParse, + signal?: AbortSignal, + ): Promise { + const range = header.tableRange; + if (range === null) return undefined; + const section = header.vendorRamdiskSection; + if ( + section === null || + header.vendorRamdiskTableEntryCount === null || + header.vendorRamdiskTableEntrySize === null + ) + throw formatFailure("vendor ramdisk table is missing its section"); + this.assertOpen(signal); + const bytes = await readArtifactFileBytes( + handle, + range.offset, + range.size, + fileSize, + signal, + ); + const table = parseVendorRamdiskTable(bytes, { + entryCount: header.vendorRamdiskTableEntryCount, + entrySize: header.vendorRamdiskTableEntrySize, + sectionOffset: section.offset, + sectionSize: section.size, + }); + if (!table.ok) throw parseFailure(table.error); + return table.value; + } + + async #footer( + handle: Pick, + fileSize: number, + header: AndroidBootParse, + plans: readonly AndroidBootComponentPlan[], + signal?: AbortSignal, + ): Promise { + const trailing = fileSize - header.imageEnd; + this.assertOpen(signal); + const tail = + trailing >= AVB_FOOTER_SIZE + ? await readArtifactFileBytes( + handle, + fileSize - AVB_FOOTER_SIZE, + AVB_FOOTER_SIZE, + fileSize, + signal, + ) + : null; + const footer = inspectAvbFooter({ + fileSize, + imageEnd: header.imageEnd, + headerOccupied: header.headerOccupied, + components: [ + ...plans, + ...(header.tableRange === null ? [] : [header.tableRange]), + ...(header.vendorRamdiskSection !== null && + header.vendorRamdiskSection.size > 0 + ? [header.vendorRamdiskSection] + : []), + ], + tail, + }); + if (!footer.ok) throw parseFailure(footer.error); + return footer.value; + } + + async #compression( + handle: Pick, + fileSize: number, + plans: readonly AndroidBootComponentPlan[], + signal?: AbortSignal, + ): Promise> { + const observed = new Map(); + for (const plan of plans) { + this.assertOpen(signal); + const prefix = await readArtifactFileBytes( + handle, + plan.offset, + Math.min(4, plan.size), + fileSize, + signal, + ); + observed.set(plan.path, compressionFromPrefix(prefix)); + } + return observed; + } +} + +const formatFailure = ( + detail: string, + options?: ErrorOptions, +): ArtifactReaderFailure => + new ArtifactReaderFailure( + "malformed", + `Android boot image is malformed: ${detail}`, + options, + ); + +const parseFailure = (failure: ParseFailureError): unknown => { + const facts = failure.failure; + if (facts.kind === "limit") { + const ceiling = ANDROID_BOOT_FIXED_LIMITS.get(facts.limit.name); + if (ceiling !== undefined) + return artifactFixedLimitFailure( + { + name: ceiling.name, + kind: "parser", + limit: facts.limit.maximum, + unit: ceiling.unit, + }, + failure.message, + "capacity", + { cause: failure }, + ); + } + return artifactParseFailure(failure, undefined, () => "capacity"); +}; + +const entryFor = ( + plan: AndroidBootComponentPlan, + compression: AndroidBootCompression | null, +): BootEntry => ({ + path: plan.path, + kind: "file", + declaredSize: plan.size, + compressedSize: null, + executable: false, + encrypted: false, + byteOffset: plan.offset, + declaredIntegrity: null, + unpacked: false, + limitations: compression === null ? [] : [COMPRESSION_LIMITATION], + adapterKey: `android-boot-image:${plan.path}`, + formatMetadata: { + kind: "android-boot-image-entry", + role: plan.role, + index: plan.index, + compression, + ramdisk_type: plan.ramdiskType, + ramdisk_type_name: plan.ramdiskTypeName, + load_address: plan.loadAddress, + name_bytes_hex: plan.nameBytesHex, + board_id_hex: plan.boardIdHex, + }, + sourcePath: plan.path, +}); + +const toMetadata = ( + header: AndroidBootParse, + avb: AvbFooterFacts, + componentCount: number, +): AndroidBootImageMetadata => ({ + kind: "android-boot-image", + image_kind: header.imageKind, + magic: header.magic, + header_version: header.headerVersion, + page_size: header.pageSize, + header_size: header.headerSize, + os_version_raw: header.osVersionRaw, + os_version: header.osVersion, + security_patch_level: header.securityPatchLevel, + name: header.name, + name_bytes_hex: header.nameBytesHex, + cmdline: header.cmdline, + cmdline_bytes_hex: header.cmdlineBytesHex, + extra_cmdline: header.extraCmdline, + extra_cmdline_bytes_hex: header.extraCmdlineBytesHex, + command_line: header.commandLine, + header_digest_hex: header.headerDigestHex, + kernel_addr: header.kernelAddr, + ramdisk_addr: header.ramdiskAddr, + second_addr: header.secondAddr, + tags_addr: header.tagsAddr, + dtb_addr: header.dtbAddr, + kernel_size: header.kernelSize, + ramdisk_size: header.ramdiskSize, + second_size: header.secondSize, + recovery_dtbo_size: header.recoveryDtboSize, + recovery_dtbo_offset: header.recoveryDtboOffset, + dtb_size: header.dtbSize, + signature_size: header.signatureSize, + vendor_ramdisk_size: header.vendorRamdiskSize, + vendor_ramdisk_table_entry_count: header.vendorRamdiskTableEntryCount, + vendor_ramdisk_table_entry_size: header.vendorRamdiskTableEntrySize, + bootconfig_size: header.bootconfigSize, + avb_footer_present: avb.present, + avb_footer_size: avb.footerSize, + avb_version_major: avb.versionMajor, + avb_version_minor: avb.versionMinor, + avb_original_image_size: avb.originalImageSize, + avb_vbmeta_offset: avb.vbmetaOffset, + avb_vbmeta_size: avb.vbmetaSize, + component_count: componentCount, +}); diff --git a/src/artifacts/AndroidBootImageFormat.test.ts b/src/artifacts/AndroidBootImageFormat.test.ts new file mode 100644 index 0000000000..26bcd7a446 --- /dev/null +++ b/src/artifacts/AndroidBootImageFormat.test.ts @@ -0,0 +1,602 @@ +import { expect, it } from "vitest"; + +import { + appendAvbFooter, + buildBootImage, + buildVendorBootImage, + declareVendorRamdiskCount, + osVersionRaw, + truncateImage, +} from "../../tests/fixtures/androidBootImage.js"; +import { + compressionFromPrefix, + hasAndroidBootImageMagic, + inspectAvbFooter, + parseAndroidBootHeader, + parseVendorRamdiskTable, +} from "./AndroidBootImageFormat.js"; + +const parsed = (bytes: Buffer, fileSize = bytes.length) => { + const result = parseAndroidBootHeader(bytes.subarray(0, 4096), fileSize); + if (!result.ok) + throw new Error(result.error.message, { cause: result.error }); + return result.value; +}; + +const failed = (bytes: Buffer, fileSize = bytes.length) => { + const result = parseAndroidBootHeader(bytes.subarray(0, 4096), fileSize); + if (result.ok) throw new Error("Expected the header to be refused"); + return result.error; +}; + +it("recognizes ANDROID! and VNDRBOOT and names compression from a prefix", () => { + expect(hasAndroidBootImageMagic(Buffer.from("ANDROID!"))).toBe(true); + expect(hasAndroidBootImageMagic(Buffer.from("VNDRBOOT"))).toBe(true); + expect(hasAndroidBootImageMagic(Buffer.from("short"))).toBe(false); + expect(compressionFromPrefix(Buffer.from([0x1f, 0x8b]))).toBe("gzip"); + expect(compressionFromPrefix(Buffer.from([0x04, 0x22, 0x4d, 0x18]))).toBe( + "lz4", + ); + expect(compressionFromPrefix(Buffer.from([0x02, 0x21, 0x4c, 0x18]))).toBe( + "lz4", + ); + expect(compressionFromPrefix(Buffer.from([0x28, 0xb5, 0x2f, 0xfd]))).toBe( + "zstd", + ); + expect(compressionFromPrefix(Buffer.from("plain"))).toBeNull(); +}); + +it("decodes a v0 command line, OS version, and page-aligned kernel", () => { + const kernel = Buffer.from("kernel"); + const image = buildBootImage({ + version: 0, + kernel, + osVersion: osVersionRaw(13, 0, 0, 2024, 11), + name: "board", + }); + expect(image.subarray(2048, 2048 + kernel.length).equals(kernel)).toBe(true); + const facts = parsed(image); + expect(facts).toMatchObject({ + imageKind: "boot", + magic: "ANDROID!", + headerVersion: 0, + pageSize: 2048, + headerSize: 1632, + osVersionRaw: 436_208_011, + osVersion: "13.0.0", + securityPatchLevel: "2024-11", + name: "board", + commandLine: "console=tty0 androidboot.hardware=test", + kernelSize: kernel.length, + secondSize: 0, + recoveryDtboSize: null, + signatureSize: null, + headerOccupied: 2048, + }); + expect(facts.components.map((item) => item.path)).toEqual([ + "kernel", + "ramdisk", + ]); + expect(facts.components[0]).toMatchObject({ + offset: 2048, + size: kernel.length, + loadAddress: 0x8000_8000, + }); + expect(facts.limitations).toEqual([ + "Command line, board name, and vendor ramdisk names are target-derived and untrusted.", + "ANDROID! covers boot, init_boot, and recovery images; the header does not record which role the file had.", + ]); +}); + +it("keeps a split UTF-8 name as hex and a non-calendar patch month as raw", () => { + const image = buildBootImage({ + version: 0, + name: "测".repeat(6), + osVersion: osVersionRaw(13, 0, 0, 2024, 13), + }); + const facts = parsed(image); + expect(facts.name).toBeNull(); + expect(facts.nameBytesHex).toBe(image.subarray(48, 64).toString("hex")); + expect(facts.osVersion).toBe("13.0.0"); + expect(facts.securityPatchLevel).toBeNull(); + expect(facts.limitations.join(" ")).toContain("security patch month 13"); +}); + +it("places a v2 DTB after the recovery DTBO and rejects an overlapping offset", () => { + const dtb = Buffer.from("dtb-bytes"); + const recovery = Buffer.from("dtbo"); + const image = buildBootImage({ + version: 2, + kernel: Buffer.from("kernel"), + ramdisk: Buffer.alloc(0), + recoveryDtbo: recovery, + dtb, + }); + expect(image.subarray(2048, 2054).equals(Buffer.from("kernel"))).toBe(true); + const facts = parsed(image); + const dtbo = facts.components.find((item) => item.role === "recovery-dtbo"); + const dtbPlan = facts.components.find((item) => item.role === "dtb"); + expect(dtbo).toMatchObject({ path: "recovery_dtbo", offset: 4096 }); + expect(dtbPlan).toMatchObject({ + path: "dtb", + offset: 6144, + size: dtb.length, + loadAddress: 0x8200_0000, + }); + expect(image.subarray(6144, 6144 + dtb.length).equals(dtb)).toBe(true); + const overlap = buildBootImage({ + version: 2, + recoveryDtbo: recovery, + recoveryDtboOffset: 2048, + dtb, + }); + expect(failed(overlap).message).toContain( + "recovery_dtbo overlaps an earlier component", + ); +}); + +it("rejects an unsupported version, a bad page size, and a truncated image", () => { + const version = buildBootImage({ version: 0 }); + version.writeUInt32LE(5, 40); + expect(failed(version)).toMatchObject({ + kind: "unsupported", + failure: { + format: "android-boot-image", + field: "header_version", + offset: 40, + }, + message: "header version 5 is unsupported", + }); + const page = buildBootImage({ version: 0 }); + page.writeUInt32LE(1024, 36); + expect(failed(page)).toMatchObject({ + kind: "malformed", + message: expect.stringContaining("page size 1024"), + }); + const vendor = buildVendorBootImage({ version: 4 }); + vendor.writeUInt32LE(5, 8); + expect(failed(vendor)).toMatchObject({ + kind: "unsupported", + failure: { + format: "android-boot-image", + field: "header_version", + offset: 8, + }, + }); + expect(failed(Buffer.from("ANDROID!"))).toMatchObject({ kind: "truncated" }); + expect(failed(truncateImage(buildBootImage({ version: 0 })))).toMatchObject({ + kind: "truncated", + failure: { format: "android-boot-image" }, + }); +}); + +it("aligns a kernel larger than 2^31 without allocating the image", () => { + const header = Buffer.alloc(1632); + header.write("ANDROID!", 0, "ascii"); + header.writeUInt32LE(0x8000_0001, 8); + header.writeUInt32LE(2048, 36); + const result = parseAndroidBootHeader(header, Number.MAX_SAFE_INTEGER); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.components).toEqual([ + expect.objectContaining({ + role: "kernel", + path: "kernel", + offset: 2048, + size: 0x8000_0001, + }), + ]); + expect(result.value.imageEnd).toBe(0x8000_1000); +}); + +it("decodes a legacy command line whose UTF-8 character straddles the 512-byte split", () => { + const image = buildBootImage({ version: 0, cmdline: "", extraCmdline: "" }); + const joined = Buffer.from(`${"a".repeat(511)}\u00e9 quiet`, "utf8"); + joined.copy(image, 64, 0, 512); + joined.copy(image, 608, 512); + const facts = parsed(image); + expect(facts.cmdline).toBeNull(); + expect(facts.extraCmdline).toBeNull(); + expect(facts.cmdlineBytesHex).toBe(joined.subarray(0, 512).toString("hex")); + expect(facts.commandLine).toBe(`${"a".repeat(511)}\u00e9 quiet`); +}); + +it("keeps a legacy command line null when the joined bytes are invalid UTF-8", () => { + const image = buildBootImage({ version: 0, cmdline: "", extraCmdline: "" }); + Buffer.from("a".repeat(511), "utf8").copy(image, 64); + image[575] = 0xc3; + image[608] = 0x41; + expect(parsed(image).commandLine).toBeNull(); +}); + +it("decodes v3 and v4 boot images with a fixed 4096-byte page", () => { + const kernel = Buffer.from("kern"); + const v3 = parsed( + buildBootImage({ + version: 3, + kernel, + ramdisk: Buffer.from([0x1f, 0x8b, 1]), + cmdline: "console=tty0", + }), + ); + expect(v3).toMatchObject({ + headerVersion: 3, + pageSize: 4096, + headerSize: 1580, + name: null, + kernelAddr: null, + extraCmdline: null, + headerDigestHex: null, + signatureSize: null, + commandLine: "console=tty0", + }); + expect(v3.components.map((item) => item.offset)).toEqual([4096, 8192]); + expect(v3.cmdlineBytesHex).toHaveLength(3072); + const signature = Buffer.from("sig"); + const v4 = parsed( + buildBootImage({ + version: 4, + kernel, + ramdisk: Buffer.alloc(0), + signature, + }), + ); + expect(v4.signatureSize).toBe(signature.length); + expect(v4.components.map((item) => item.role)).toEqual([ + "kernel", + "signature", + ]); + expect(v4.components[1]).toMatchObject({ offset: 8192, path: "signature" }); +}); + +it("splits a v4 vendor ramdisk table and a v3 section", () => { + const first = Buffer.from("aaa"); + const second = Buffer.from("bbbbb"); + const dtb = Buffer.from("dtb"); + const bootconfig = Buffer.from("androidboot.serialno=abc\n"); + const boardId = Buffer.alloc(64, 0x11); + boardId.writeUInt32LE(0x11223344, 0); + const longName = "platform-ramdisk-name-exceeds-32b"; + const storedName = longName.slice(0, 32); + const image = buildVendorBootImage({ + version: 4, + ramdisks: [ + { name: longName, type: 1, bytes: first, boardId }, + { name: "platform", type: 2, bytes: second }, + ], + dtb, + bootconfig, + }); + expect(image.subarray(4096, 4099).equals(first)).toBe(true); + const facts = parsed(image); + expect(facts).toMatchObject({ + imageKind: "vendor-boot", + magic: "VNDRBOOT", + headerVersion: 4, + pageSize: 4096, + osVersion: null, + vendorRamdiskSize: 8, + vendorRamdiskTableEntryCount: 2, + vendorRamdiskTableEntrySize: 108, + bootconfigSize: bootconfig.length, + }); + expect(facts.cmdlineBytesHex).toHaveLength(4096); + expect(facts.tableRange).toEqual({ offset: 12288, size: 216 }); + const table = facts.tableRange; + const section = facts.vendorRamdiskSection; + if (table === null || section === null) throw new Error("missing table"); + expect( + image.subarray(table.offset + 12, table.offset + 44).toString("utf8"), + ).toBe(storedName); + expect( + image.subarray(table.offset + 44, table.offset + 108).equals(boardId), + ).toBe(true); + const rows = parseVendorRamdiskTable( + image.subarray(table.offset, table.offset + table.size), + { + entryCount: 2, + entrySize: 108, + sectionOffset: section.offset, + sectionSize: section.size, + }, + ); + expect(rows.ok, JSON.stringify(rows)).toBe(true); + if (!rows.ok) return; + expect(rows.value.components.map((item) => item.path)).toEqual([ + `vendor_ramdisk/${storedName}`, + "vendor_ramdisk/platform", + ]); + expect(rows.value.components[0]?.nameBytesHex).toHaveLength(64); + expect(rows.value.components[0]?.boardIdHex).toBe(boardId.toString("hex")); + expect(rows.value.components[0]).toMatchObject({ + ramdiskType: 1, + ramdiskTypeName: "platform", + offset: 4096, + size: first.length, + }); + expect(rows.value.components.map((item) => item.loadAddress)).toEqual([ + null, + null, + ]); + const v3 = buildVendorBootImage({ + version: 3, + pageSize: 2048, + ramdisk: Buffer.from("ram"), + }); + expect(v3.subarray(4096, 4099).equals(Buffer.from("ram"))).toBe(true); + expect(parsed(v3).components).toEqual([ + expect.objectContaining({ + path: "vendor_ramdisk", + offset: 4096, + size: 3, + loadAddress: 0x8100_0000, + }), + ]); +}); + +it("rejects vendor table overlap, overrun, and an excessive entry count", () => { + const image = buildVendorBootImage({ + version: 4, + ramdisks: [ + { name: "one", type: 1, bytes: Buffer.from("aaa") }, + { name: "two", type: 1, bytes: Buffer.from("bbbbb") }, + ], + }); + const facts = parsed(image); + const table = facts.tableRange; + const section = facts.vendorRamdiskSection; + const entrySize = facts.vendorRamdiskTableEntrySize; + if ( + table === null || + section === null || + entrySize === null || + facts.vendorRamdiskTableEntryCount === null + ) + throw new Error("missing table"); + const input = { + entryCount: facts.vendorRamdiskTableEntryCount, + entrySize, + sectionOffset: section.offset, + sectionSize: section.size, + }; + const rows = (source: Buffer) => + parseVendorRamdiskTable( + source.subarray(table.offset, table.offset + table.size), + input, + ); + const overlap = Buffer.from(image); + const short = rows(image.subarray(0, table.offset + table.size - 1)); + if (short.ok) throw new Error("Expected a truncated ramdisk table"); + expect(short.error).toMatchObject({ + kind: "truncated", + failure: { field: "vendor ramdisk table" }, + }); + overlap.writeUInt32LE(0, table.offset + entrySize + 4); + const overlapped = rows(overlap); + expect(overlapped.ok).toBe(false); + if (overlapped.ok) return; + expect(overlapped.error.message).toContain("overlaps entry"); + const overrun = Buffer.from(image); + overrun.writeUInt32LE(100, table.offset); + const overran = rows(overrun); + expect(overran.ok).toBe(false); + if (overran.ok) return; + expect(overran.error.message).toContain("overruns the vendor ramdisk"); + const capacity = failed( + declareVendorRamdiskCount(buildVendorBootImage({ version: 4 }), 4097), + ); + expect(capacity).toMatchObject({ + kind: "limit", + failure: { + format: "android-boot-image", + limit: { + name: "Android vendor ramdisk table entry count", + maximum: 4096, + }, + }, + }); + expect(capacity.message).toContain("4096"); + expect( + failed( + buildVendorBootImage({ + version: 4, + entrySize: 107, + ramdisks: [{ name: "short", bytes: Buffer.from("abcd") }], + }), + ).message, + ).toContain("smaller than the 108-byte"); +}); + +it("names unsafe vendor ramdisk paths and reports an uncovered section", () => { + const entry = (name: string, offset: number): Buffer => { + const row = Buffer.alloc(108); + row.writeUInt32LE(4, 0); + row.writeUInt32LE(offset, 4); + Buffer.from(name, "utf8").copy(row, 12); + return row; + }; + const table = Buffer.concat([ + entry("a/b", 0), + entry(".", 4), + entry("same", 8), + entry("same", 12), + ]); + const result = parseVendorRamdiskTable(table, { + entryCount: 4, + entrySize: 108, + sectionOffset: 4096, + sectionSize: 16, + }); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.components.map((item) => item.path)).toEqual([ + "vendor_ramdisk/ramdisk-0", + "vendor_ramdisk/ramdisk-1", + "vendor_ramdisk/same", + "vendor_ramdisk/same-3", + ]); + const uncovered = parsed( + buildVendorBootImage({ + version: 4, + section: Buffer.from("uncovered-section"), + }), + ); + expect(uncovered.components).toEqual([]); + expect(uncovered.limitations.join(" ")).toContain( + "outside the ramdisk table", + ); + const wide = Buffer.alloc(208); + wide.writeUInt32LE(4, 0); + const wideRows = parseVendorRamdiskTable(wide, { + entryCount: 1, + entrySize: 208, + sectionOffset: 4096, + sectionSize: 4, + }); + expect(wideRows.ok, JSON.stringify(wideRows)).toBe(true); + if (!wideRows.ok) return; + expect(wideRows.value.limitations.join(" ")).toContain("108-byte"); + expect(wideRows.value.components[0]?.nameBytesHex).toHaveLength(64); + expect(wideRows.value.components[0]?.boardIdHex).toHaveLength(128); +}); + +it("omits empty vendor ramdisk fragments instead of rejecting the table", () => { + const entry = (name: string, size: number, offset: number): Buffer => { + const row = Buffer.alloc(108); + row.writeUInt32LE(size, 0); + row.writeUInt32LE(offset, 4); + Buffer.from(name, "utf8").copy(row, 12); + return row; + }; + const input = { + entryCount: 3, + entrySize: 108, + sectionOffset: 4096, + sectionSize: 8, + }; + const result = parseVendorRamdiskTable( + Buffer.concat([entry("one", 4, 0), entry("gap", 0, 4), entry("two", 4, 4)]), + input, + ); + expect(result.ok, JSON.stringify(result)).toBe(true); + if (!result.ok) return; + expect(result.value.components.map((item) => item.path)).toEqual([ + "vendor_ramdisk/one", + "vendor_ramdisk/two", + ]); + expect(result.value.limitations.join(" ")).toContain( + "entries 1 declare no bytes", + ); + const outside = parseVendorRamdiskTable( + Buffer.concat([entry("one", 4, 0), entry("gap", 0, 9), entry("two", 4, 4)]), + input, + ); + expect(outside.ok).toBe(false); + if (outside.ok) return; + expect(outside.error.message).toContain("overruns the vendor ramdisk"); +}); + +it("keeps colliding vendor ramdisk names unique", () => { + const entry = (name: string, offset: number): Buffer => { + const row = Buffer.alloc(108); + row.writeUInt32LE(4, 0); + row.writeUInt32LE(offset, 4); + Buffer.from(name, "utf8").copy(row, 12); + return row; + }; + const paths = (names: readonly string[]) => { + const table = Buffer.concat( + names.map((name, index) => entry(name, index * 4)), + ); + const result = parseVendorRamdiskTable(table, { + entryCount: names.length, + entrySize: 108, + sectionOffset: 4096, + sectionSize: names.length * 4, + }); + if (!result.ok) + throw new Error(result.error.message, { cause: result.error }); + return result.value.components.map((item) => item.path); + }; + expect(paths(["x", "x-2", "x"])).toEqual([ + "vendor_ramdisk/x", + "vendor_ramdisk/x-2", + "vendor_ramdisk/x-2-2", + ]); + expect(paths(["ramdisk-1", ""])).toEqual([ + "vendor_ramdisk/ramdisk-1", + "vendor_ramdisk/ramdisk-1-1", + ]); + expect(paths(["ramdisk-2", "ramdisk-2-2", "a/b"])).toEqual([ + "vendor_ramdisk/ramdisk-2", + "vendor_ramdisk/ramdisk-2-2", + "vendor_ramdisk/ramdisk-2-2-2", + ]); +}); + +it("records an AVB footer and rejects vbmeta that overlaps a component", () => { + const image = buildBootImage({ + version: 0, + kernel: Buffer.alloc(64, 1), + ramdisk: Buffer.alloc(0), + }); + const facts = parsed(image); + const happy = appendAvbFooter(image); + const footer = inspectAvbFooter({ + fileSize: happy.length, + imageEnd: facts.imageEnd, + headerOccupied: facts.headerOccupied, + components: facts.components, + tail: happy.subarray(happy.length - 64), + }); + expect(footer).toMatchObject({ + ok: true, + value: { + present: true, + footerSize: 64, + versionMajor: 1, + versionMinor: 0, + originalImageSize: image.length, + vbmetaOffset: image.length, + limitations: [], + }, + }); + const bare = inspectAvbFooter({ + fileSize: image.length, + imageEnd: facts.imageEnd, + headerOccupied: facts.headerOccupied, + components: facts.components, + tail: null, + }); + expect(bare).toMatchObject({ + ok: true, + value: { present: false, limitations: [] }, + }); + const short = Buffer.concat([image, Buffer.alloc(10)]); + const shortFooter = inspectAvbFooter({ + fileSize: short.length, + imageEnd: facts.imageEnd, + headerOccupied: facts.headerOccupied, + components: facts.components, + tail: null, + }); + expect(shortFooter.ok).toBe(true); + if (!shortFooter.ok) return; + expect(shortFooter.value.limitations[0]).toContain("10 trailing bytes"); + const colliding = appendAvbFooter(image, { + vbmetaOffset: 2048, + vbmeta: Buffer.alloc(16), + }); + const collision = inspectAvbFooter({ + fileSize: colliding.length, + imageEnd: facts.imageEnd, + headerOccupied: facts.headerOccupied, + components: facts.components, + tail: colliding.subarray(colliding.length - 64), + }); + expect(collision.ok).toBe(false); + if (collision.ok) return; + expect(collision.error.message).toContain( + "AVB vbmeta overlaps a component at offset 2048", + ); +}); diff --git a/src/artifacts/AndroidBootImageFormat.ts b/src/artifacts/AndroidBootImageFormat.ts new file mode 100644 index 0000000000..9badf398fc --- /dev/null +++ b/src/artifacts/AndroidBootImageFormat.ts @@ -0,0 +1,1179 @@ +import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; +import { logicalPathNfc } from "../domain/artifactIdentity.js"; +import { err, ok, type Result } from "../domain/result.js"; +import { + ANDROID_BOOT_MAGIC, + VENDOR_BOOT_MAGIC, + hasAndroidBootImageMagic, +} from "../domain/androidBootImageFormat.js"; +import { + decodeLimit, + malformedInput, + ParseFailureError, + truncatedInput, + unsupportedInput, + type LimitRef, +} from "../domain/parseFailure.js"; +import { BinaryReader } from "../domain/binaryContainer.js"; + +export { hasAndroidBootImageMagic }; + +/** + * Android boot (`ANDROID!`, versions 0-4) and vendor boot (`VNDRBOOT`, + * versions 3-4) headers. Multi-byte header fields are little-endian. + * Component bytes are located and bounded here; they are not decompressed, + * executed, or signature-checked. + */ +export const ANDROID_BOOT_HEADER_PROBE_BYTES = 4096; +export const AVB_FOOTER_SIZE = 64; +const ANDROID_BOOT_MAGIC_BYTES = Buffer.from(ANDROID_BOOT_MAGIC); +const VENDOR_BOOT_MAGIC_BYTES = Buffer.from(VENDOR_BOOT_MAGIC); +const AVB_FOOTER_MAGIC_BYTES = Buffer.from("AVBf"); +const BOOT_V3_PAGE_SIZE = 4096; +const LEGACY_V0_SIZE = 1632; +const LEGACY_V1_SIZE = 1648; +const LEGACY_V2_SIZE = 1660; +const MODERN_V3_SIZE = 1580; +const MODERN_V4_SIZE = 1584; +const VENDOR_V3_SIZE = 2112; +const VENDOR_V4_SIZE = 2128; +// v4 entry: size, offset, type, 32-byte name, 16 board-id words (108 bytes). +const VENDOR_RAMDISK_ENTRY_SIZE = 108; +const MAX_VENDOR_RAMDISKS = 4096; +const MAX_RAMDISK_ENTRY_SIZE = 4096; +const MAX_HEADER_SIZE = 1024 * 1024; +const PAGE_MIN = 2048; +const PAGE_MAX = 65536; +const NAME_SIZE = 16; +const BOOT_ARGS_SIZE = 512; +const BOOT_EXTRA_ARGS_SIZE = 1024; +const VENDOR_ARGS_SIZE = 2048; +const RAMDISK_NAME_SIZE = 32; +const BOARD_ID_BYTES = 64; +const BOARD_ID_OFFSET = 12 + RAMDISK_NAME_SIZE; + +export type AndroidBootCompression = "gzip" | "lz4" | "zstd"; + +export interface AndroidBootComponentPlan { + readonly role: + | "kernel" + | "ramdisk" + | "second" + | "recovery-dtbo" + | "dtb" + | "vendor-ramdisk" + | "bootconfig" + | "signature"; + readonly path: string; + readonly index: number; + readonly offset: number; + readonly size: number; + readonly loadAddress: number | null; + readonly ramdiskType: number | null; + readonly ramdiskTypeName: string | null; + readonly nameBytesHex: string | null; + readonly boardIdHex: string | null; +} + +export interface AndroidBootParse { + readonly imageKind: "boot" | "vendor-boot"; + readonly magic: typeof ANDROID_BOOT_MAGIC | typeof VENDOR_BOOT_MAGIC; + readonly headerVersion: number; + readonly pageSize: number; + readonly headerSize: number; + /** Bytes occupied by the page-aligned header before the first component. */ + readonly headerOccupied: number; + readonly osVersionRaw: number | null; + readonly osVersion: string | null; + readonly securityPatchLevel: string | null; + readonly name: string | null; + readonly nameBytesHex: string | null; + readonly cmdline: string | null; + readonly cmdlineBytesHex: string; + readonly extraCmdline: string | null; + readonly extraCmdlineBytesHex: string | null; + readonly commandLine: string | null; + readonly headerDigestHex: string | null; + readonly kernelAddr: number | null; + readonly ramdiskAddr: number | null; + readonly secondAddr: number | null; + readonly tagsAddr: number | null; + readonly dtbAddr: number | null; + readonly kernelSize: number | null; + readonly ramdiskSize: number | null; + readonly secondSize: number | null; + readonly recoveryDtboSize: number | null; + readonly recoveryDtboOffset: number | null; + readonly dtbSize: number | null; + readonly signatureSize: number | null; + readonly vendorRamdiskSize: number | null; + readonly vendorRamdiskTableEntryCount: number | null; + readonly vendorRamdiskTableEntrySize: number | null; + readonly bootconfigSize: number | null; + readonly components: readonly AndroidBootComponentPlan[]; + readonly imageEnd: number; + readonly limitations: readonly string[]; + readonly tableRange: { + readonly offset: number; + readonly size: number; + } | null; + readonly vendorRamdiskSection: { + readonly offset: number; + readonly size: number; + } | null; +} + +export interface VendorRamdiskTableParse { + readonly components: readonly AndroidBootComponentPlan[]; + readonly limitations: readonly string[]; +} + +export interface AvbFooterFacts { + readonly present: boolean; + readonly footerSize: typeof AVB_FOOTER_SIZE | null; + readonly versionMajor: number | null; + readonly versionMinor: number | null; + readonly originalImageSize: number | null; + readonly vbmetaOffset: number | null; + readonly vbmetaSize: number | null; + readonly limitations: readonly string[]; +} + +/** The ParseFailure format of an Android boot or vendor boot image. */ +const ANDROID_BOOT_FORMAT = "android-boot-image"; + +const formatError = (message: string): never => { + throw malformedInput(ANDROID_BOOT_FORMAT, message); +}; + +const capacityError = (message: string, limit: LimitRef): never => { + throw decodeLimit(ANDROID_BOOT_FORMAT, message, limit); +}; + +const HEADER_SIZE_LIMIT = { + name: "Android boot image header_size", + maximum: MAX_HEADER_SIZE, + unit: "bytes", +}; +const VENDOR_RAMDISK_COUNT_LIMIT = { + name: "Android vendor ramdisk table entry count", + maximum: MAX_VENDOR_RAMDISKS, + unit: "entries", +}; +const VENDOR_RAMDISK_ENTRY_SIZE_LIMIT = { + name: "Android vendor ramdisk table entry size", + maximum: MAX_RAMDISK_ENTRY_SIZE, + unit: "bytes", +}; +/** Parser-owned fixed ceilings and their units for artifact recovery. */ +export const ANDROID_BOOT_FIXED_LIMITS: ReadonlyMap< + string, + LimitRef & { readonly unit: string } +> = new Map([ + [HEADER_SIZE_LIMIT.name, HEADER_SIZE_LIMIT], + [VENDOR_RAMDISK_COUNT_LIMIT.name, VENDOR_RAMDISK_COUNT_LIMIT], + [VENDOR_RAMDISK_ENTRY_SIZE_LIMIT.name, VENDOR_RAMDISK_ENTRY_SIZE_LIMIT], +]); + +const parsed = (read: () => T): Result => { + try { + return ok(read()); + } catch (cause) { + if (!(cause instanceof ParseFailureError)) throw cause; + return err(cause); + } +}; + +const requireBytes = (buffer: Buffer, length: number, what: string): void => { + if (buffer.length < length) + throw truncatedInput( + ANDROID_BOOT_FORMAT, + `${what} is truncated: ${buffer.length} bytes available, at least ${length} required`, + { offset: buffer.length, field: what }, + ); +}; + +const u32 = (buffer: Buffer, offset: number): number => { + requireBytes(buffer, offset + 4, "header"); + return new BinaryReader(buffer, true, ANDROID_BOOT_FORMAT).u32(offset); +}; + +const u64 = (buffer: Buffer, offset: number, what: string): number => { + requireBytes(buffer, offset + 8, what); + const reader = new BinaryReader(buffer, true, ANDROID_BOOT_FORMAT); + const low = reader.u32(offset); + const high = reader.u32(offset + 4); + if (high > 0x1f_ffff) formatError(`${what} exceeds a safe integer`); + return high * 0x1_0000_0000 + low; +}; + +const u64be = (buffer: Buffer, offset: number, what: string): number => { + requireBytes(buffer, offset + 8, what); + const reader = new BinaryReader(buffer, false, ANDROID_BOOT_FORMAT); + const high = reader.u32(offset); + const low = reader.u32(offset + 4); + if (high > 0x1f_ffff) formatError(`${what} exceeds a safe integer`); + return high * 0x1_0000_0000 + low; +}; + +const alignUp = (value: number, page: number): number => { + if (!Number.isSafeInteger(value) || value < 0) + formatError("a component extent is not a safe nonnegative integer"); + const remainder = value % page; + if (remainder === 0) return value; + const aligned = value + (page - remainder); + if (!Number.isSafeInteger(aligned)) + formatError("a page-aligned component extent is not a safe integer"); + return aligned; +}; + +const endOf = (offset: number, size: number): number => { + if ( + !Number.isSafeInteger(offset) || + !Number.isSafeInteger(size) || + offset < 0 || + size < 0 + ) + formatError("a component range is not a safe nonnegative extent"); + const end = offset + size; + if (!Number.isSafeInteger(end)) + formatError("a component range overflows a safe integer"); + return end; +}; + +const requirePageSize = (value: number): number => { + if ( + !Number.isInteger(value) || + value < PAGE_MIN || + value > PAGE_MAX || + (value & (value - 1)) !== 0 + ) + formatError( + `page size ${value} is not a power of two from 2048 through 65536`, + ); + return value; +}; + +const requireHeaderSize = ( + value: number, + minimum: number, + maximum: number, +): number => { + if (value > MAX_HEADER_SIZE) + capacityError( + `header_size ${value} exceeds the ${MAX_HEADER_SIZE} byte header bound`, + HEADER_SIZE_LIMIT, + ); + if (!Number.isInteger(value) || value < minimum || value > maximum) + formatError( + `header_size ${value} is outside the supported range ${minimum} through ${maximum}`, + ); + return value; +}; + +const requireFileCovers = (fileSize: number, imageEnd: number): void => { + if (!Number.isSafeInteger(fileSize) || fileSize < 0) + formatError("file size is not a safe nonnegative integer"); + if (imageEnd > fileSize) + throw truncatedInput( + ANDROID_BOOT_FORMAT, + `image is truncated: components end at byte ${imageEnd} but the file is ${fileSize} bytes`, + { offset: fileSize, field: "components" }, + ); +}; + +const untilNul = (bytes: Buffer): Buffer => { + const nul = bytes.indexOf(0); + return nul === -1 ? bytes : bytes.subarray(0, nul); +}; + +const decodeText = (bytes: Buffer): string | null => { + try { + return decodeStrictUtf8(bytes, "preserve"); + } catch { + return null; + } +}; + +const decodeField = ( + bytes: Buffer, +): { readonly text: string | null; readonly hex: string } => ({ + text: decodeText(untilNul(bytes)), + hex: bytes.toString("hex"), +}); + +const commandFields = ( + cmdlineBytes: Buffer, + extraBytes: Buffer | null, +): Pick< + AndroidBootParse, + | "cmdline" + | "cmdlineBytesHex" + | "extraCmdline" + | "extraCmdlineBytesHex" + | "commandLine" +> => { + const cmdline = decodeField(cmdlineBytes); + const extra = extraBytes === null ? null : decodeField(extraBytes); + return { + cmdline: cmdline.text, + cmdlineBytesHex: cmdline.hex, + extraCmdline: extra?.text ?? null, + extraCmdlineBytesHex: extra?.hex ?? null, + // A multibyte character can straddle the cmdline/extra_cmdline split, + // so the joined line is decoded from the joined bytes. + commandLine: + extraBytes === null + ? cmdline.text + : decodeText( + Buffer.concat([untilNul(cmdlineBytes), untilNul(extraBytes)]), + ), + }; +}; + +const decodeOsVersion = ( + raw: number, +): { + readonly osVersion: string | null; + readonly securityPatchLevel: string | null; + readonly limitation: string | null; +} => { + const major = (raw >>> 25) & 0x7f; + const minor = (raw >>> 18) & 0x7f; + const patch = (raw >>> 11) & 0x7f; + const year = (raw >>> 4) & 0x7f; + const month = raw & 0xf; + const osVersion = + major === 0 && minor === 0 && patch === 0 + ? null + : `${String(major)}.${String(minor)}.${String(patch)}`; + if (year === 0 && month === 0) + return { osVersion, securityPatchLevel: null, limitation: null }; + if (month < 1 || month > 12) + return { + osVersion, + securityPatchLevel: null, + limitation: `security patch month ${String(month)} is not a calendar month; the raw os_version field is retained`, + }; + const monthText = String(month).padStart(2, "0"); + return { + osVersion, + securityPatchLevel: `${String(2000 + year)}-${monthText}`, + limitation: null, + }; +}; + +const baseLimitations = ( + imageKind: AndroidBootParse["imageKind"], +): string[] => [ + "Command line, board name, and vendor ramdisk names are target-derived and untrusted.", + ...(imageKind === "boot" + ? [ + "ANDROID! covers boot, init_boot, and recovery images; the header does not record which role the file had.", + ] + : []), +]; + +const component = ( + role: AndroidBootComponentPlan["role"], + path: string, + offset: number, + size: number, + loadAddress: number | null, + extra?: Partial< + Pick< + AndroidBootComponentPlan, + | "index" + | "ramdiskType" + | "ramdiskTypeName" + | "nameBytesHex" + | "boardIdHex" + > + >, +): AndroidBootComponentPlan => ({ + role, + path, + index: extra?.index ?? 0, + offset, + size, + loadAddress, + ramdiskType: extra?.ramdiskType ?? null, + ramdiskTypeName: extra?.ramdiskTypeName ?? null, + nameBytesHex: extra?.nameBytesHex ?? null, + boardIdHex: extra?.boardIdHex ?? null, +}); + +const place = ( + components: AndroidBootComponentPlan[], + cursor: number, + page: number, + planned: AndroidBootComponentPlan | null, +): number => { + if (planned === null || planned.size === 0) return cursor; + components.push(planned); + return alignUp(endOf(cursor, planned.size), page); +}; + +const bootParse = ( + fields: Pick< + AndroidBootParse, + | "imageKind" + | "magic" + | "headerVersion" + | "pageSize" + | "headerSize" + | "headerOccupied" + | "cmdlineBytesHex" + | "components" + | "imageEnd" + | "limitations" + > & + Partial, +): AndroidBootParse => ({ + osVersionRaw: null, + osVersion: null, + securityPatchLevel: null, + name: null, + nameBytesHex: null, + cmdline: null, + extraCmdline: null, + extraCmdlineBytesHex: null, + commandLine: null, + headerDigestHex: null, + kernelAddr: null, + ramdiskAddr: null, + secondAddr: null, + tagsAddr: null, + dtbAddr: null, + kernelSize: null, + ramdiskSize: null, + secondSize: null, + recoveryDtboSize: null, + recoveryDtboOffset: null, + dtbSize: null, + signatureSize: null, + vendorRamdiskSize: null, + vendorRamdiskTableEntryCount: null, + vendorRamdiskTableEntrySize: null, + bootconfigSize: null, + tableRange: null, + vendorRamdiskSection: null, + ...fields, +}); + +const RAMDISK_TYPE_NAMES: Readonly> = { + 0: "none", + 1: "platform", + 2: "recovery", + 3: "dlkm", +}; + +const ramdiskTypeName = (value: number): string => + RAMDISK_TYPE_NAMES[value] ?? "unknown"; + +const hasPrefix = (buffer: Buffer, bytes: readonly number[]): boolean => + buffer.length >= bytes.length && + bytes.every((byte, index) => buffer[index] === byte); + +/** gzip, lz4 frame, lz4 legacy, or zstd magic. Other prefixes stay unknown. */ +export const compressionFromPrefix = ( + prefix: Buffer, +): AndroidBootCompression | null => { + if (hasPrefix(prefix, [0x1f, 0x8b])) return "gzip"; + if (hasPrefix(prefix, [0x04, 0x22, 0x4d, 0x18])) return "lz4"; + if (hasPrefix(prefix, [0x02, 0x21, 0x4c, 0x18])) return "lz4"; + if (hasPrefix(prefix, [0x28, 0xb5, 0x2f, 0xfd])) return "zstd"; + return null; +}; + +const legacyStructSize = (version: number): number => { + if (version === 0) return LEGACY_V0_SIZE; + if (version === 1) return LEGACY_V1_SIZE; + return LEGACY_V2_SIZE; +}; + +const layoutLegacyTail = ( + prefix: Buffer, + version: number, + page: number, + cursor: number, + components: AndroidBootComponentPlan[], + limitations: string[], +): { + readonly cursor: number; + readonly recoveryDtboSize: number | null; + readonly recoveryDtboOffset: number | null; + readonly dtbSize: number | null; + readonly dtbAddr: number | null; +} => { + if (version < 1) + return { + cursor, + recoveryDtboSize: null, + recoveryDtboOffset: null, + dtbSize: null, + dtbAddr: null, + }; + const recoveryDtboSize = u32(prefix, LEGACY_V0_SIZE); + const recoveryDtboOffset = u64( + prefix, + LEGACY_V0_SIZE + 4, + "recovery_dtbo offset", + ); + let next = cursor; + if (recoveryDtboSize > 0) { + if (recoveryDtboOffset % page !== 0) + formatError( + `recovery_dtbo offset ${recoveryDtboOffset} is not aligned to page size ${page}`, + ); + endOf(recoveryDtboOffset, recoveryDtboSize); + if (recoveryDtboOffset < cursor) + formatError("recovery_dtbo overlaps an earlier component"); + if (recoveryDtboOffset > cursor) + limitations.push( + "Bytes between the sequential layout and recovery_dtbo were not exposed as entries.", + ); + components.push( + component( + "recovery-dtbo", + "recovery_dtbo", + recoveryDtboOffset, + recoveryDtboSize, + null, + ), + ); + next = alignUp(endOf(recoveryDtboOffset, recoveryDtboSize), page); + } + if (version < 2) + return { + cursor: next, + recoveryDtboSize, + recoveryDtboOffset, + dtbSize: null, + dtbAddr: null, + }; + const dtbSize = u32(prefix, LEGACY_V1_SIZE); + const dtbAddr = u64(prefix, LEGACY_V1_SIZE + 4, "dtb address"); + return { + cursor: place( + components, + next, + page, + dtbSize === 0 ? null : component("dtb", "dtb", next, dtbSize, dtbAddr), + ), + recoveryDtboSize, + recoveryDtboOffset, + dtbSize, + dtbAddr, + }; +}; + +const parseLegacyBoot = ( + prefix: Buffer, + fileSize: number, + headerVersion: number, +): AndroidBootParse => { + const structSize = legacyStructSize(headerVersion); + requireBytes(prefix, structSize, "header"); + const pageSize = requirePageSize(u32(prefix, 36)); + const headerSize = + headerVersion === 0 + ? LEGACY_V0_SIZE + : requireHeaderSize( + u32(prefix, LEGACY_V1_SIZE - 4), + structSize, + pageSize, + ); + const limitations = baseLimitations("boot"); + if (headerVersion > 0 && headerSize > structSize) + limitations.push( + `Header bytes after the v${String(headerVersion)} structure were not decoded.`, + ); + const osRaw = u32(prefix, 44); + const os = decodeOsVersion(osRaw); + if (os.limitation !== null) limitations.push(os.limitation); + const name = decodeField(prefix.subarray(48, 48 + NAME_SIZE)); + const commands = commandFields( + prefix.subarray(64, 64 + BOOT_ARGS_SIZE), + prefix.subarray(608, 608 + BOOT_EXTRA_ARGS_SIZE), + ); + const components: AndroidBootComponentPlan[] = []; + const kernelSize = u32(prefix, 8); + const kernelAddr = u32(prefix, 12); + const ramdiskSize = u32(prefix, 16); + const ramdiskAddr = u32(prefix, 20); + const secondSize = u32(prefix, 24); + const secondAddr = u32(prefix, 28); + let cursor = place( + components, + pageSize, + pageSize, + kernelSize === 0 + ? null + : component("kernel", "kernel", pageSize, kernelSize, kernelAddr), + ); + cursor = place( + components, + cursor, + pageSize, + ramdiskSize === 0 + ? null + : component("ramdisk", "ramdisk", cursor, ramdiskSize, ramdiskAddr), + ); + cursor = place( + components, + cursor, + pageSize, + secondSize === 0 + ? null + : component("second", "second", cursor, secondSize, secondAddr), + ); + const tail = layoutLegacyTail( + prefix, + headerVersion, + pageSize, + cursor, + components, + limitations, + ); + requireFileCovers(fileSize, tail.cursor); + return bootParse({ + imageKind: "boot", + magic: ANDROID_BOOT_MAGIC, + headerVersion, + pageSize, + headerSize, + headerOccupied: pageSize, + osVersionRaw: osRaw, + osVersion: os.osVersion, + securityPatchLevel: os.securityPatchLevel, + name: name.text, + nameBytesHex: name.hex, + ...commands, + headerDigestHex: prefix.subarray(576, 608).toString("hex"), + kernelAddr, + ramdiskAddr, + secondAddr, + tagsAddr: u32(prefix, 32), + dtbAddr: tail.dtbAddr, + kernelSize, + ramdiskSize, + secondSize, + recoveryDtboSize: tail.recoveryDtboSize, + recoveryDtboOffset: tail.recoveryDtboOffset, + dtbSize: tail.dtbSize, + components, + imageEnd: tail.cursor, + limitations, + }); +}; + +const parseModernBoot = ( + prefix: Buffer, + fileSize: number, + headerVersion: 3 | 4, +): AndroidBootParse => { + const structSize = headerVersion === 4 ? MODERN_V4_SIZE : MODERN_V3_SIZE; + requireBytes(prefix, structSize, "header"); + const headerSize = requireHeaderSize( + u32(prefix, 20), + structSize, + BOOT_V3_PAGE_SIZE, + ); + const limitations = baseLimitations("boot"); + if (headerSize > structSize) + limitations.push( + `Header bytes after the v${String(headerVersion)} structure were not decoded.`, + ); + const osRaw = u32(prefix, 16); + const os = decodeOsVersion(osRaw); + if (os.limitation !== null) limitations.push(os.limitation); + const commands = commandFields( + prefix.subarray(44, 44 + BOOT_ARGS_SIZE + BOOT_EXTRA_ARGS_SIZE), + null, + ); + const kernelSize = u32(prefix, 8); + const ramdiskSize = u32(prefix, 12); + const signatureSize = + headerVersion === 4 ? u32(prefix, MODERN_V3_SIZE) : null; + const components: AndroidBootComponentPlan[] = []; + let cursor = place( + components, + BOOT_V3_PAGE_SIZE, + BOOT_V3_PAGE_SIZE, + kernelSize === 0 + ? null + : component("kernel", "kernel", BOOT_V3_PAGE_SIZE, kernelSize, null), + ); + cursor = place( + components, + cursor, + BOOT_V3_PAGE_SIZE, + ramdiskSize === 0 + ? null + : component("ramdisk", "ramdisk", cursor, ramdiskSize, null), + ); + cursor = place( + components, + cursor, + BOOT_V3_PAGE_SIZE, + signatureSize === null || signatureSize === 0 + ? null + : component("signature", "signature", cursor, signatureSize, null), + ); + requireFileCovers(fileSize, cursor); + return bootParse({ + imageKind: "boot", + magic: ANDROID_BOOT_MAGIC, + headerVersion, + pageSize: BOOT_V3_PAGE_SIZE, + headerSize, + headerOccupied: BOOT_V3_PAGE_SIZE, + osVersionRaw: osRaw, + osVersion: os.osVersion, + securityPatchLevel: os.securityPatchLevel, + ...commands, + kernelSize, + ramdiskSize, + signatureSize, + components, + imageEnd: cursor, + limitations, + }); +}; + +const parseVendorTableHeader = ( + prefix: Buffer, +): { + readonly tableSize: number; + readonly entryCount: number; + readonly entrySize: number; + readonly bootconfigSize: number; +} => { + const tableSize = u32(prefix, VENDOR_V3_SIZE); + const entryCount = u32(prefix, VENDOR_V3_SIZE + 4); + const entrySize = u32(prefix, VENDOR_V3_SIZE + 8); + const bootconfigSize = u32(prefix, VENDOR_V3_SIZE + 12); + if (entryCount > MAX_VENDOR_RAMDISKS) + capacityError( + `vendor ramdisk table declares more than ${MAX_VENDOR_RAMDISKS} entries`, + VENDOR_RAMDISK_COUNT_LIMIT, + ); + if (entrySize > MAX_RAMDISK_ENTRY_SIZE) + capacityError( + `vendor ramdisk table entry size ${entrySize} exceeds the ${MAX_RAMDISK_ENTRY_SIZE} byte entry bound`, + VENDOR_RAMDISK_ENTRY_SIZE_LIMIT, + ); + if (entryCount > 0 && entrySize < VENDOR_RAMDISK_ENTRY_SIZE) + formatError( + `vendor ramdisk table entry size ${entrySize} is smaller than the ${VENDOR_RAMDISK_ENTRY_SIZE}-byte v4 entry`, + ); + const product = entryCount * entrySize; + if (!Number.isSafeInteger(product) || product !== tableSize) + formatError( + `vendor ramdisk table size ${tableSize} does not equal ${entryCount} entries of ${entrySize} bytes`, + ); + return { tableSize, entryCount, entrySize, bootconfigSize }; +}; + +const parseVendorHeader = ( + prefix: Buffer, + fileSize: number, +): AndroidBootParse => { + requireBytes(prefix, 12, "header"); + const headerVersion = u32(prefix, 8); + if (headerVersion !== 3 && headerVersion !== 4) + throw unsupportedInput( + ANDROID_BOOT_FORMAT, + `vendor boot header version ${headerVersion} is unsupported`, + { offset: 8, field: "header_version", undecodedContent: true }, + ); + const structSize = headerVersion === 4 ? VENDOR_V4_SIZE : VENDOR_V3_SIZE; + requireBytes(prefix, structSize, "header"); + const pageSize = requirePageSize(u32(prefix, 12)); + const kernelAddr = u32(prefix, 16); + const ramdiskAddr = u32(prefix, 20); + const vendorRamdiskSize = u32(prefix, 24); + const tagsAddr = u32(prefix, 2076); + const name = decodeField(prefix.subarray(2080, 2080 + NAME_SIZE)); + const headerSize = requireHeaderSize( + u32(prefix, 2096), + structSize, + MAX_HEADER_SIZE, + ); + const dtbSize = u32(prefix, 2100); + const dtbAddr = u64(prefix, 2104, "dtb address"); + const table = headerVersion === 4 ? parseVendorTableHeader(prefix) : null; + const limitations = baseLimitations("vendor-boot"); + if (headerSize > structSize) + limitations.push( + `Header bytes after the v${String(headerVersion)} structure were not decoded.`, + ); + const headerOccupied = alignUp(headerSize, pageSize); + const sectionOffset = headerOccupied; + let cursor = + vendorRamdiskSize === 0 + ? sectionOffset + : alignUp(endOf(sectionOffset, vendorRamdiskSize), pageSize); + const components: AndroidBootComponentPlan[] = []; + if (headerVersion === 3 && vendorRamdiskSize > 0) + components.push( + component( + "vendor-ramdisk", + "vendor_ramdisk", + sectionOffset, + vendorRamdiskSize, + ramdiskAddr, + ), + ); + cursor = place( + components, + cursor, + pageSize, + dtbSize === 0 ? null : component("dtb", "dtb", cursor, dtbSize, dtbAddr), + ); + const tableRange = + table !== null && table.tableSize > 0 + ? { offset: cursor, size: table.tableSize } + : null; + if (tableRange !== null) + cursor = alignUp(endOf(tableRange.offset, tableRange.size), pageSize); + const bootconfigSize = table?.bootconfigSize ?? null; + cursor = place( + components, + cursor, + pageSize, + bootconfigSize === null || bootconfigSize === 0 + ? null + : component("bootconfig", "bootconfig", cursor, bootconfigSize, null), + ); + if (table !== null && table.entryCount === 0 && vendorRamdiskSize > 0) + limitations.push( + "Vendor ramdisk section bytes outside the ramdisk table were not exposed as entries.", + ); + requireFileCovers(fileSize, cursor); + return bootParse({ + imageKind: "vendor-boot", + magic: VENDOR_BOOT_MAGIC, + headerVersion, + pageSize, + headerSize, + headerOccupied, + name: name.text, + nameBytesHex: name.hex, + ...commandFields(prefix.subarray(28, 28 + VENDOR_ARGS_SIZE), null), + kernelAddr, + ramdiskAddr, + tagsAddr, + dtbAddr, + dtbSize, + vendorRamdiskSize, + vendorRamdiskTableEntryCount: table?.entryCount ?? null, + vendorRamdiskTableEntrySize: table?.entrySize ?? null, + bootconfigSize, + components, + imageEnd: cursor, + limitations, + tableRange, + vendorRamdiskSection: { offset: sectionOffset, size: vendorRamdiskSize }, + }); +}; + +const parseAndroidHeader = ( + prefix: Buffer, + fileSize: number, +): AndroidBootParse => { + requireBytes(prefix, 44, "header"); + const headerVersion = u32(prefix, 40); + if (headerVersion <= 2) + return parseLegacyBoot(prefix, fileSize, headerVersion); + if (headerVersion === 3 || headerVersion === 4) + return parseModernBoot(prefix, fileSize, headerVersion); + throw unsupportedInput( + ANDROID_BOOT_FORMAT, + `header version ${headerVersion} is unsupported`, + { offset: 40, field: "header_version", undecodedContent: true }, + ); +}; + +/** Decode one boot or vendor_boot header and its page-aligned component ranges. */ +export const parseAndroidBootHeader = ( + prefix: Buffer, + fileSize: number, +): Result => + parsed(() => { + if (!Number.isSafeInteger(fileSize) || fileSize < 0) + formatError("file size is not a safe nonnegative integer"); + requireBytes(prefix, 8, "header"); + if (prefix.subarray(0, 8).equals(ANDROID_BOOT_MAGIC_BYTES)) + return parseAndroidHeader(prefix, fileSize); + if (prefix.subarray(0, 8).equals(VENDOR_BOOT_MAGIC_BYTES)) + return parseVendorHeader(prefix, fileSize); + return formatError("magic is not ANDROID! or VNDRBOOT"); + }); + +const vendorRamdiskPath = ( + text: string | null, + index: number, + used: Set, +): string => { + const base = + text !== null && + text.length > 0 && + text !== "." && + text !== ".." && + !text.includes("/") + ? // Inventory keys logical paths by their NFC spelling, so uniqueness + // is checked in that spelling; name_bytes_hex keeps the stored bytes. + logicalPathNfc(text) + : `ramdisk-${String(index)}`; + // `-` can itself match an earlier name (`x` beside `x-2`, or a + // fallback `ramdisk-` beside a real name of that form). Keep + // suffixing until the segment is unused. + let unique = used.has(base) ? `${base}-${String(index)}` : base; + let extra = 2; + while (used.has(unique)) { + unique = `${base}-${String(index)}-${String(extra)}`; + extra += 1; + } + used.add(unique); + return `vendor_ramdisk/${unique}`; +}; + +const sectionCovered = ( + entries: readonly AndroidBootComponentPlan[], + sectionOffset: number, + sectionSize: number, +): boolean => { + let covered = 0; + const spans = entries + .map((entry) => ({ + start: entry.offset - sectionOffset, + end: entry.offset - sectionOffset + entry.size, + })) + .sort((left, right) => left.start - right.start); + for (const span of spans) { + if (span.start > covered) return false; + covered = Math.max(covered, span.end); + } + return covered === sectionSize; +}; + +const readVendorRamdiskTable = ( + table: Buffer, + input: { + readonly entryCount: number; + readonly entrySize: number; + readonly sectionOffset: number; + readonly sectionSize: number; + }, +): VendorRamdiskTableParse => { + if (input.entryCount > 0 && input.entrySize < VENDOR_RAMDISK_ENTRY_SIZE) + formatError( + `vendor ramdisk table entry size ${input.entrySize} is smaller than the ${VENDOR_RAMDISK_ENTRY_SIZE}-byte v4 entry`, + ); + const expected = input.entryCount * input.entrySize; + requireBytes(table, expected, "vendor ramdisk table"); + if (table.length > expected) + formatError( + `vendor ramdisk table is ${table.length} bytes, expected ${expected}`, + ); + const components: AndroidBootComponentPlan[] = []; + const used = new Set(); + const empty: number[] = []; + let longer = false; + for (let index = 0; index < input.entryCount; index += 1) { + const base = index * input.entrySize; + const size = u32(table, base); + const offset = u32(table, base + 4); + const ramdiskType = u32(table, base + 8); + if (offset > input.sectionSize || size > input.sectionSize - offset) + formatError( + `vendor ramdisk table entry ${index} overruns the vendor ramdisk section`, + ); + // An empty fragment carries no bytes to expose, like other zero-sized + // components; omit it rather than rejecting the image. + if (size === 0) { + empty.push(index); + continue; + } + const fileOffset = endOf(input.sectionOffset, offset); + endOf(fileOffset, size); + const decoded = decodeField( + table.subarray(base + 12, base + 12 + RAMDISK_NAME_SIZE), + ); + if (input.entrySize > VENDOR_RAMDISK_ENTRY_SIZE) longer = true; + components.push( + component( + "vendor-ramdisk", + vendorRamdiskPath(decoded.text, index, used), + fileOffset, + size, + // ramdisk_addr is the assembled section's base; a fragment's placement + // depends on bootloader selection, so it is not published per entry. + null, + { + index, + ramdiskType, + ramdiskTypeName: ramdiskTypeName(ramdiskType), + nameBytesHex: decoded.hex, + boardIdHex: table + .subarray( + base + BOARD_ID_OFFSET, + base + BOARD_ID_OFFSET + BOARD_ID_BYTES, + ) + .toString("hex"), + }, + ), + ); + } + const ordered = [...components].sort( + (left, right) => left.offset - right.offset || left.index - right.index, + ); + for (let index = 1; index < ordered.length; index += 1) { + const previous = ordered[index - 1]; + const current = ordered[index]; + if ( + previous !== undefined && + current !== undefined && + previous.offset + previous.size > current.offset + ) + formatError( + `vendor ramdisk table entry ${current.index} overlaps entry ${previous.index}`, + ); + } + const limitations: string[] = []; + if (longer) + limitations.push( + `Vendor ramdisk table entries are longer than the ${String(VENDOR_RAMDISK_ENTRY_SIZE)}-byte v4 structure; trailing entry bytes were not decoded.`, + ); + if (empty.length > 0) + limitations.push( + `Vendor ramdisk table entries ${empty.join(", ")} declare no bytes and were omitted.`, + ); + if (!sectionCovered(components, input.sectionOffset, input.sectionSize)) + limitations.push( + "Vendor ramdisk section bytes outside the ramdisk table were not exposed as entries.", + ); + return { components, limitations }; +}; + +/** Split a v4 vendor ramdisk table into non-overlapping section slices. */ +export const parseVendorRamdiskTable = ( + table: Buffer, + input: { + readonly entryCount: number; + readonly entrySize: number; + readonly sectionOffset: number; + readonly sectionSize: number; + }, +): Result => + parsed(() => readVendorRamdiskTable(table, input)); + +const absentFooter = (limitations: readonly string[] = []): AvbFooterFacts => ({ + present: false, + footerSize: null, + versionMajor: null, + versionMinor: null, + originalImageSize: null, + vbmetaOffset: null, + vbmetaSize: null, + limitations, +}); + +const rejectVbmetaOverlap = ( + vbmeta: { readonly offset: number; readonly size: number }, + fileSize: number, + headerOccupied: number, + components: readonly { readonly offset: number; readonly size: number }[], +): void => { + if (vbmeta.size === 0) return; + if (endOf(vbmeta.offset, vbmeta.size) > fileSize - AVB_FOOTER_SIZE) + formatError("AVB vbmeta overlaps the footer"); + const occupied = [{ offset: 0, size: headerOccupied }, ...components]; + for (const componentRange of occupied) + if ( + componentRange.size > 0 && + vbmeta.offset < componentRange.offset + componentRange.size && + componentRange.offset < vbmeta.offset + vbmeta.size + ) + formatError( + componentRange.offset === 0 + ? "AVB vbmeta overlaps the boot image header" + : `AVB vbmeta overlaps a component at offset ${componentRange.offset}`, + ); +}; + +const readAvbFooter = (input: { + readonly fileSize: number; + readonly imageEnd: number; + readonly headerOccupied: number; + readonly components: readonly { + readonly offset: number; + readonly size: number; + }[]; + readonly tail: Buffer | null; +}): AvbFooterFacts => { + if (input.fileSize < input.imageEnd) + throw truncatedInput( + ANDROID_BOOT_FORMAT, + `image is truncated: components end at byte ${input.imageEnd} but the file is ${input.fileSize} bytes`, + { offset: input.fileSize, field: "components" }, + ); + const trailing = input.fileSize - input.imageEnd; + if (trailing === 0) return absentFooter(); + if (trailing < AVB_FOOTER_SIZE) + return absentFooter([ + `${trailing} trailing bytes follow the boot image and are shorter than a 64-byte AVB footer.`, + ]); + const tail = input.tail; + if (tail === null || tail.length !== AVB_FOOTER_SIZE) + return formatError("AVB footer bytes were not supplied"); + if (!tail.subarray(0, 4).equals(AVB_FOOTER_MAGIC_BYTES)) + return absentFooter([ + `${trailing} trailing bytes follow the boot image and were not decoded as an AVB footer.`, + ]); + const originalImageSize = u64be(tail, 12, "AVB original image size"); + const vbmetaOffset = u64be(tail, 20, "AVB vbmeta offset"); + const vbmetaSize = u64be(tail, 28, "AVB vbmeta size"); + if (originalImageSize < input.imageEnd) + formatError( + `AVB original image size ${originalImageSize} ends before boot image components at ${input.imageEnd}`, + ); + if (originalImageSize > input.fileSize - AVB_FOOTER_SIZE) + formatError( + `AVB original image size ${originalImageSize} overlaps the footer`, + ); + rejectVbmetaOverlap( + { offset: vbmetaOffset, size: vbmetaSize }, + input.fileSize, + input.headerOccupied, + input.components, + ); + return { + present: true, + footerSize: AVB_FOOTER_SIZE, + versionMajor: new BinaryReader(tail, false, ANDROID_BOOT_FORMAT).u32(4), + versionMinor: new BinaryReader(tail, false, ANDROID_BOOT_FORMAT).u32(8), + originalImageSize, + vbmetaOffset, + vbmetaSize, + limitations: [], + }; +}; + +/** + * Report an AVB footer when the last 64 bytes start with AVBf and sit past + * the page-aligned image. Sizes are recorded; the footer is not verified. + */ +export const inspectAvbFooter = (input: { + readonly fileSize: number; + readonly imageEnd: number; + readonly headerOccupied: number; + readonly components: readonly { + readonly offset: number; + readonly size: number; + }[]; + readonly tail: Buffer | null; +}): Result => + parsed(() => readAvbFooter(input)); diff --git a/src/artifacts/NodeSeaArtifactReader.test.ts b/src/artifacts/NodeSeaArtifactReader.test.ts index 7d916b6aa8..207ead8198 100644 --- a/src/artifacts/NodeSeaArtifactReader.test.ts +++ b/src/artifacts/NodeSeaArtifactReader.test.ts @@ -1122,7 +1122,7 @@ it("confirms SEA naming before rejecting an unrelated cyclic PE resource branch" try { await expect( locateNodeSea(handle, fixture.bytes.length), - ).rejects.toMatchObject({ reason: "format" }); + ).rejects.toMatchObject({ reason: "malformed" }); } finally { await handle.close(); } diff --git a/src/artifacts/PositionalArtifactReader.ts b/src/artifacts/PositionalArtifactReader.ts index b02acaff10..fb03168104 100644 --- a/src/artifacts/PositionalArtifactReader.ts +++ b/src/artifacts/PositionalArtifactReader.ts @@ -17,6 +17,8 @@ import { import { ownArtifactStream } from "./OwnedArtifactStream.js"; import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js"; import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js"; +import type { ArtifactFormatMetadata } from "../domain/artifactFormatMetadata.js"; +import { invariantViolation } from "../domain/internalInvariant.js"; /** An entry whose bytes are one range of the carrier. */ export type PositionalArtifactEntry = ArtifactEntry & { @@ -25,10 +27,11 @@ export type PositionalArtifactEntry = ArtifactEntry & { }; /** The entries one preparation established and the coverage to report. */ -export interface PositionalArtifactEntries { +export interface PositionalArtifactEntries { readonly entries: readonly PositionalArtifactEntry[]; /** The coverage the preparation established, including complete coverage. */ readonly coverage: ArtifactReaderTraversal; + readonly formatMetadata?: Metadata; } /** @@ -37,15 +40,22 @@ export interface PositionalArtifactEntries { * carrier's identity, and close retires open streams before the carrier. * Encrypted entries are listed but never opened. */ -export abstract class PositionalArtifactReader implements ArtifactReader { +export abstract class PositionalArtifactReader< + Metadata extends ArtifactFormatMetadata = never, +> implements ArtifactReader { abstract readonly format: ArtifactReader["format"]; readonly #scope = new ArtifactResourceScope(); - readonly #entries = new Map(); readonly #streams = new Set(); readonly #label: string; readonly #source: ArtifactFileSource; readonly #preparation = new ArtifactPreparation(); - #coverage: ArtifactReaderTraversal | undefined; + #prepared: + | { + readonly entries: ReadonlyMap; + readonly coverage: ArtifactReaderTraversal; + readonly formatMetadata: Metadata | undefined; + } + | undefined; #closing = false; constructor( @@ -60,7 +70,12 @@ export abstract class PositionalArtifactReader implements ArtifactReader { /** Read the carrier once and describe its entries. */ protected abstract prepareEntries( signal?: AbortSignal, - ): Promise; + ): Promise>; + + /** Metadata from the same validated preparation that established entries and coverage. */ + protected get preparedFormatMetadata(): Metadata | undefined { + return this.#prepared?.formatMetadata; + } async prepareContainer( expectedSha256: string, @@ -78,22 +93,27 @@ export abstract class PositionalArtifactReader implements ArtifactReader { ): AsyncIterable { await this.#scope.run(async () => { this.assertOpen(signal); + // The first preparation validates before publishing; cached traversals + // still need their own freshness admission. + if (this.#prepared !== undefined) await this.#source.read(signal); await this.#preparation.run( signal, () => this.#prepare(signal), () => this.assertOpen(signal), ); - await this.#source.read(signal); }); this.assertOpen(signal); - // An unprepared reader declares nothing, which consumers read as unknown. - if (this.#coverage !== undefined) - options?.onCoverage?.({ - ...this.#coverage, - limitations: [...this.#coverage.limitations], - }); + const prepared = this.#prepared; + if (prepared === undefined) + throw invariantViolation( + "Positional artifact preparation did not complete", + ); + options?.onCoverage?.({ + ...prepared.coverage, + limitations: [...prepared.coverage.limitations], + }); let index = 0; - for (const entry of this.#entries.values()) { + for (const entry of prepared.entries.values()) { // Yield between batches so a large inventory does not hold the loop. if (index++ % 256 === 0) await setImmediate(); this.assertOpen(signal); @@ -105,7 +125,7 @@ export abstract class PositionalArtifactReader implements ArtifactReader { async open(entry: ArtifactEntry, signal?: AbortSignal): Promise { return this.#scope.run(async () => { this.assertOpen(signal); - const stored = this.#entries.get(entry.adapterKey); + const stored = this.#prepared?.entries.get(entry.adapterKey); assertProducedEntry( entry, stored, @@ -159,7 +179,8 @@ export abstract class PositionalArtifactReader implements ArtifactReader { ); await this.#scope.close(); await this.#source.close(); - this.#entries.clear(); + this.#prepared = undefined; + this.#preparation.clear(); } provenance(): readonly [] { @@ -184,9 +205,17 @@ export abstract class PositionalArtifactReader implements ArtifactReader { } async #prepare(signal?: AbortSignal): Promise { - const { entries, coverage } = await this.prepareEntries(signal); - for (const entry of entries) this.#entries.set(entry.adapterKey, entry); - this.#coverage = coverage; + const prepared = await this.prepareEntries(signal); + const entries = new Map( + prepared.entries.map((entry) => [entry.adapterKey, entry] as const), + ); + await this.#source.read(signal); + this.assertOpen(signal); + this.#prepared = { + entries, + coverage: prepared.coverage, + formatMetadata: prepared.formatMetadata, + }; } #entryStream( diff --git a/src/artifacts/artifactFormats.test.ts b/src/artifacts/artifactFormats.test.ts index 7fef477b0a..aa133bad0a 100644 --- a/src/artifacts/artifactFormats.test.ts +++ b/src/artifacts/artifactFormats.test.ts @@ -30,6 +30,7 @@ type FormatsWithReaders = | "unityfs" | "wxapkg" | "uimage" + | "android-boot-image" | "mach-o-universal" | "directory" | "pyinstaller" diff --git a/src/artifacts/artifactFormats.ts b/src/artifacts/artifactFormats.ts index 0f1d8a52cc..c406fe75e4 100644 --- a/src/artifacts/artifactFormats.ts +++ b/src/artifacts/artifactFormats.ts @@ -17,6 +17,7 @@ import { ZipArtifactReader, } from "../resources/index.js"; import type { ArtifactReaderAdmission } from "./ArtifactReaderAdmission.js"; +import { AndroidBootImageArtifactReader } from "./AndroidBootImageArtifactReader.js"; import { AsarArtifactReader } from "./AsarArtifactReader.js"; import type { BunStandaloneAdmission } from "./bun/BunStandaloneAdmission.js"; import { BunStandaloneArtifactReader } from "./BunStandaloneArtifactReader.js"; @@ -349,6 +350,16 @@ const NON_ZIP_FORMATS = { createReader: (path, options) => new UImageArtifactReader(path, sourceOf(options)), }), + "android-boot-image": container("android-boot-image", { + roleContainer: true, + retainClassifiedSource: true, + extractable: true, + absentInventory: "unavailable", + readerLimitation: + "Android boot image inventory establishes header facts and stored component bytes. Payloads are not decompressed, the v4 signature and AVB footer are not verified, and the image is not executed.", + createReader: (path, options) => + new AndroidBootImageArtifactReader(path, sourceOf(options)), + }), "javascript-bundle": described("javascript-bundle", plain), "source-map": described("source-map", plain), "mach-o-universal": described("mach-o-universal", { diff --git a/src/artifacts/deno/DenoStandaloneArtifactReader.test.ts b/src/artifacts/deno/DenoStandaloneArtifactReader.test.ts index 658a31502e..4ea247b9e9 100644 --- a/src/artifacts/deno/DenoStandaloneArtifactReader.test.ts +++ b/src/artifacts/deno/DenoStandaloneArtifactReader.test.ts @@ -1363,7 +1363,7 @@ it("fails closed when a readable D3N0L4ND resource sits beside an unreadable RT_ locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length), ).resolves.toMatchObject({ status: "present", - failure: { reason: "format" }, + failure: { reason: "malformed" }, }); }); @@ -1388,7 +1388,7 @@ it("fails closed when a readable D3N0L4ND resource sits beside a non-directory R locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length), ).resolves.toMatchObject({ status: "present", - failure: { reason: "format" }, + failure: { reason: "malformed" }, }); }); @@ -1401,7 +1401,7 @@ it("fails closed when a D3N0L4ND payload is not file-backed", async () => { locateDenoStandalone(bytesHandle(fixture.bytes), fixture.bytes.length), ).resolves.toMatchObject({ status: "present", - failure: { reason: "format" }, + failure: { reason: "malformed" }, }); }); diff --git a/src/artifacts/deno/DenoStandaloneLocation.ts b/src/artifacts/deno/DenoStandaloneLocation.ts index e6fdd38bdd..851faacf1f 100644 --- a/src/artifacts/deno/DenoStandaloneLocation.ts +++ b/src/artifacts/deno/DenoStandaloneLocation.ts @@ -150,7 +150,11 @@ export const locateDenoStandalone = async ( } catch (cause) { if ( cause instanceof ArtifactReaderFailure && - (cause.reason === "format" || cause.reason === "limit") + (cause.reason === "format" || + cause.reason === "malformed" || + cause.reason === "truncated" || + cause.reason === "unsupported" || + cause.reason === "limit") ) return { status: "present", failure: cause }; throw cause; diff --git a/src/domain/analysisErrorClassification.test.ts b/src/domain/analysisErrorClassification.test.ts index 32a2c95a76..fa2aa6c365 100644 --- a/src/domain/analysisErrorClassification.test.ts +++ b/src/domain/analysisErrorClassification.test.ts @@ -42,6 +42,9 @@ it.each([ it.each([ "cancelled", + "malformed", + "truncated", + "unsupported", "format", "integrity", "path", diff --git a/src/domain/analysisErrorClassification.ts b/src/domain/analysisErrorClassification.ts index 8b99f1f0a9..dafd2058a9 100644 --- a/src/domain/analysisErrorClassification.ts +++ b/src/domain/analysisErrorClassification.ts @@ -98,6 +98,9 @@ const RETRYABLE_CAPABILITY_UNAVAILABLE = classified( const ARTIFACT_OPERATION_CLASSIFICATIONS = { cancelled: classified("cancelled", "cancelled"), + malformed: classified("invalid_request", "invalid_input"), + truncated: classified("truncated", "truncated"), + unsupported: classified("unsupported_target", "unsupported_target"), format: classified("artifact_operation_failed", "execution_failure"), integrity: classified("artifact_operation_failed", "integrity_mismatch"), limit: classified("truncated", "truncated"), diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts index baa820f063..0d5055a316 100644 --- a/src/domain/analysisErrorPresentation.ts +++ b/src/domain/analysisErrorPresentation.ts @@ -545,6 +545,12 @@ const artifactMessage = ({ detail ?? "Artifact processing reached a resource limit. Select an artifact within the reported limits and retry." ); + if (reason === "unsupported") + return "Artifact structure uses an unsupported format or revision. Use a decoder that supports the reported form."; + if (reason === "truncated") + return "A declared artifact structure is truncated. Select a complete copy and retry; do not pad or truncate required bytes."; + if (reason === "malformed") + return "Artifact bytes contain malformed format structure. Review the reported field and select a valid copy."; if (reason === "path") return ( detail ?? diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index e0e005ab29..e7592e9b66 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -91,6 +91,7 @@ const formatSchema = z.enum([ "javascript", "source-map", "uimage", + "android-boot-image", ]); const kindSchema = z.enum(["executable", "database", "archive", "artifact"]); type SnapshotFormat = z.infer; diff --git a/src/domain/androidBootImageFormat.ts b/src/domain/androidBootImageFormat.ts new file mode 100644 index 0000000000..91201ce97a --- /dev/null +++ b/src/domain/androidBootImageFormat.ts @@ -0,0 +1,11 @@ +/** Android boot image magic values; the header parser lives with its reader. */ +export const ANDROID_BOOT_MAGIC = "ANDROID!"; +export const VENDOR_BOOT_MAGIC = "VNDRBOOT"; +const ANDROID_BOOT_MAGIC_BYTES = Buffer.from(ANDROID_BOOT_MAGIC); +const VENDOR_BOOT_MAGIC_BYTES = Buffer.from(VENDOR_BOOT_MAGIC); + +/** True when the first eight bytes are ANDROID! or VNDRBOOT. */ +export const hasAndroidBootImageMagic = (prefix: Buffer): boolean => + prefix.length >= 8 && + (prefix.subarray(0, 8).equals(ANDROID_BOOT_MAGIC_BYTES) || + prefix.subarray(0, 8).equals(VENDOR_BOOT_MAGIC_BYTES)); diff --git a/src/domain/artifactFormatMetadata.ts b/src/domain/artifactFormatMetadata.ts index 05e0b81013..5cf07d483c 100644 --- a/src/domain/artifactFormatMetadata.ts +++ b/src/domain/artifactFormatMetadata.ts @@ -847,6 +847,106 @@ export type BunStandaloneEntryMetadata = z.infer< typeof bunStandaloneEntryMetadataSchema >; +/** + * Android boot and vendor_boot header facts. Addresses, names, and the + * command line are declarations from the image. The digest, v4 signature, + * and AVB footer are recorded and not verified. + */ +export const androidBootImageMetadataSchema = z.strictObject({ + kind: z.literal("android-boot-image"), + image_kind: z.enum(["boot", "vendor-boot"]), + magic: z.enum(["ANDROID!", "VNDRBOOT"]), + header_version: z.number().int().min(0).max(4), + page_size: z.number().int().min(2048).max(65536), + header_size: offset, + os_version_raw: uint32.nullable(), + os_version: z + .string() + .regex(/^\d{1,3}\.\d{1,3}\.\d{1,3}$/u) + .nullable(), + security_patch_level: z + .string() + .regex(/^\d{4}-\d{2}$/u) + .nullable(), + name: z.string().nullable(), + name_bytes_hex: z + .string() + .regex(/^[0-9a-f]{32}$/u) + .nullable(), + cmdline: z.string().nullable(), + cmdline_bytes_hex: z + .string() + .regex(/^(?:[0-9a-f]{1024}|[0-9a-f]{3072}|[0-9a-f]{4096})$/u), + extra_cmdline: z.string().nullable(), + extra_cmdline_bytes_hex: z + .string() + .regex(/^[0-9a-f]{2048}$/u) + .nullable(), + command_line: z.string().nullable(), + header_digest_hex: z + .string() + .regex(/^[0-9a-f]{64}$/u) + .nullable(), + kernel_addr: uint32.nullable(), + ramdisk_addr: uint32.nullable(), + second_addr: uint32.nullable(), + tags_addr: uint32.nullable(), + dtb_addr: offset.nullable(), + kernel_size: uint32.nullable(), + ramdisk_size: uint32.nullable(), + second_size: uint32.nullable(), + recovery_dtbo_size: uint32.nullable(), + recovery_dtbo_offset: offset.nullable(), + dtb_size: uint32.nullable(), + signature_size: uint32.nullable(), + vendor_ramdisk_size: uint32.nullable(), + vendor_ramdisk_table_entry_count: uint32.nullable(), + vendor_ramdisk_table_entry_size: uint32.nullable(), + bootconfig_size: uint32.nullable(), + avb_footer_present: z.boolean(), + avb_footer_size: z.literal(64).nullable(), + avb_version_major: uint32.nullable(), + avb_version_minor: uint32.nullable(), + avb_original_image_size: offset.nullable(), + avb_vbmeta_offset: offset.nullable(), + avb_vbmeta_size: offset.nullable(), + component_count: uint32, +}); +export type AndroidBootImageMetadata = z.infer< + typeof androidBootImageMetadataSchema +>; + +/** One stored boot-image component. Compression is a leading-magic observation. */ +export const androidBootImageEntryMetadataSchema = z.strictObject({ + kind: z.literal("android-boot-image-entry"), + role: z.enum([ + "kernel", + "ramdisk", + "second", + "recovery-dtbo", + "dtb", + "vendor-ramdisk", + "bootconfig", + "signature", + ]), + index: uint32, + compression: z.enum(["gzip", "lz4", "zstd"]).nullable(), + ramdisk_type: uint32.nullable(), + ramdisk_type_name: z.string().nullable(), + load_address: offset.nullable(), + name_bytes_hex: z + .string() + .regex(/^[0-9a-f]{64}$/u) + .nullable(), + board_id_hex: z + .string() + .regex(/^[0-9a-f]{128}$/u) + .nullable(), +}); +export type AndroidBootImageEntryMetadata = z.infer< + typeof androidBootImageEntryMetadataSchema +>; + const denoListingSchema = z.enum(["listed", "unsupported"]); const denoEnvVarSchema = z.strictObject({ @@ -959,6 +1059,8 @@ export const artifactFormatMetadataSchema = z.discriminatedUnion("kind", [ espFlashPartitionMetadataSchema, fitMetadataSchema, fitImageMetadataSchema, + androidBootImageMetadataSchema, + androidBootImageEntryMetadataSchema, ]); export type ArtifactFormatMetadata = z.infer< typeof artifactFormatMetadataSchema @@ -1077,6 +1179,14 @@ const declarationsByKind: { notCompared: "role and index restate the entry's path; its stored bytes are compared by content.", }, + "android-boot-image": { + notCompared: + "Its header facts come from the image's own bytes, which content comparison covers.", + }, + "android-boot-image-entry": { + notCompared: + "role and index restate the entry's path, compression is observed from its bytes, and load addresses, names and board IDs come from the image header or vendor ramdisk table, which the image's content comparison covers.", + }, "esp-image": { notCompared: "Its fields come from the image's own bytes, which content comparison covers.", diff --git a/src/domain/artifactFormatRecognition.ts b/src/domain/artifactFormatRecognition.ts index 5f814c69e9..9551e493c1 100644 --- a/src/domain/artifactFormatRecognition.ts +++ b/src/domain/artifactFormatRecognition.ts @@ -1,4 +1,5 @@ import type { ArtifactFormatId } from "./artifactGraph.js"; +import { hasAndroidBootImageMagic } from "./androidBootImageFormat.js"; import { hasBinaryPlistSignature } from "./apple/appleArchiveFormat.js"; import { hasDfuSePrefix, isDfuSeFile } from "./firmware/dfuse.js"; import { ESP8266_REFUSAL, recognizeEspImage } from "./firmware/espImage.js"; @@ -22,6 +23,7 @@ export type RecognizedArtifactFormat = Extract< | "unityfs" | "wxapkg" | "uimage" + | "android-boot-image" | "intel-hex" | "srec" | "uf2" @@ -102,6 +104,7 @@ export const ARTIFACT_FORMAT_RECOGNIZERS: readonly ArtifactFormatRecognizer[] = (prefix) => hasWxapkgEncryptedMagic(prefix) || hasWxapkgHeader(prefix), ), when("uimage", hasUImageMagic), + when("android-boot-image", hasAndroidBootImageMagic), ({ prefix }) => { const format = detectHexRecordEncoding(prefix); return format === undefined ? undefined : { state: "recognized", format }; diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.ts index 1a70bcecee..4d740ddab9 100644 --- a/src/domain/artifactGraph.ts +++ b/src/domain/artifactGraph.ts @@ -72,6 +72,7 @@ export const ARTIFACT_FORMAT_IDS = [ "unityfs", "wxapkg", "uimage", + "android-boot-image", "javascript-bundle", "source-map", "mach-o-universal", @@ -120,6 +121,7 @@ const artifactContentFormatSchema = artifactFormatSchema.extract([ "unityfs", "wxapkg", "uimage", + "android-boot-image", "intel-hex", "srec", "esp-image", diff --git a/src/domain/artifactOperationError.ts b/src/domain/artifactOperationError.ts index c7880448bb..9632e1d70c 100644 --- a/src/domain/artifactOperationError.ts +++ b/src/domain/artifactOperationError.ts @@ -8,6 +8,7 @@ import { } from "./analysisErrorBase.js"; import type { ArtifactReaderLimitFact } from "./artifactReaderLimits.js"; import type { FixedAllowance } from "./fixedAllowanceRemediation.js"; +import type { ParseFailureKind } from "./parseFailure.js"; /** The resource class that refused an artifact operation. */ export type ArtifactLimitBoundary = "file-size" | "capacity" | "memory"; @@ -99,10 +100,10 @@ export class ArtifactOperationError extends AnalysisError { | "trace_web_source_location" | "analyze_javascript_application", readonly reason: + | ParseFailureKind | "cancelled" | "format" | "integrity" - | "limit" | "path" | "unavailable" | "io", diff --git a/src/domain/binaryTargetTypes.ts b/src/domain/binaryTargetTypes.ts index c57c2beff5..4f233af215 100644 --- a/src/domain/binaryTargetTypes.ts +++ b/src/domain/binaryTargetTypes.ts @@ -316,6 +316,7 @@ export type BinaryTarget = | "unityfs" | "wxapkg" | "uimage" + | "android-boot-image" | "dmg" | "pkg" | "intel-hex" @@ -371,6 +372,7 @@ export const BINARY_TARGET_FORMAT_KINDS = { unityfs: "archive", wxapkg: "archive", uimage: "archive", + "android-boot-image": "archive", dmg: "archive", pkg: "archive", "intel-hex": "archive", diff --git a/src/domain/evidenceSubject.ts b/src/domain/evidenceSubject.ts index 5580bd3d2c..bb65458c1d 100644 --- a/src/domain/evidenceSubject.ts +++ b/src/domain/evidenceSubject.ts @@ -29,6 +29,7 @@ export const evidenceSubjectFormatSchema = z.enum([ "unityfs", "wxapkg", "uimage", + "android-boot-image", "dmg", "pkg", "plist", diff --git a/src/domain/liveBinaryTargetSummary.ts b/src/domain/liveBinaryTargetSummary.ts index 5100532b1f..f5ada430c6 100644 --- a/src/domain/liveBinaryTargetSummary.ts +++ b/src/domain/liveBinaryTargetSummary.ts @@ -72,6 +72,7 @@ export const liveBinaryTargetSummaryVariants = [ "unityfs", "wxapkg", "uimage", + "android-boot-image", "dmg", "pkg", "intel-hex", diff --git a/src/native/pe/PeCertificatesProvider.ts b/src/native/pe/PeCertificatesProvider.ts index 7b82777834..9b2f1c51d0 100644 --- a/src/native/pe/PeCertificatesProvider.ts +++ b/src/native/pe/PeCertificatesProvider.ts @@ -1,9 +1,8 @@ -import { BinaryFormatFailure } from "../../domain/binaryContainer.js"; import { projectSelectedArtifactFileFailure, projectOwnedArtifactIdentityFailure, + projectOwnedArtifactInputFailure, projectStableArtifactFailure, - stableArtifactInputFailure, projectArtifactCloseFailure, ArtifactReaderFailure, type StableArtifactSnapshot, @@ -18,7 +17,6 @@ import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; import { AnalysisInputError, AnalysisResourceConstraintError, - AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js"; import { MAX_INSPECT_PE_CERTIFICATE_ENTRIES, @@ -146,20 +144,18 @@ const peCertificatesFailurePrimary = ( input: InspectPeCertificatesInput, ) => { const { cause, origin } = facts; - if (cause instanceof BinaryFormatFailure && cause.kind === "unsupported") - return new AnalysisUnsupportedTargetError( - OPERATION, - input.path, - cause.message, - { cause }, - ); - const identityFailure = projectOwnedArtifactIdentityFailure( facts, OPERATION, input.path, ); if (identityFailure !== undefined) return identityFailure; + const inputFailure = projectOwnedArtifactInputFailure( + facts, + OPERATION, + input.path, + ); + if (inputFailure !== undefined) return inputFailure; if ( origin === "owned-or-classified" && cause instanceof PeCertificateAsn1Failure && @@ -192,8 +188,6 @@ const peCertificatesFailurePrimary = ( }), }, ); - if (cause.reason === "path" || cause.reason === "format") - return stableArtifactInputFailure(cause, OPERATION); } const fileFailure = projectSelectedArtifactFileFailure( cause, diff --git a/src/native/pe/PeResourcesProvider.ts b/src/native/pe/PeResourcesProvider.ts index f71a8cffa3..1b7962d25e 100644 --- a/src/native/pe/PeResourcesProvider.ts +++ b/src/native/pe/PeResourcesProvider.ts @@ -1,10 +1,9 @@ -import { BinaryFormatFailure } from "../../domain/binaryContainer.js"; import { imageFileSizeRemediation, projectSelectedArtifactFileFailure, projectOwnedArtifactIdentityFailure, + projectOwnedArtifactInputFailure, projectStableArtifactFailure, - stableArtifactInputFailure, projectArtifactCloseFailure, ArtifactReaderFailure, type StableArtifactSnapshot, @@ -21,7 +20,6 @@ import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; import { AnalysisInputError, AnalysisResourceConstraintError, - AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js"; import { MAX_INSPECT_PE_DIRECTORY_ENTRIES, @@ -109,14 +107,6 @@ const peResourcesFailurePrimary = ( ) => { const { cause, origin } = facts; const operation = "inspect_pe_resources"; - if (cause instanceof BinaryFormatFailure && cause.kind === "unsupported") - return new AnalysisUnsupportedTargetError( - operation, - input.path, - cause.message, - { cause }, - ); - const identityFailure = projectOwnedArtifactIdentityFailure( facts, operation, @@ -124,6 +114,13 @@ const peResourcesFailurePrimary = ( ); if (identityFailure !== undefined) return identityFailure; + const inputFailure = projectOwnedArtifactInputFailure( + facts, + operation, + input.path, + ); + if (inputFailure !== undefined) return inputFailure; + if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure @@ -166,8 +163,6 @@ const peResourcesFailurePrimary = ( }, ); } - if (cause.reason === "path" || cause.reason === "format") - return stableArtifactInputFailure(cause, operation); } const fileFailure = projectSelectedArtifactFileFailure( diff --git a/src/resources/ArtifactFileOperation.ts b/src/resources/ArtifactFileOperation.ts index 3371590a0e..af9bf735f5 100644 --- a/src/resources/ArtifactFileOperation.ts +++ b/src/resources/ArtifactFileOperation.ts @@ -248,9 +248,8 @@ export const assertArtifactReadActive = ( /** * Project a failure raised by a domain byte parser over artifact bytes onto the * reader's reasons: the caller's cancellation (`signal.reason`) becomes - * `cancelled`, malformed or truncated structure `format`, and a decode budget - * `limit` bounded by `limitBoundary`. Unsupported forms and every other cause - * pass through unchanged. + * `cancelled`, parser failure kinds stay distinct, and a decode budget is + * bounded by `limitBoundary`. Every other cause passes through unchanged. */ export const artifactParseFailure = ( cause: unknown, @@ -263,8 +262,6 @@ export const artifactParseFailure = ( }); if (!(cause instanceof ParseFailureError)) return cause; const { failure } = cause; - if (failure.kind === "malformed" || failure.kind === "truncated") - return new ArtifactReaderFailure("format", cause.message, { cause }); if (failure.kind === "limit") { const boundary = limitBoundary?.(failure.limit); return new ArtifactReaderFailure("limit", cause.message, { @@ -272,7 +269,7 @@ export const artifactParseFailure = ( ...(boundary === undefined ? {} : { boundary }), }); } - return cause; + return new ArtifactReaderFailure(failure.kind, cause.message, { cause }); }; /** Recognize only the originating caller's cancellation without discarding cleanup ownership. */ diff --git a/src/resources/ArtifactOperationFailure.test.ts b/src/resources/ArtifactOperationFailure.test.ts index f0e9507eb5..7d81b6797b 100644 --- a/src/resources/ArtifactOperationFailure.test.ts +++ b/src/resources/ArtifactOperationFailure.test.ts @@ -1,4 +1,5 @@ import { expect, it } from "vitest"; +import { createHash } from "node:crypto"; import { ArtifactReaderFailure, @@ -9,13 +10,179 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { constants as bufferConstants } from "node:buffer"; import { imageFileSizeRemediation, + projectOwnedArtifactInputFailure, + projectStableArtifactFailure, readerIntegrityFailure, } from "./StableArtifactFailure.js"; import { artifactIntegrityDetails } from "../domain/artifactIntegrity.js"; -import { ArtifactFileCleanupFailure } from "./ArtifactFileOperation.js"; +import { + ArtifactFileCleanupFailure, + artifactFilePrimaryFacts, + artifactParseFailure, +} from "./ArtifactFileOperation.js"; import { AnalysisCleanupLease } from "./AnalysisCleanupLease.js"; import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js"; import { artifactReaderLimitFailure } from "./index.js"; +import { + malformedInput, + truncatedInput, + unsupportedInput, +} from "../domain/parseFailure.js"; + +it.each([ + malformedInput("pe", "bad field"), + truncatedInput("pe", "short field"), + unsupportedInput("pe", "unsupported image"), +])( + "preserves selected input projection and partial identity through cleanup retry: $kind", + async (cause) => { + const path = "/selected/./program.exe"; + const operation = "inspect_pe_resources"; + const failure = artifactParseFailure(cause, undefined); + expect(failure).toMatchObject({ cause }); + let attempts = 0; + const lease = new AnalysisCleanupLease(async () => { + if (attempts++ === 0) throw new Error("cleanup retry failed"); + }, [path]); + const wrapped = new ArtifactFileCleanupFailure( + new RegularFileCleanupFailure({ + path, + owner: { close: async () => undefined } as never, + outcome: { kind: "failed", cause: failure }, + cleanupCause: new Error("close failed"), + }), + lease, + ); + const primary = projectOwnedArtifactInputFailure( + artifactFilePrimaryFacts(wrapped), + operation, + path, + ); + if (primary === undefined) + throw new Error("Expected a selected-input projection"); + expect(primary.cause).toBe(failure); + const bytes = Buffer.from("inert snapshot"); + const sha256 = createHash("sha256").update(bytes).digest("hex"); + const projected = projectStableArtifactFailure( + wrapped, + primary, + path, + "pe-fixture", + operation, + { bytes, sha256 }, + ); + expect(projectAnalysisError(projected)).toMatchObject({ + code: "cleanup_incomplete", + }); + await expect(lease.release()).rejects.toThrow("cleanup retry failed"); + expect(projectAnalysisError(projected)).toMatchObject({ + code: "cleanup_incomplete", + }); + await lease.release(); + expect(projectAnalysisError(projected)).toMatchObject({ + code: + cause.kind === "unsupported" ? "unsupported_target" : "invalid_request", + details: + cause.kind === "unsupported" + ? { operation, path, reason: cause.message } + : { + operation, + issues: [ + { + path: ["path"], + reason: "invalid_format", + message: cause.message, + }, + ], + }, + }); + expect(projected.partialObservation).toEqual({ + kind: "file-snapshot-hash", + path, + sha256, + bytes: bytes.length, + }); + }, +); + +it("leaves opaque operation errors and decode limits with their owning projection", () => { + const unsupported = artifactParseFailure( + unsupportedInput("pe", "unsupported"), + undefined, + ); + expect( + projectOwnedArtifactInputFailure( + { cause: unsupported, origin: "opaque-operation" }, + "inspect_pe_resources", + "/selected.exe", + ), + ).toBeUndefined(); + expect( + projectOwnedArtifactInputFailure( + { + cause: new ArtifactReaderFailure("limit", "budget"), + origin: "owned-or-classified", + }, + "inspect_pe_resources", + "/selected.exe", + ), + ).toBeUndefined(); +}); + +it.each([ + { + cause: malformedInput("fixture", "bad field"), + code: "invalid_request", + category: "invalid_input", + }, + { + cause: truncatedInput("fixture", "short field"), + code: "truncated", + category: "truncated", + }, + { + cause: unsupportedInput("fixture", "new revision"), + code: "unsupported_target", + category: "unsupported_target", + }, +])( + "preserves $cause.kind parser facts after cleanup retry", + async ({ cause, code, category }) => { + const readerFailure = artifactParseFailure(cause, undefined); + if (!(readerFailure instanceof ArtifactReaderFailure)) + throw new Error( + "Parser failure did not become an artifact reader failure", + ); + expect(readerFailure).toMatchObject({ reason: cause.kind, cause }); + const lease = new AnalysisCleanupLease(async () => {}, [ + "fixture descriptor", + ]); + const wrapped = ArtifactReaderFailure.withCleanup( + readerFailure, + { reason: "close failed", resources: ["fixture descriptor"] }, + undefined, + [lease], + ); + const projectedOwner = translateArtifactFailure( + "inspect_artifact", + wrapped, + ); + expect(projectAnalysisError(projectedOwner)).toMatchObject({ + code: "cleanup_incomplete", + details: { + reason: cause.kind, + detail: cause.message, + cleanup: "incomplete", + }, + }); + await lease.release(); + expect(projectAnalysisError(projectedOwner)).toMatchObject({ + code, + category, + details: { reason: cause.kind, detail: cause.message }, + }); + }, +); // The provider ceiling test uses a sparse file and is skipped on Windows. it.skipIf(process.platform !== "win32")( diff --git a/src/resources/ArtifactReader.ts b/src/resources/ArtifactReader.ts index b1bdc0aa9b..acea3a7bdc 100644 --- a/src/resources/ArtifactReader.ts +++ b/src/resources/ArtifactReader.ts @@ -4,6 +4,7 @@ import type { ArtifactAdmissionLimit, ArtifactIntegrityCheck, ArtifactLimitBoundary, + ArtifactOperationError, } from "../domain/artifactOperationError.js"; import type { ArtifactContainerIntegrityPair, @@ -233,6 +234,7 @@ export interface ArtifactReader { | "unityfs" | "wxapkg" | "uimage" + | "android-boot-image" | "pyinstaller" | "dotnet-bundle" | "bun-standalone" @@ -271,14 +273,7 @@ export type CleanupFailedRead = ArtifactReaderFailure & { }; /** Why an artifact reader failed. */ -export type ArtifactReaderFailureReason = - | "cancelled" - | "format" - | "integrity" - | "io" - | "limit" - | "path" - | "unavailable"; +export type ArtifactReaderFailureReason = ArtifactOperationError["reason"]; export class ArtifactReaderFailure extends Error { readonly userMessage: string | undefined; @@ -469,8 +464,10 @@ export const artifactFixedLimitFailure = ( allowance: ArtifactFixedLimit, outcome: string, boundary: ArtifactLimitBoundary = "capacity", + options?: ErrorOptions, ): ArtifactReaderFailure => new ArtifactReaderFailure("limit", outcome, { + ...options, boundary, userMessage: outcome, fixedAllowance: allowance, diff --git a/src/resources/StableArtifactFailure.ts b/src/resources/StableArtifactFailure.ts index 1dfd12cb03..f71efe21ec 100644 --- a/src/resources/StableArtifactFailure.ts +++ b/src/resources/StableArtifactFailure.ts @@ -17,6 +17,7 @@ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, + AnalysisUnsupportedTargetError, cancelledBy, carriedReason, } from "../domain/analysisErrorCore.js"; @@ -63,6 +64,32 @@ export const projectOwnedArtifactIdentityFailure = ( /** The request field that selected a file: a name, or a path into the request. */ export type RequestField = string | readonly (string | number)[]; +/** Keep a selected parser refusal's established path and structured input projection. */ +export const projectOwnedArtifactInputFailure = ( + { cause, origin }: ArtifactFilePrimaryFacts, + operation: string, + path: string, + field: RequestField = "path", +): AnalysisError | undefined => { + if ( + origin !== "owned-or-classified" || + !(cause instanceof ArtifactReaderFailure) + ) + return undefined; + if (cause.reason === "unsupported") + return new AnalysisUnsupportedTargetError(operation, path, cause.message, { + cause, + }); + if ( + cause.reason === "malformed" || + cause.reason === "truncated" || + cause.reason === "format" || + cause.reason === "path" + ) + return stableArtifactInputFailure(cause, operation, field); + return undefined; +}; + const requestFieldPath = (field: RequestField): (string | number)[] => typeof field === "string" ? [field] : [...field]; diff --git a/src/resources/index.ts b/src/resources/index.ts index 8f8fe7e0ca..cb6e893117 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -88,6 +88,7 @@ export { imageFileSizeRemediation, projectArtifactCloseFailure, projectOwnedArtifactIdentityFailure, + projectOwnedArtifactInputFailure, projectSelectedArtifactFileFailure, projectStableArtifactFailure, readerIntegrityFailure, diff --git a/tests/acceptance/androidBootImageCli.test.ts b/tests/acceptance/androidBootImageCli.test.ts new file mode 100644 index 0000000000..c6a770eca8 --- /dev/null +++ b/tests/acceptance/androidBootImageCli.test.ts @@ -0,0 +1,123 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect } from "vitest"; + +import { parseEvidence } from "../../src/domain/evidence.js"; +import { artifactInspectionResultSchema } from "../../src/domain/artifactInspection.js"; +import { + artifactExtractionResultSchema, + artifactInventoryResultSchema, +} from "../../src/domain/artifactGraph.js"; +import { + androidBootImageRefusals, + buildVendorBootImage, +} from "../fixtures/androidBootImage.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { cliTest } from "../support/cli/cliFixture.js"; + +cliTest( + "inspects and extracts a vendor_boot image through the compiled CLI", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-android-boot-cli-"); + const platform = Buffer.from("platform-bytes"); + const recovery = Buffer.from("recovery-bytes"); + const dtb = Buffer.from("vendor-dtb"); + const bootconfig = Buffer.from("androidboot.hardware=test\n"); + const source = join(root, "vendor_boot.img"); + const callerPath = `${root}/./vendor_boot.img`; + await writeFile( + source, + buildVendorBootImage({ + version: 4, + name: "board", + cmdline: "console=tty0", + ramdisks: [ + { name: "platform", type: 1, bytes: platform }, + { name: "recovery", type: 2, bytes: recovery }, + ], + dtb, + bootconfig, + }), + ); + const inspected = await cli.run({ + arguments: ["inspect-artifact", callerPath, "--json"], + }); + expect(inspected.exitCode, inspected.stdout + inspected.stderr).toBe(0); + const evidence = parseEvidence(inspected.json); + expect(evidence.caller_input_path).toBe(callerPath); + const inspection = artifactInspectionResultSchema.parse( + evidence.normalized_result, + ); + const graph = artifactInventoryResultSchema.parse( + inspection.substeps[0]?.evidence.normalized_result, + ); + expect(graph.manifest.root_format).toBe("android-boot-image"); + expect(graph.coverage.status).toBe("complete"); + expect( + graph.occurrences.find((row) => row.logical_path === ".") + ?.format_metadata, + ).toMatchObject({ + kind: "android-boot-image", + image_kind: "vendor-boot", + magic: "VNDRBOOT", + header_version: 4, + name: "board", + command_line: "console=tty0", + vendor_ramdisk_table_entry_count: 2, + component_count: 4, + }); + const extracted = await cli.run({ + arguments: ["extract-artifact", callerPath, "--json"], + environment: { TMPDIR: root, TMP: root, TEMP: root }, + }); + expect(extracted.exitCode, extracted.stdout + extracted.stderr).toBe(0); + const extractedEvidence = parseEvidence(extracted.json); + expect(extractedEvidence.caller_input_path).toBe(callerPath); + const result = artifactExtractionResultSchema.parse( + extractedEvidence.normalized_result, + ); + expect(result.containment_verified).toBe(true); + expect( + ( + await readFile(join(result.output_root, "vendor_ramdisk/platform")) + ).equals(platform), + ).toBe(true); + expect( + ( + await readFile(join(result.output_root, "vendor_ramdisk/recovery")) + ).equals(recovery), + ).toBe(true); + expect((await readFile(join(result.output_root, "dtb"))).equals(dtb)).toBe( + true, + ); + expect( + (await readFile(join(result.output_root, "bootconfig"))).equals( + bootconfig, + ), + ).toBe(true); + }, +); + +cliTest( + "keeps Android parser refusal kinds through the compiled CLI", + async ({ cli }) => { + const root = await createTestTempDirectory( + "rea-android-boot-cli-refusals-", + ); + for (const fixture of androidBootImageRefusals()) { + const path = join(root, `${fixture.name}.img`); + await writeFile(path, fixture.bytes); + const result = await cli.run({ + arguments: ["inspect-artifact", path, "--json"], + }); + expect(result.exitCode, result.stdout + result.stderr).toBe(1); + expect(result.json).toMatchObject({ + code: fixture.code, + category: fixture.category, + details: { operation: "inspect_artifact", reason: fixture.kind }, + }); + expect((await readFile(path)).equals(fixture.bytes)).toBe(true); + } + }, +); diff --git a/tests/boundary/mcp/androidBootImageMcp.test.ts b/tests/boundary/mcp/androidBootImageMcp.test.ts new file mode 100644 index 0000000000..9035489be9 --- /dev/null +++ b/tests/boundary/mcp/androidBootImageMcp.test.ts @@ -0,0 +1,145 @@ +import { createHash } from "node:crypto"; +import { readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect, it } from "vitest"; + +import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js"; +import { artifactExtractionResultSchema } from "../../../src/domain/artifactGraph.js"; +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { + appendAvbFooter, + androidBootImageRefusals, + buildBootImage, + osVersionRaw, +} from "../../fixtures/androidBootImage.js"; +import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; + +it("retains Android boot image facts through compiled MCP", async () => { + const root = await createTestTempDirectory("rea-android-boot-mcp-"); + const path = join(root, "boot.img"); + const kernel = Buffer.from([0x7f, 0x45, 0x4c, 0x46, 2, 1, 1, 0]); + const ramdisk = Buffer.from([0x1f, 0x8b, 0x08, 0, 0x61]); + const signature = Buffer.from("boot-signature"); + const image = buildBootImage({ + version: 4, + kernel, + ramdisk, + signature, + cmdline: "console=tty0", + osVersion: osVersionRaw(13, 0, 0, 2024, 11), + }); + const bytes = appendAvbFooter(image); + await writeFile(path, bytes); + const { call } = await connectLocalToolsMcp({ + REA_MCP_INPUT_SCHEMA_PROFILE: "compact", + }); + let outputRoot: string | undefined; + try { + const opened = await call("open_binary", { path }); + expect(opened.isError, JSON.stringify(opened)).not.toBe(true); + expect(opened.structuredContent).toMatchObject({ + result: { + kind: "archive", + format: "android-boot-image", + architecture: null, + }, + }); + const reply = await call("inspect_artifact", {}); + expect(reply.isError, JSON.stringify(reply)).not.toBe(true); + const inspection = artifactInspectionResultSchema.parse( + parseEvidence(reply.structuredContent).normalized_result, + ); + const inventory = inspection.substeps[0]!.evidence.normalized_result; + expect(inventory.coverage.status).toBe("complete"); + expect(inventory.occurrences).toContainEqual( + expect.objectContaining({ + logical_path: ".", + format_metadata: expect.objectContaining({ + kind: "android-boot-image", + header_version: 4, + os_version: "13.0.0", + security_patch_level: "2024-11", + command_line: "console=tty0", + signature_size: signature.length, + avb_footer_present: true, + avb_footer_size: 64, + }), + }), + ); + expect(inventory.occurrences).toContainEqual( + expect.objectContaining({ + logical_path: "ramdisk", + format_metadata: expect.objectContaining({ compression: "gzip" }), + source_location: { offset: 8192, length: ramdisk.length }, + }), + ); + expect(inventory.occurrences).toContainEqual( + expect.objectContaining({ + logical_path: "signature", + source_location: { offset: 12288, length: signature.length }, + }), + ); + expect(inventory.nodes).toContainEqual( + expect.objectContaining({ + sha256: createHash("sha256").update(ramdisk).digest("hex"), + }), + ); + const extracted = await call("extract_artifact", {}); + expect(extracted.isError, JSON.stringify(extracted)).not.toBe(true); + const result = artifactExtractionResultSchema.parse( + parseEvidence(extracted.structuredContent).normalized_result, + ); + outputRoot = result.output_root; + expect(result.containment_verified).toBe(true); + expect(result.cleanup).toMatchObject({ + verified: true, + residual_paths: [], + }); + expect((await readFile(join(outputRoot, "kernel"))).equals(kernel)).toBe( + true, + ); + expect((await readFile(join(outputRoot, "ramdisk"))).equals(ramdisk)).toBe( + true, + ); + expect( + (await readFile(join(outputRoot, "signature"))).equals(signature), + ).toBe(true); + expect((await readFile(path)).equals(bytes)).toBe(true); + await call("close_binary", {}); + } finally { + if (outputRoot !== undefined) + await rm(outputRoot, { recursive: true, force: true }); + } +}); + +it("keeps Android parser refusal kinds and recovers through compiled MCP", async () => { + const root = await createTestTempDirectory("rea-android-boot-mcp-refusals-"); + const { call } = await connectLocalToolsMcp({ + REA_MCP_INPUT_SCHEMA_PROFILE: "compact", + }); + try { + for (const fixture of androidBootImageRefusals()) { + const path = join(root, `${fixture.name}.img`); + await writeFile(path, fixture.bytes); + const opened = await call("open_binary", { path }); + expect(opened.isError, JSON.stringify(opened)).not.toBe(true); + const { error } = parseMcpToolError(await call("inspect_artifact", {})); + expect(error).toMatchObject({ + code: fixture.code, + category: fixture.category, + details: { operation: "inspect_artifact", reason: fixture.kind }, + }); + expect((await readFile(path)).equals(fixture.bytes)).toBe(true); + expect((await call("close_binary", {})).isError).not.toBe(true); + } + const path = join(root, "valid.img"); + await writeFile(path, buildBootImage({ version: 0 })); + expect((await call("open_binary", { path })).isError).not.toBe(true); + expect((await call("inspect_artifact", {})).isError).not.toBe(true); + } finally { + await call("close_binary", {}); + } +}); diff --git a/tests/fixtures/androidBootImage.ts b/tests/fixtures/androidBootImage.ts new file mode 100644 index 0000000000..dbd357b0dd --- /dev/null +++ b/tests/fixtures/androidBootImage.ts @@ -0,0 +1,438 @@ +/** + * Synthetic Android boot and vendor_boot images. + * Field offsets follow the v0-v4 and vendor v3/v4 layouts directly. + */ + +const BOOT_V3_PAGE = 4096; +const LEGACY_V1 = 1648; +const LEGACY_V2 = 1660; +const MODERN_V3 = 1580; +const MODERN_V4 = 1584; +const VENDOR_V3 = 2112; +const VENDOR_V4 = 2128; +/** `vendor_ramdisk_table_entry_v4`: 12-byte prefix, 32-byte name, 16 board ids. */ +const VENDOR_ENTRY = 108; +const VENDOR_RAMDISK_NAME_SIZE = 32; +const VENDOR_RAMDISK_BOARD_ID_OFFSET = 44; + +export interface BootImageOptions { + readonly version: 0 | 1 | 2 | 3 | 4; + readonly pageSize?: number; + readonly headerSize?: number; + readonly kernel?: Buffer; + readonly ramdisk?: Buffer; + readonly second?: Buffer; + readonly recoveryDtbo?: Buffer; + /** File offset. Omit to place the DTBO on the sequential page cursor. */ + readonly recoveryDtboOffset?: number; + readonly dtb?: Buffer; + readonly signature?: Buffer; + readonly name?: string; + readonly cmdline?: string; + readonly extraCmdline?: string; + readonly osVersion?: number; + readonly kernelAddr?: number; + readonly ramdiskAddr?: number; + readonly secondAddr?: number; + readonly tagsAddr?: number; + readonly dtbAddr?: number; + readonly headerDigest?: Buffer; +} + +export interface VendorRamdiskFixture { + readonly name?: string; + readonly type?: number; + readonly bytes: Buffer; + readonly boardId?: Buffer; +} + +export interface VendorBootImageOptions { + readonly version: 3 | 4; + readonly pageSize?: number; + readonly headerSize?: number; + readonly name?: string; + readonly cmdline?: string; + readonly kernelAddr?: number; + readonly ramdiskAddr?: number; + readonly tagsAddr?: number; + readonly dtbAddr?: number; + readonly dtb?: Buffer; + /** Version 3 section bytes. Empty omits the vendor_ramdisk child. */ + readonly ramdisk?: Buffer; + /** Version 4 table entries. Their bytes are concatenated into the section. */ + readonly ramdisks?: readonly VendorRamdiskFixture[]; + /** Section bytes with no table entries. Use to leave the section uncovered. */ + readonly section?: Buffer; + readonly bootconfig?: Buffer; + readonly entrySize?: number; +} + +interface Placement { + readonly offset: number; + readonly bytes: Buffer; +} + +/** Pack the boot header os_version word. `year` is the calendar year. */ +export const osVersionRaw = ( + major: number, + minor: number, + patch: number, + year: number, + month: number, +): number => + ((major & 0x7f) << 25) | + ((minor & 0x7f) << 18) | + ((patch & 0x7f) << 11) | + (((year - 2000) & 0x7f) << 4) | + (month & 0xf); + +const alignUp = (value: number, page: number): number => { + const remainder = value % page; + return remainder === 0 ? value : value + (page - remainder); +}; + +const writeU32 = (buffer: Buffer, offset: number, value: number): void => { + buffer.writeUInt32LE(value >>> 0, offset); +}; + +const writeU64 = (buffer: Buffer, offset: number, value: number): void => { + writeU32(buffer, offset, value >>> 0); + writeU32(buffer, offset + 4, Math.floor(value / 2 ** 32)); +}; + +const writeU64be = (buffer: Buffer, offset: number, value: number): void => { + buffer.writeUInt32BE(Math.floor(value / 2 ** 32), offset); + buffer.writeUInt32BE(value >>> 0, offset + 4); +}; + +const writeText = ( + buffer: Buffer, + offset: number, + length: number, + text: string, +): void => { + Buffer.from(text, "utf8").copy(buffer, offset, 0, length); +}; + +const place = ( + placed: Placement[], + cursor: number, + page: number, + bytes: Buffer | undefined, +): number => { + if (bytes === undefined || bytes.length === 0) return cursor; + placed.push({ offset: cursor, bytes }); + return alignUp(cursor + bytes.length, page); +}; + +const writeLegacyHeader = ( + image: Buffer, + options: BootImageOptions, + version: 0 | 1 | 2, + page: number, + sizes: { + readonly kernel: number; + readonly ramdisk: number; + readonly second: number; + readonly recovery: number; + readonly recoveryOffset: number; + readonly dtb: number; + }, +): void => { + writeU32(image, 8, sizes.kernel); + writeU32(image, 12, options.kernelAddr ?? 0x8000_8000); + writeU32(image, 16, sizes.ramdisk); + writeU32(image, 20, options.ramdiskAddr ?? 0x8100_0000); + writeU32(image, 24, sizes.second); + writeU32(image, 28, options.secondAddr ?? 0x8110_0000); + writeU32(image, 32, options.tagsAddr ?? 0x8000_0100); + writeU32(image, 36, page); + writeU32(image, 40, version); + writeU32(image, 44, options.osVersion ?? 0); + writeText(image, 48, 16, options.name ?? "board"); + writeText(image, 64, 512, options.cmdline ?? "console=tty0"); + (options.headerDigest ?? Buffer.alloc(32)).copy(image, 576, 0, 32); + writeText( + image, + 608, + 1024, + options.extraCmdline ?? " androidboot.hardware=test", + ); + if (version === 0) return; + writeU32(image, 1632, sizes.recovery); + writeU64(image, 1636, sizes.recoveryOffset); + writeU32( + image, + 1644, + options.headerSize ?? (version === 1 ? LEGACY_V1 : LEGACY_V2), + ); + if (version < 2) return; + writeU32(image, LEGACY_V1, sizes.dtb); + writeU64(image, LEGACY_V1 + 4, options.dtbAddr ?? 0x8200_0000); +}; + +const writeModernHeader = ( + image: Buffer, + options: BootImageOptions, + version: 3 | 4, + sizes: { + readonly kernel: number; + readonly ramdisk: number; + readonly signature: number; + }, +): void => { + writeU32(image, 8, sizes.kernel); + writeU32(image, 12, sizes.ramdisk); + writeU32(image, 16, options.osVersion ?? 0); + writeU32( + image, + 20, + options.headerSize ?? (version === 4 ? MODERN_V4 : MODERN_V3), + ); + writeU32(image, 40, version); + writeText( + image, + 44, + 1536, + `${options.cmdline ?? "console=tty0"}${options.extraCmdline ?? ""}`, + ); + if (version === 4) writeU32(image, MODERN_V3, sizes.signature); +}; + +/** Build a page-padded ANDROID! image. Zero-length components are omitted. */ +export const buildBootImage = (options: BootImageOptions): Buffer => { + const version = options.version; + const modern = version >= 3; + const page = modern ? BOOT_V3_PAGE : (options.pageSize ?? 2048); + const kernel = options.kernel ?? Buffer.from("kernel"); + const ramdisk = options.ramdisk ?? Buffer.from("ramdisk"); + const second = options.second ?? Buffer.alloc(0); + const recovery = !modern && version >= 1 ? options.recoveryDtbo : undefined; + const dtb = !modern && version >= 2 ? options.dtb : undefined; + const signature = version === 4 ? options.signature : undefined; + const placed: Placement[] = []; + let cursor = page; + cursor = place(placed, cursor, page, kernel); + cursor = place(placed, cursor, page, ramdisk); + if (!modern) cursor = place(placed, cursor, page, second); + let recoveryOffset = 0; + if (recovery !== undefined && recovery.length > 0) { + recoveryOffset = options.recoveryDtboOffset ?? cursor; + placed.push({ offset: recoveryOffset, bytes: recovery }); + cursor = Math.max(cursor, alignUp(recoveryOffset + recovery.length, page)); + } + if (!modern && version >= 2) cursor = place(placed, cursor, page, dtb); + if (version === 4) cursor = place(placed, cursor, page, signature); + const image = Buffer.alloc(cursor); + image.write("ANDROID!", 0, "ascii"); + const sizes = { + kernel: kernel.length, + ramdisk: ramdisk.length, + second: second.length, + recovery: recovery?.length ?? 0, + recoveryOffset, + dtb: dtb?.length ?? 0, + signature: signature?.length ?? 0, + }; + switch (version) { + case 0: + case 1: + case 2: + writeLegacyHeader(image, options, version, page, sizes); + break; + case 3: + case 4: + writeModernHeader(image, options, version, sizes); + break; + } + for (const item of placed) item.bytes.copy(image, item.offset); + return image; +}; + +const vendorRamdiskTable = ( + ramdisks: readonly VendorRamdiskFixture[], + entrySize: number, +): Buffer => { + const table = Buffer.alloc(ramdisks.length * entrySize); + let offset = 0; + for (const [index, ramdisk] of ramdisks.entries()) { + const base = index * entrySize; + writeU32(table, base, ramdisk.bytes.length); + writeU32(table, base + 4, offset); + writeU32(table, base + 8, ramdisk.type ?? 0); + writeText(table, base + 12, VENDOR_RAMDISK_NAME_SIZE, ramdisk.name ?? ""); + ramdisk.boardId?.copy(table, base + VENDOR_RAMDISK_BOARD_ID_OFFSET, 0, 64); + offset += ramdisk.bytes.length; + } + return table; +}; + +const writeVendorHeader = ( + image: Buffer, + options: VendorBootImageOptions, + facts: { + readonly version: 3 | 4; + readonly page: number; + readonly headerSize: number; + readonly sectionSize: number; + readonly dtbSize: number; + readonly tableSize: number; + readonly entryCount: number; + readonly entrySize: number; + readonly bootconfigSize: number; + }, +): void => { + image.write("VNDRBOOT", 0, "ascii"); + writeU32(image, 8, facts.version); + writeU32(image, 12, facts.page); + writeU32(image, 16, options.kernelAddr ?? 0x8000_8000); + writeU32(image, 20, options.ramdiskAddr ?? 0x8100_0000); + writeU32(image, 24, facts.sectionSize); + writeText(image, 28, 2048, options.cmdline ?? "console=tty0"); + writeU32(image, 2076, options.tagsAddr ?? 0x8000_0100); + writeText(image, 2080, 16, options.name ?? "board"); + writeU32(image, 2096, facts.headerSize); + writeU32(image, 2100, facts.dtbSize); + writeU64(image, 2104, options.dtbAddr ?? 0x8200_0000); + if (facts.version < 4) return; + writeU32(image, VENDOR_V3, facts.tableSize); + writeU32(image, VENDOR_V3 + 4, facts.entryCount); + writeU32(image, VENDOR_V3 + 8, facts.entrySize); + writeU32(image, VENDOR_V3 + 12, facts.bootconfigSize); +}; + +/** Build a page-padded VNDRBOOT image. The v4 table is not a child. */ +export const buildVendorBootImage = ( + options: VendorBootImageOptions, +): Buffer => { + const version = options.version; + const page = options.pageSize ?? 4096; + const headerSize = + options.headerSize ?? (version === 4 ? VENDOR_V4 : VENDOR_V3); + const ramdisks = options.ramdisks ?? []; + const entrySize = options.entrySize ?? VENDOR_ENTRY; + const section = + options.section ?? + (version === 3 + ? (options.ramdisk ?? Buffer.alloc(0)) + : Buffer.concat(ramdisks.map((item) => item.bytes))); + const dtb = options.dtb ?? Buffer.alloc(0); + const bootconfig = + version === 4 ? (options.bootconfig ?? Buffer.alloc(0)) : Buffer.alloc(0); + const table = + version === 4 && ramdisks.length > 0 + ? vendorRamdiskTable(ramdisks, entrySize) + : Buffer.alloc(0); + const placed: Placement[] = []; + let cursor = alignUp(headerSize, page); + const sectionOffset = cursor; + if (section.length > 0) + cursor = alignUp(sectionOffset + section.length, page); + cursor = place(placed, cursor, page, dtb); + cursor = place(placed, cursor, page, table); + cursor = place(placed, cursor, page, bootconfig); + const image = Buffer.alloc(cursor); + writeVendorHeader(image, options, { + version, + page, + headerSize, + sectionSize: section.length, + dtbSize: dtb.length, + tableSize: table.length, + entryCount: ramdisks.length, + entrySize, + bootconfigSize: bootconfig.length, + }); + if (section.length > 0) section.copy(image, sectionOffset); + for (const item of placed) item.bytes.copy(image, item.offset); + return image; +}; + +/** Append an AVBf footer. Sizes are written; nothing is signed. */ +export const appendAvbFooter = ( + image: Buffer, + options: { + readonly vbmeta?: Buffer; + readonly vbmetaOffset?: number; + readonly originalImageSize?: number; + readonly partitionSize?: number; + } = {}, +): Buffer => { + const vbmeta = options.vbmeta ?? Buffer.from("vbmeta-test"); + const vbmetaOffset = options.vbmetaOffset ?? image.length; + const originalImageSize = options.originalImageSize ?? image.length; + const minimum = Math.max(image.length, vbmetaOffset + vbmeta.length) + 64; + const partitionSize = options.partitionSize ?? minimum; + if (partitionSize < minimum) + throw new Error("partition is shorter than the image, vbmeta, and footer"); + if (vbmetaOffset + vbmeta.length > partitionSize - 64) + throw new Error("vbmeta does not fit before the footer"); + const out = Buffer.alloc(partitionSize); + image.copy(out, 0, 0, Math.min(image.length, out.length)); + vbmeta.copy(out, vbmetaOffset); + const footerAt = partitionSize - 64; + out.write("AVBf", footerAt, "ascii"); + out.writeUInt32BE(1, footerAt + 4); + out.writeUInt32BE(0, footerAt + 8); + writeU64be(out, footerAt + 12, originalImageSize); + writeU64be(out, footerAt + 20, vbmetaOffset); + writeU64be(out, footerAt + 28, vbmeta.length); + return out; +}; + +/** Drop the final byte. The view is a copy, so the source image stays intact. */ +export const truncateImage = (image: Buffer): Buffer => + Buffer.from(image.subarray(0, Math.max(0, image.length - 1))); + +/** + * Rewrite a v4 vendor table count. `entry_size` stays 108 and `table_size` + * becomes `count * 108`. + */ +export const declareVendorRamdiskCount = ( + image: Buffer, + count: number, +): Buffer => { + const copy = Buffer.from(image); + writeU32(copy, VENDOR_V3, count * VENDOR_ENTRY); + writeU32(copy, VENDOR_V3 + 4, count); + return copy; +}; +/** Small byte-format refusals for the public artifact adapters. */ +export const androidBootImageRefusals = () => { + const unsupportedBoot = buildBootImage({ version: 0 }); + unsupportedBoot.writeUInt32LE(5, 40); + const unsupportedVendor = buildVendorBootImage({ version: 4 }); + unsupportedVendor.writeUInt32LE(5, 8); + const malformed = buildBootImage({ version: 0 }); + malformed.writeUInt32LE(1024, 36); + return [ + { + name: "boot-version", + bytes: unsupportedBoot, + kind: "unsupported", + code: "unsupported_target", + category: "unsupported_target", + }, + { + name: "vendor-version", + bytes: unsupportedVendor, + kind: "unsupported", + code: "unsupported_target", + category: "unsupported_target", + }, + { + name: "short-image", + bytes: truncateImage(buildBootImage({ version: 0 })), + kind: "truncated", + code: "truncated", + category: "truncated", + }, + { + name: "bad-page", + bytes: malformed, + kind: "malformed", + code: "invalid_request", + category: "invalid_input", + }, + ] as const; +};