Files
reverse-engineering-anything/docs/specs/native/kernel-build-config/spec.md
T
morluto acb10754c1 refactor(native)!: report kernel build config coverage as partial or unknown instead of incomplete (#11486)
inspect_kernel_build_config coverage.status was `incomplete` for a config cut by the
searched bytes or a budget-stopped search (known gaps), for a malformed framed
config, and for a payload that was never searched (examined_bytes 0). Coverage
now uses the shared status: `partial` for the known gaps, `unknown` when a
config's existence or contents cannot be determined; `unsupported` is
unchanged. config.status keeps its own values, and the service's consistency
check pairs each config state with its coverage.

BREAKING CHANGE: inspect_kernel_build_config `coverage.status` reports `partial`
(config_gzip_truncated, config_search_exhausted) or `unknown` (malformed config,
payload not searched) instead of `incomplete`.
2026-11-16 05:01:36 +08:00

81 lines
4.3 KiB
Markdown

# Linux kernel build config
## Problem and outcome
Analysing a Linux kernel image usually starts with two questions: which kernel
version is this, and how was it configured. A kernel built with
`CONFIG_IKCONFIG` embeds its `.config` as a gzip blob between `IKCFG_ST` and
`IKCFG_ED`. REA reports kernel modules and ELF notes, but it cannot read the
version banner or the embedded config, so an agent needs a Linux host and
`scripts/extract-ikconfig`.
This feature adds `inspect_kernel_build_config` and
`inspect-kernel-build-config`. They read one selected local kernel image and
report its `Linux version` banner and embedded build config, without
executing or booting it.
[Linux kernel build config](../../../guides/native/kernel-build-config.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. Accepted inputs are a `vmlinux` ELF, a raw arm64 `Image`, an x86 `bzImage`
or `zImage` whose payload is gzip, and a `configs.ko` module. The file is
read through the stable artifact read and never executed.
2. The banner is the first printable `Linux version ` string followed by a
version token that starts with a digit and ends at a NUL or newline within
512 bytes. Version, builder and compiler are split from it. A banner with a
space right after `#` or at its end is the kbuild placeholder from
`init/version.o`, built without a build number or timestamp; a later banner
that repeats its text up to `#` without that gap replaces it. The scan is
linear in the searched bytes.
3. A config is `present` only when `IKCFG_ST` is followed by a gzip member that
ends exactly at the next `IKCFG_ED`, inflates within `max_config_bytes`,
passes its CRC-32 and ISIZE checks, and parses as `.config` text. Inflation
reads only the bytes up to that marker.
4. Framing that fails its checks or grammar, including a framed deflate stream
that does not decode or is cut off by `IKCFG_ED`, is `malformed`, never
`absent`. An unframed `IKCFG_ST` string is skipped. A valid config later in the bytes
still wins.
5. Entries report name, kind (`y`, `m`, `number`, `string`, `not_set`) and
value, with an exact `name` filter and `offset`/`limit` paging.
6. A bzImage setup header from boot protocol 2.08 locates the payload. A gzip
payload is inflated within `max_payload_bytes` and searched, with locations
marked `inflated_payload`. Other payload codecs, and a file that is itself a
compressed stream such as `Image.gz`, are `unsupported` and name the codec,
using the codec detection shared with the kernel module parser.
7. Budgets bound file size, config and payload inflate size, option count and
page size. The config search inflates at most 16 candidates and at most
four times `max_config_bytes` in total, charging a stream that fails
partway through its full per-candidate allowance. Exhausting the search budget is
`incomplete` with `config_search_exhausted` and coverage `partial`; a
member cut by the searched bytes is also `partial`. A malformed framed
config, or a payload that could not be searched, has coverage `unknown`. A member past
`max_config_bytes` fails the budget only when no later candidate is
accepted.
8. Cancellation is checked between candidates, between banner hits, while
scanning long text and while parsing config lines. Inflation runs off the
event loop and each scan, including marker searches that find nothing, text
checks, validation of a single long value and hashing, yields to it at least once per MiB, so a live
cancellation reaches those checks.
9. Banner text and config values are marked target-derived and untrusted.
10. MCP requires an absolute path. The CLI resolves relative paths against the
working directory.
## Acceptance
- Unit tests cover banner parsing, config framing, grammar, malformed and
truncated members, decoy candidates, search budgets, cancellation, and
bzImage payload handling.
- Service tests cover each status and reason.
- CLI acceptance, filesystem boundary and MCP boundary tests exercise the
public contract.
## Non-goals
- Decompressing xz, lz4, lzma, zstd, bzip2 or lzo payloads.
- Comparing the config with a source tree or evaluating Kconfig dependencies.
- Executing or booting the image.