ktstr/distro/
extract.rs

1//! Extraction of prebuilt distro kernel packages (`.rpm` / `.deb`).
2//!
3//! Given one or more downloaded/local kernel packages, this module
4//! materializes the filesystem tree they carry into a destination
5//! directory and locates the artifacts ktstr needs to boot a VM:
6//! the bootable image, module tree, kernel config, `System.map`, and
7//! (from a debuginfo package) `vmlinux`.
8//!
9//! ## Package shapes
10//!
11//! - **Fedora / RHEL**: `kernel-core` carries `vmlinuz`, `config`,
12//!   `System.map`, and `modules.builtin` under
13//!   `/lib/modules/<release>/`; the loadable `.ko.xz` modules live in
14//!   separate `kernel-modules-core` / `kernel-modules` rpms (verified
15//!   against Fedora 44 packages). A `kernel-debuginfo` rpm carries
16//!   `vmlinux` under `/usr/lib/debug/`.
17//! - **Ubuntu / Debian**: the image lives in `linux-image-*` (under
18//!   `/boot/`) and the modules in `linux-modules-*` (under
19//!   `/lib/modules/`, or `/usr/lib/modules/` on usrmerge packages);
20//!   the two debs merge into one tree. A `-dbgsym` ddeb contributes
21//!   `vmlinux`.
22//! - **Arch / SteamOS**: a pacman `.pkg.tar.zst` is a plain
23//!   zstd-compressed tarball; `linux-neptune-*` carries `vmlinuz` and
24//!   the module tree under `/usr/lib/modules/<release>/` (usrmerge)
25//!   with the package arch in the `.PKGINFO` member's `arch = ` field
26//!   (verified against a live jupiter-3.8 package). No kernel
27//!   `.config` is shipped and there is no debuginfo package.
28//!
29//! None of these distros ship `modules.dep` in the package — depmod
30//! generates it at install time — so extraction synthesizes it in
31//! process from each module's `.modinfo` section (see
32//! `ensure_modules_dep`), without relying on a host `depmod`.
33//!
34//! ## Compression
35//!
36//! The `rpm` crate parses package headers; the raw cpio payload is
37//! decompressed here with the already-vendored xz2/zstd/flate2 stack
38//! (Fedora kernels ship xz payloads, newer ones zstd) rather than
39//! pulling rpm's own liblzma backend. deb `data.tar[.xz|.zst|.gz]`
40//! members are streamed through the same vendored decoders.
41//!
42//! ## Hardening
43//!
44//! Every archive entry path is sanitized before it touches disk:
45//! `..` components are a hard error and absolute anchors are stripped
46//! so a payload path like `/lib/modules/...` lands *under* the
47//! destination rather than at the filesystem root. Symlinks whose
48//! target would resolve outside the destination tree are skipped
49//! rather than created. This mirrors the tarball-extraction rigor in
50//! [`crate::fetch`] and [`crate::cgroup`].
51
52use std::collections::{BTreeSet, HashMap, HashSet};
53use std::ffi::OsString;
54use std::fs;
55use std::io::{self, BufReader, Cursor, Read};
56use std::os::unix::fs::PermissionsExt;
57use std::path::{Component, Path, PathBuf};
58
59use anyhow::{Context, Result, anyhow, bail};
60
61/// The artifacts recovered from one or more kernel packages.
62///
63/// Paths are absolute and point inside the destination directory
64/// passed to [`extract_kernel_packages`], except where a field is
65/// `None` because the corresponding package (config, debuginfo, …)
66/// was not supplied.
67#[derive(Debug, Clone)]
68pub struct ExtractedKernel {
69    /// `uname -r`-style kernel release string derived from the
70    /// extracted tree (e.g. `6.14.6-300.fc42.x86_64`).
71    pub kernel_release: String,
72    /// Raw bootable image (x86_64 bzImage, aarch64 flat `Image`),
73    /// normalized from whatever form the package shipped.
74    pub image: PathBuf,
75    /// Kernel `.config`, when the package carries one.
76    pub config: Option<PathBuf>,
77    /// `System.map`, when present.
78    pub system_map: Option<PathBuf>,
79    /// Root directory containing `lib/modules/<release>/…`, suitable
80    /// for [`module_closure`]. `None` when no module tree was found.
81    pub modules_dir: Option<PathBuf>,
82    /// Uncompressed `vmlinux` from a debuginfo package, when supplied.
83    pub vmlinux: Option<PathBuf>,
84}
85
86/// Extract one or more kernel packages into `dest` and locate the
87/// bootable artifacts.
88///
89/// Multiple packages are merged into a single tree under `dest`
90/// (Ubuntu's split image/modules debs, or a Fedora kernel plus its
91/// debuginfo). Every package is checked against the host architecture
92/// before extraction. The kernel release is derived from the merged
93/// tree and it is an error for the packages to disagree on it.
94pub fn extract_kernel_packages(packages: &[&Path], dest: &Path) -> Result<ExtractedKernel> {
95    if packages.is_empty() {
96        bail!("extract_kernel_packages: no packages supplied");
97    }
98    fs::create_dir_all(dest).with_context(|| format!("create destination {}", dest.display()))?;
99    let dest = dest
100        .canonicalize()
101        .with_context(|| format!("canonicalize destination {}", dest.display()))?;
102
103    for pkg in packages {
104        let arch = package_arch(pkg)?;
105        ensure_arch_matches_host(&arch, pkg)?;
106        match package_kind(pkg)? {
107            PackageKind::Rpm => extract_rpm(pkg, &dest)?,
108            PackageKind::Deb => extract_deb(pkg, &dest)?,
109            PackageKind::Pacman => extract_pacman(pkg, &dest)?,
110        }
111    }
112
113    unify_modules_layout(&dest)?;
114    let release = discover_release(&dest)?;
115    let image_src = find_image(&dest, &release).ok_or_else(|| {
116        anyhow!(
117            "no kernel image (lib/modules/{release}/vmlinuz or boot/vmlinuz-{release}) \
118             found under {}",
119            dest.display()
120        )
121    })?;
122    let image = normalize_image(&image_src, &dest, &release)?;
123
124    let modules_root = dest.join(format!("lib/modules/{release}"));
125    let modules_dir = modules_root.is_dir().then(|| dest.clone());
126    if modules_dir.is_some() {
127        ensure_modules_dep(&dest, &release);
128    }
129    Ok(ExtractedKernel {
130        kernel_release: release.clone(),
131        image,
132        config: find_first(
133            &dest,
134            &[
135                format!("boot/config-{release}"),
136                format!("lib/modules/{release}/config"),
137            ],
138        ),
139        system_map: find_first(
140            &dest,
141            &[
142                format!("boot/System.map-{release}"),
143                format!("lib/modules/{release}/System.map"),
144            ],
145        ),
146        vmlinux: find_first(
147            &dest,
148            &[
149                format!("usr/lib/debug/lib/modules/{release}/vmlinux"),
150                format!("usr/lib/debug/boot/vmlinux-{release}"),
151            ],
152        ),
153        modules_dir,
154    })
155}
156
157/// Extract debuginfo package(s) into `dest` — merging onto a kernel
158/// tree already materialized there by [`extract_kernel_packages`] — and
159/// return the `vmlinux` path they carry, if any.
160///
161/// Split out from [`extract_kernel_packages`] so the distro acquisition
162/// path can run its config gate on the kernel packages BEFORE fetching
163/// the (mandatory, up to ~1 GiB) debuginfo: a kernel that cannot boot
164/// under ktstr fails at the gate with no debuginfo bytes crossing the
165/// wire. `release` is the kernel release already discovered from the
166/// kernel tree; the lookup uses the same `vmlinux` candidates
167/// [`extract_kernel_packages`] checks. A second extraction pass into the
168/// same `dest` is safe — the debuginfo packages only add
169/// `usr/lib/debug/…` paths and are arch-checked like any package.
170pub fn extract_vmlinux(packages: &[&Path], dest: &Path, release: &str) -> Result<Option<PathBuf>> {
171    let dest = dest
172        .canonicalize()
173        .with_context(|| format!("canonicalize destination {}", dest.display()))?;
174    for pkg in packages {
175        let arch = package_arch(pkg)?;
176        ensure_arch_matches_host(&arch, pkg)?;
177        match package_kind(pkg)? {
178            PackageKind::Rpm => extract_rpm(pkg, &dest)?,
179            PackageKind::Deb => extract_deb(pkg, &dest)?,
180            PackageKind::Pacman => extract_pacman(pkg, &dest)?,
181        }
182    }
183    Ok(find_first(
184        &dest,
185        &[
186            format!("usr/lib/debug/lib/modules/{release}/vmlinux"),
187            format!("usr/lib/debug/boot/vmlinux-{release}"),
188        ],
189    ))
190}
191
192/// Fold the usrmerge module layout onto the classic one.
193///
194/// Newer Ubuntu debs ship modules under `usr/lib/modules/<rel>/`
195/// (usrmerge) where Fedora rpms use `lib/modules/<rel>/`; on an
196/// installed system `/lib` is a symlink into `/usr`, but the
197/// extracted tree has no such link. Bridge the two `modules`
198/// directories with a relative symlink so every downstream lookup —
199/// image discovery, `modules.dep` synthesis, and `module_closure` —
200/// resolves through the classic `lib/modules/<rel>` path (and vice
201/// versa) regardless of which layout the package shipped.
202fn unify_modules_layout(dest: &Path) -> Result<()> {
203    let classic = dest.join("lib/modules");
204    let usrmerge = dest.join("usr/lib/modules");
205    if usrmerge.is_dir() && !classic.exists() {
206        fs::create_dir_all(dest.join("lib"))?;
207        std::os::unix::fs::symlink("../usr/lib/modules", &classic)
208            .with_context(|| format!("symlink {}", classic.display()))?;
209    } else if classic.is_dir() && !usrmerge.exists() {
210        fs::create_dir_all(dest.join("usr/lib"))?;
211        std::os::unix::fs::symlink("../../lib/modules", &usrmerge)
212            .with_context(|| format!("symlink {}", usrmerge.display()))?;
213    }
214    Ok(())
215}
216
217/// Synthesize `modules.dep` for a package that doesn't ship one.
218///
219/// Neither Fedora's kernel-core rpm nor Ubuntu's linux-modules deb
220/// contains `modules.dep` — depmod generates it at package install
221/// time. Rather than shell out to the host `depmod` (whose kmod may be
222/// unable to decompress the tree's `.ko.xz` modules, silently emitting
223/// an incomplete file), build it in process from each module's
224/// `.modinfo` (see [`build_modules_dep`]). A failure is a warning, not
225/// a hard error: [`module_closure`] still emits an actionable message
226/// if the file is missing when modules are actually requested.
227fn ensure_modules_dep(dest: &Path, release: &str) {
228    let modules_dir = dest.join(format!("lib/modules/{release}"));
229    let dep_path = modules_dir.join("modules.dep");
230    if dep_path.exists() {
231        return;
232    }
233    match build_modules_dep(&modules_dir) {
234        Ok(text) => {
235            if let Err(e) = fs::write(&dep_path, text) {
236                tracing::warn!(
237                    release,
238                    error = %e,
239                    "could not write synthesized modules.dep; module_closure will not resolve dependencies for this tree"
240                );
241            }
242        }
243        Err(e) => tracing::warn!(
244            release,
245            error = %e,
246            "could not synthesize modules.dep; module_closure will not resolve dependencies for this tree"
247        ),
248    }
249}
250
251/// `.modinfo` fields ktstr needs to reconstruct `modules.dep`.
252struct ModInfo {
253    /// The module's registered name (`name=` field), if present.
254    name: Option<String>,
255    /// Direct dependency module names (`depends=`, comma-separated).
256    depends: Vec<String>,
257}
258
259/// Build `modules.dep` text for the module tree rooted at
260/// `modules_dir` (a `lib/modules/<release>/` directory).
261///
262/// Walks every module file, reads its `.modinfo` for the module name
263/// and direct `depends`, and emits one depmod-format line per module:
264/// the module's path, a colon, then the space-separated paths of its
265/// direct dependencies — all relative to `modules_dir`, exactly the
266/// shape [`module_closure`] parses. Dependency names are resolved to
267/// paths through the name→path map; a `depends` entry with no matching
268/// module file (a built-in, or one outside the tree) is dropped, as
269/// real depmod does. Lines are sorted for a deterministic file.
270fn build_modules_dep(modules_dir: &Path) -> Result<String> {
271    let mut entries: Vec<(String, Vec<String>)> = Vec::new();
272    let mut name_to_path: HashMap<String, String> = HashMap::new();
273
274    for entry in walkdir::WalkDir::new(modules_dir).follow_links(false) {
275        let entry = entry.with_context(|| format!("walk {}", modules_dir.display()))?;
276        if !entry.file_type().is_file() || !is_module_file(entry.path()) {
277            continue;
278        }
279        let path = entry.path();
280        let rel = path
281            .strip_prefix(modules_dir)
282            .expect("walkdir entry is under modules_dir")
283            .to_str()
284            .ok_or_else(|| anyhow!("non-utf8 module path {}", path.display()))?
285            .to_string();
286
287        let raw = fs::read(path).with_context(|| format!("read module {}", path.display()))?;
288        let elf = match path.extension().and_then(|e| e.to_str()) {
289            Some("ko") => raw,
290            Some(ext) => decompress_bytes(ext, &raw)
291                .with_context(|| format!("decompress module {}", path.display()))?,
292            None => raw,
293        };
294        let info =
295            parse_modinfo(&elf).with_context(|| format!("read .modinfo of {}", path.display()))?;
296        let name = info.name.unwrap_or_else(|| module_key(&rel));
297        name_to_path.insert(module_key(&name), rel.clone());
298        entries.push((rel, info.depends));
299    }
300
301    let mut lines: Vec<String> = entries
302        .iter()
303        .map(|(rel, depends)| {
304            let deps: Vec<&str> = depends
305                .iter()
306                .filter_map(|d| name_to_path.get(&module_key(d)).map(String::as_str))
307                .collect();
308            if deps.is_empty() {
309                format!("{rel}:")
310            } else {
311                format!("{rel}: {}", deps.join(" "))
312            }
313        })
314        .collect();
315    lines.sort();
316    Ok(lines.join("\n") + "\n")
317}
318
319/// Whether `path`'s basename is a loadable module (`.ko` or a
320/// `.ko.{xz,zst,gz}` compressed module).
321fn is_module_file(path: &Path) -> bool {
322    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
323        return false;
324    };
325    name.ends_with(".ko")
326        || name.ends_with(".ko.xz")
327        || name.ends_with(".ko.zst")
328        || name.ends_with(".ko.gz")
329}
330
331/// Read the `name=` and `depends=` fields from a module's `.modinfo`
332/// ELF section (NUL-separated `key=value` pairs).
333fn parse_modinfo(elf: &[u8]) -> Result<ModInfo> {
334    let obj = goblin::elf::Elf::parse(elf).context("parse module ELF")?;
335    let section = obj
336        .section_headers
337        .iter()
338        .find(|sh| obj.shdr_strtab.get_at(sh.sh_name) == Some(".modinfo"))
339        .ok_or_else(|| anyhow!("module has no .modinfo section"))?;
340    let start = section.sh_offset as usize;
341    let end = start
342        .checked_add(section.sh_size as usize)
343        .ok_or_else(|| anyhow!(".modinfo section size overflows"))?;
344    let blob = elf
345        .get(start..end)
346        .ok_or_else(|| anyhow!(".modinfo section [{start:#x}..{end:#x}] out of bounds"))?;
347
348    let mut name = None;
349    let mut depends = Vec::new();
350    for field in blob.split(|&b| b == 0).filter(|f| !f.is_empty()) {
351        let field =
352            std::str::from_utf8(field).map_err(|_| anyhow!(".modinfo field is not UTF-8"))?;
353        if let Some(v) = field.strip_prefix("name=") {
354            name = Some(v.to_string());
355        } else if let Some(v) = field.strip_prefix("depends=") {
356            depends = v
357                .split(',')
358                .filter(|s| !s.is_empty())
359                .map(str::to_string)
360                .collect();
361        }
362    }
363    Ok(ModInfo { name, depends })
364}
365
366// ---------------------------------------------------------------------------
367// Architecture guard
368// ---------------------------------------------------------------------------
369
370/// Package architecture as spelled by the package itself
371/// (`x86_64`/`aarch64` for rpm, `amd64`/`arm64` for deb).
372pub fn package_arch(path: &Path) -> Result<String> {
373    match package_kind(path)? {
374        PackageKind::Rpm => {
375            let meta = rpm::PackageMetadata::open(path)
376                .with_context(|| format!("parse rpm header {}", path.display()))?;
377            Ok(meta.get_arch()?.to_string())
378        }
379        PackageKind::Deb => deb_arch(path),
380        PackageKind::Pacman => pacman_arch(path),
381    }
382}
383
384/// Canonicalize a distro arch token to ktstr's host-arch spelling,
385/// mapping the deb `amd64`/`arm64` aliases onto `x86_64`/`aarch64`.
386fn canonical_arch(arch: &str) -> Option<&'static str> {
387    match arch.trim().to_ascii_lowercase().as_str() {
388        "x86_64" | "amd64" => Some("x86_64"),
389        "aarch64" | "arm64" => Some("aarch64"),
390        _ => None,
391    }
392}
393
394/// Error unless `pkg_arch` matches the compile-time host architecture
395/// (see [`crate::fetch::arch_info`]).
396pub fn ensure_arch_matches_host(pkg_arch: &str, pkg: &Path) -> Result<()> {
397    let host = crate::fetch::arch_info().0;
398    let canon = canonical_arch(pkg_arch).ok_or_else(|| {
399        anyhow!(
400            "unsupported package architecture {pkg_arch:?} for {}",
401            pkg.display()
402        )
403    })?;
404    if canon != host {
405        bail!(
406            "package {} targets {canon} (declared {pkg_arch:?}), but this host is {host}",
407            pkg.display()
408        );
409    }
410    Ok(())
411}
412
413// ---------------------------------------------------------------------------
414// Package-kind dispatch
415// ---------------------------------------------------------------------------
416
417enum PackageKind {
418    Rpm,
419    Deb,
420    Pacman,
421}
422
423/// Classify a package by extension (`.pkg.tar.zst` is matched on the
424/// full name — `Path::extension` only sees the final `.zst`), falling
425/// back to the leading magic bytes (rpm lead `ed ab ee db`, ar/deb
426/// `!<arch>\n`, zstd frame `28 b5 2f fd` for a pacman package).
427fn package_kind(path: &Path) -> Result<PackageKind> {
428    if path
429        .file_name()
430        .and_then(|n| n.to_str())
431        .is_some_and(|n| n.ends_with(".pkg.tar.zst"))
432    {
433        return Ok(PackageKind::Pacman);
434    }
435    match path.extension().and_then(|e| e.to_str()) {
436        Some("rpm") => return Ok(PackageKind::Rpm),
437        Some("deb" | "ddeb" | "udeb") => return Ok(PackageKind::Deb),
438        _ => {}
439    }
440    let mut magic = [0u8; 8];
441    let mut f = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
442    let n = f.read(&mut magic)?;
443    let magic = &magic[..n];
444    if magic.starts_with(&[0xed, 0xab, 0xee, 0xdb]) {
445        Ok(PackageKind::Rpm)
446    } else if magic.starts_with(b"!<arch>\n") {
447        Ok(PackageKind::Deb)
448    } else if magic.starts_with(&[0x28, 0xb5, 0x2f, 0xfd]) {
449        Ok(PackageKind::Pacman)
450    } else {
451        bail!("{} is not an rpm, deb, or pacman package", path.display())
452    }
453}
454
455// ---------------------------------------------------------------------------
456// RPM extraction
457// ---------------------------------------------------------------------------
458
459fn extract_rpm(path: &Path, dest: &Path) -> Result<()> {
460    let pkg = rpm::Package::open(path).with_context(|| format!("parse rpm {}", path.display()))?;
461    let compressor = pkg.metadata.get_payload_compressor()?;
462    let reader = rpm_payload_decoder(compressor, &pkg.payload)
463        .with_context(|| format!("open payload of {}", path.display()))?;
464    extract_cpio(reader, dest)
465        .with_context(|| format!("extract cpio payload of {}", path.display()))
466}
467
468/// Wrap the raw (compressed) rpm payload in the matching vendored
469/// decoder. rpm payloads are cpio streams compressed with the codec
470/// named by `RPMTAG_PAYLOADCOMPRESSOR`; Fedora/RHEL kernels use xz,
471/// newer Fedora uses zstd. bzip2 (long obsolete for rpm) is rejected.
472fn rpm_payload_decoder<'a>(
473    compressor: rpm::CompressionType,
474    payload: &'a [u8],
475) -> Result<Box<dyn Read + 'a>> {
476    let cursor = Cursor::new(payload);
477    Ok(match compressor {
478        rpm::CompressionType::None => Box::new(cursor),
479        rpm::CompressionType::Gzip => Box::new(flate2::read::GzDecoder::new(cursor)),
480        rpm::CompressionType::Zstd => Box::new(zstd::stream::read::Decoder::new(cursor)?),
481        rpm::CompressionType::Xz => Box::new(xz2::read::XzDecoder::new(cursor)),
482        other => bail!("unsupported rpm payload compression {other}"),
483    })
484}
485
486/// Extract a newc-format cpio stream (SVR4 ASCII, magic `070701` /
487/// `070702`) with the same path hardening as [`extract_tar`].
488///
489/// The rpm-specific "stripped" variant (`07070X`), which stores file
490/// names in the header rather than the payload, is not produced by the
491/// distro kernel packages ktstr targets and is rejected explicitly.
492fn extract_cpio<R: Read>(mut r: R, dest: &Path) -> Result<()> {
493    loop {
494        let mut hdr = [0u8; 110];
495        r.read_exact(&mut hdr).context("read cpio header")?;
496        match &hdr[0..6] {
497            b"070701" | b"070702" => {}
498            b"07070X" => bail!("rpm 'stripped' cpio payloads are not supported"),
499            magic => bail!("unknown cpio magic {:?}", String::from_utf8_lossy(magic)),
500        }
501        let field = |i: usize| cpio_hex(&hdr[6 + i * 8..6 + i * 8 + 8]);
502        let mode = field(1)?;
503        let filesize = field(6)? as usize;
504        let namesize = field(11)? as usize;
505
506        let mut name = vec![0u8; namesize];
507        r.read_exact(&mut name).context("read cpio name")?;
508        while name.last() == Some(&0) {
509            name.pop();
510        }
511        skip_exact(&mut r, pad4(110 + namesize))?;
512        let name = String::from_utf8(name).context("cpio entry name is not utf-8")?;
513        if name == "TRAILER!!!" {
514            break;
515        }
516
517        let rel = sanitize_relative(Path::new(&name))?;
518        write_cpio_entry(&mut r, dest, rel.as_deref(), mode, filesize)?;
519        skip_exact(&mut r, pad4(filesize))?;
520    }
521    Ok(())
522}
523
524/// Materialize one cpio entry, consuming exactly `filesize` payload
525/// bytes regardless of whether the entry is kept (so the stream stays
526/// aligned for the next header).
527fn write_cpio_entry<R: Read>(
528    r: &mut R,
529    dest: &Path,
530    rel: Option<&Path>,
531    mode: u32,
532    filesize: usize,
533) -> Result<()> {
534    const S_IFMT: u32 = 0o170000;
535    match (mode & S_IFMT, rel) {
536        (0o040000, Some(rel)) => {
537            fs::create_dir_all(dest.join(rel))?;
538        }
539        (0o100000, Some(rel)) => {
540            let out = dest.join(rel);
541            if let Some(parent) = out.parent() {
542                fs::create_dir_all(parent)?;
543            }
544            let mut f =
545                fs::File::create(&out).with_context(|| format!("create {}", out.display()))?;
546            let copied = io::copy(&mut r.by_ref().take(filesize as u64), &mut f)?;
547            if copied != filesize as u64 {
548                bail!(
549                    "truncated cpio entry {} (wanted {filesize} bytes, got {copied})",
550                    out.display()
551                );
552            }
553            let _ = f.set_permissions(fs::Permissions::from_mode(mode & 0o7777));
554            return Ok(());
555        }
556        (0o120000, rel) => {
557            let mut target = vec![0u8; filesize];
558            r.read_exact(&mut target)?;
559            if let (Some(rel), Ok(target)) = (rel, std::str::from_utf8(&target)) {
560                create_symlink_safe(dest, rel, Path::new(target))?;
561            }
562            return Ok(());
563        }
564        _ => {}
565    }
566    // Dropped or unhandled entry: drain its data so the stream stays aligned.
567    skip_exact(r, filesize)
568}
569
570/// Parse an 8-char ASCII hex cpio header field.
571fn cpio_hex(bytes: &[u8]) -> Result<u32> {
572    let s = std::str::from_utf8(bytes).map_err(|_| anyhow!("non-ascii cpio header field"))?;
573    u32::from_str_radix(s.trim(), 16).map_err(|_| anyhow!("malformed cpio header field {s:?}"))
574}
575
576/// newc pads each of (header+name) and (data) to a 4-byte boundary.
577fn pad4(len: usize) -> usize {
578    (4 - (len % 4)) % 4
579}
580
581/// Read and discard exactly `n` bytes, erroring on a short stream.
582fn skip_exact<R: Read>(r: &mut R, n: usize) -> Result<()> {
583    let copied = io::copy(&mut r.by_ref().take(n as u64), &mut io::sink())?;
584    if copied != n as u64 {
585        bail!("truncated archive stream (wanted {n} bytes, got {copied})");
586    }
587    Ok(())
588}
589
590// ---------------------------------------------------------------------------
591// DEB extraction
592// ---------------------------------------------------------------------------
593
594fn extract_deb(path: &Path, dest: &Path) -> Result<()> {
595    let (name, data) = find_ar_member(path, |n| n.starts_with("data.tar"))?
596        .ok_or_else(|| anyhow!("{} has no data.tar member", path.display()))?;
597    extract_data_tar(&name, data, dest)
598        .with_context(|| format!("extract {name} from {}", path.display()))
599}
600
601/// Stream a `data.tar.{xz,zst,gz}` (or plain `data.tar`) member through
602/// the matching vendored decoder into the hardened tar extractor.
603fn extract_data_tar(name: &str, data: Vec<u8>, dest: &Path) -> Result<()> {
604    match compression_ext(name) {
605        "xz" => extract_tar(xz2::read::XzDecoder::new(Cursor::new(data)), dest),
606        "gz" => extract_tar(flate2::read::GzDecoder::new(Cursor::new(data)), dest),
607        "zst" | "zstd" => extract_tar(zstd::stream::read::Decoder::new(Cursor::new(data))?, dest),
608        "tar" => extract_tar(Cursor::new(data), dest),
609        other => bail!("unsupported data.tar compression {other:?} ({name})"),
610    }
611}
612
613/// Hardened tar extraction: absolute anchors are stripped, `..` is a
614/// hard error, and escaping symlinks are skipped.
615pub(crate) fn extract_tar<R: Read>(reader: R, dest: &Path) -> Result<()> {
616    extract_tar_matching(reader, dest, |_| true)
617}
618
619/// Hardened selective tar extraction using the same path and symlink
620/// checks as [`extract_tar`]. `include` receives the sanitized relative
621/// path, so callers can extract a small source subset from a large
622/// archive without duplicating archive-hardening logic.
623pub(crate) fn extract_tar_matching<R: Read, F: FnMut(&Path) -> bool>(
624    reader: R,
625    dest: &Path,
626    mut include: F,
627) -> Result<()> {
628    let mut archive = tar::Archive::new(reader);
629    for entry in archive.entries()? {
630        let mut entry = entry?;
631        let path = entry.path()?.into_owned();
632        let rel = match sanitize_relative(&path)? {
633            Some(rel) => rel,
634            None => continue,
635        };
636        if !include(&rel) {
637            continue;
638        }
639        let out = dest.join(&rel);
640        match entry.header().entry_type() {
641            tar::EntryType::Directory => {
642                fs::create_dir_all(&out)?;
643            }
644            tar::EntryType::Symlink | tar::EntryType::Link => {
645                if let Some(target) = entry.link_name()? {
646                    create_symlink_safe(dest, &rel, &target)?;
647                }
648            }
649            _ => {
650                let mode = entry.header().mode().unwrap_or(0o644);
651                if let Some(parent) = out.parent() {
652                    fs::create_dir_all(parent)?;
653                }
654                let mut f =
655                    fs::File::create(&out).with_context(|| format!("create {}", out.display()))?;
656                io::copy(&mut entry, &mut f)?;
657                let _ = f.set_permissions(fs::Permissions::from_mode(mode & 0o7777));
658            }
659        }
660    }
661    Ok(())
662}
663
664/// The last dotted component of an archive member name
665/// (`data.tar.xz` → `xz`), used to pick a decompressor.
666fn compression_ext(name: &str) -> &str {
667    name.rsplit('.').next().unwrap_or("")
668}
669
670// ---------------------------------------------------------------------------
671// `ar` container (deb) reader
672// ---------------------------------------------------------------------------
673
674/// Return the bytes of the first `ar` member whose name satisfies
675/// `want`. The deb `ar` format is a fixed 8-byte global header
676/// (`!<arch>\n`) followed by 60-byte member headers; member data is
677/// padded to an even boundary.
678fn find_ar_member<F: FnMut(&str) -> bool>(
679    path: &Path,
680    mut want: F,
681) -> Result<Option<(String, Vec<u8>)>> {
682    let mut f =
683        BufReader::new(fs::File::open(path).with_context(|| format!("open {}", path.display()))?);
684    let mut global = [0u8; 8];
685    f.read_exact(&mut global)?;
686    if &global != b"!<arch>\n" {
687        bail!("{} is not an ar archive", path.display());
688    }
689    loop {
690        let mut hdr = [0u8; 60];
691        match f.read_exact(&mut hdr) {
692            Ok(()) => {}
693            Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => break,
694            Err(e) => return Err(e.into()),
695        }
696        if &hdr[58..60] != b"`\n" {
697            bail!("{}: malformed ar member header", path.display());
698        }
699        let name = std::str::from_utf8(&hdr[0..16])
700            .map_err(|_| anyhow!("{}: non-utf8 ar member name", path.display()))?
701            .trim_end()
702            .trim_end_matches('/')
703            .to_string();
704        let size: u64 = std::str::from_utf8(&hdr[48..58])
705            .ok()
706            .and_then(|s| s.trim().parse().ok())
707            .ok_or_else(|| anyhow!("{}: malformed ar member size", path.display()))?;
708        if want(&name) {
709            let mut buf = vec![0u8; size as usize];
710            f.read_exact(&mut buf)?;
711            return Ok(Some((name, buf)));
712        }
713        let pad = size % 2;
714        io::copy(&mut (&mut f).take(size + pad), &mut io::sink())?;
715    }
716    Ok(None)
717}
718
719/// Parse the deb architecture from the `control.tar.*` member's
720/// `control` file, falling back to the `_<arch>.deb` filename token.
721fn deb_arch(path: &Path) -> Result<String> {
722    if let Some((name, data)) = find_ar_member(path, |n| n.starts_with("control.tar"))?
723        && let Some(arch) = control_arch(&name, data)
724    {
725        return Ok(arch);
726    }
727    filename_arch(path)
728}
729
730fn control_arch(name: &str, data: Vec<u8>) -> Option<String> {
731    let control = read_tar_entry(name, data, "control")?;
732    let text = String::from_utf8(control).ok()?;
733    for line in text.lines() {
734        if let Some(v) = line.strip_prefix("Architecture:") {
735            return Some(v.trim().to_string());
736        }
737    }
738    None
739}
740
741/// Read one named file (matched by basename) out of a possibly
742/// compressed tar member into memory.
743fn read_tar_entry(member_name: &str, data: Vec<u8>, basename: &str) -> Option<Vec<u8>> {
744    let reader: Box<dyn Read> = match compression_ext(member_name) {
745        "xz" => Box::new(xz2::read::XzDecoder::new(Cursor::new(data))),
746        "gz" => Box::new(flate2::read::GzDecoder::new(Cursor::new(data))),
747        "zst" | "zstd" => Box::new(zstd::stream::read::Decoder::new(Cursor::new(data)).ok()?),
748        _ => Box::new(Cursor::new(data)),
749    };
750    let mut archive = tar::Archive::new(reader);
751    for entry in archive.entries().ok()? {
752        let mut entry = entry.ok()?;
753        let path = entry.path().ok()?.into_owned();
754        if path.file_name().and_then(|n| n.to_str()) == Some(basename) {
755            let mut buf = Vec::new();
756            entry.read_to_end(&mut buf).ok()?;
757            return Some(buf);
758        }
759    }
760    None
761}
762
763// ---------------------------------------------------------------------------
764// Pacman (.pkg.tar.zst) extraction
765// ---------------------------------------------------------------------------
766
767/// A pacman package is one zstd-compressed tarball; stream it through
768/// the vendored decoder into the hardened tar extractor. The
769/// `.PKGINFO`/`.MTREE`/`.BUILDINFO` metadata members land as dot-files
770/// in the destination root, where no artifact lookup ever visits them.
771fn extract_pacman(path: &Path, dest: &Path) -> Result<()> {
772    let f = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
773    let reader = zstd::stream::read::Decoder::new(BufReader::new(f))
774        .with_context(|| format!("init zstd decoder for {}", path.display()))?;
775    extract_tar(reader, dest).with_context(|| format!("extract pacman {}", path.display()))
776}
777
778/// Parse the pacman package architecture from the `.PKGINFO` member's
779/// `arch = <arch>` line.
780fn pacman_arch(path: &Path) -> Result<String> {
781    let f = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
782    let reader = zstd::stream::read::Decoder::new(BufReader::new(f))
783        .with_context(|| format!("init zstd decoder for {}", path.display()))?;
784    let mut archive = tar::Archive::new(reader);
785    for entry in archive.entries()? {
786        let mut entry = entry?;
787        if entry.path()?.as_os_str() != ".PKGINFO" {
788            continue;
789        }
790        let mut text = String::new();
791        entry.read_to_string(&mut text)?;
792        for line in text.lines() {
793            if let Some(v) = line.strip_prefix("arch") {
794                let v = v.trim_start();
795                if let Some(v) = v.strip_prefix('=') {
796                    return Ok(v.trim().to_string());
797                }
798            }
799        }
800        bail!("{}: .PKGINFO has no `arch =` field", path.display());
801    }
802    bail!("{}: no .PKGINFO member found", path.display())
803}
804
805fn filename_arch(path: &Path) -> Result<String> {
806    path.file_stem()
807        .and_then(|s| s.to_str())
808        .and_then(|stem| stem.rsplit('_').next())
809        .map(|s| s.to_string())
810        .ok_or_else(|| anyhow!("cannot infer architecture from filename {}", path.display()))
811}
812
813// ---------------------------------------------------------------------------
814// Path hardening
815// ---------------------------------------------------------------------------
816
817/// Reduce an archive entry path to a safe, destination-relative path.
818///
819/// Absolute anchors and `.` components are dropped; a `..` component is
820/// a hard error (traversal attempt). Returns `Ok(None)` for a path that
821/// reduces to nothing (e.g. `.` / `/`).
822fn sanitize_relative(entry: &Path) -> Result<Option<PathBuf>> {
823    let mut out = PathBuf::new();
824    for comp in entry.components() {
825        match comp {
826            Component::Normal(c) => out.push(c),
827            Component::CurDir | Component::RootDir | Component::Prefix(_) => {}
828            Component::ParentDir => {
829                bail!(
830                    "archive entry escapes destination via `..`: {}",
831                    entry.display()
832                )
833            }
834        }
835    }
836    Ok((!out.as_os_str().is_empty()).then_some(out))
837}
838
839/// Create `dest/link_rel` -> `target`, but only when the link target
840/// resolves to a path inside `dest`. Escaping targets (absolute, or
841/// `..` climbing above the root) are silently skipped — they are never
842/// the `.ko`/image/config artifacts ktstr consumes, and honoring them
843/// would let a package plant a link outside the tree.
844fn create_symlink_safe(dest: &Path, link_rel: &Path, target: &Path) -> Result<()> {
845    let link_dir = link_rel.parent().unwrap_or_else(|| Path::new(""));
846    if resolve_within_root(link_dir, target).is_none() {
847        tracing::debug!(
848            link = %link_rel.display(),
849            target = %target.display(),
850            "skipping symlink whose target escapes the extraction root"
851        );
852        return Ok(());
853    }
854    let link_path = dest.join(link_rel);
855    if let Some(parent) = link_path.parent() {
856        fs::create_dir_all(parent)?;
857    }
858    let _ = fs::remove_file(&link_path);
859    std::os::unix::fs::symlink(target, &link_path)
860        .with_context(|| format!("symlink {} -> {}", link_path.display(), target.display()))?;
861    Ok(())
862}
863
864/// Lexically resolve `target` relative to `base` (both destination-
865/// relative) and return the normalized result, or `None` if it is
866/// absolute or climbs above the root.
867fn resolve_within_root(base: &Path, target: &Path) -> Option<PathBuf> {
868    let mut stack: Vec<OsString> = base
869        .components()
870        .filter_map(|c| match c {
871            Component::Normal(s) => Some(s.to_os_string()),
872            _ => None,
873        })
874        .collect();
875    for comp in target.components() {
876        match comp {
877            Component::Normal(s) => stack.push(s.to_os_string()),
878            Component::CurDir => {}
879            Component::ParentDir => {
880                stack.pop()?;
881            }
882            Component::RootDir | Component::Prefix(_) => return None,
883        }
884    }
885    Some(stack.iter().collect())
886}
887
888// ---------------------------------------------------------------------------
889// Tree discovery
890// ---------------------------------------------------------------------------
891
892/// Derive the kernel release from the extracted tree, erroring if the
893/// packages disagree.
894fn discover_release(dest: &Path) -> Result<String> {
895    let mut releases = BTreeSet::new();
896    collect_subdir_names(&dest.join("lib/modules"), &mut releases);
897    collect_subdir_names(&dest.join("usr/lib/debug/lib/modules"), &mut releases);
898    collect_suffixed(
899        &dest.join("boot"),
900        &["vmlinuz-", "config-", "System.map-"],
901        &mut releases,
902    );
903    collect_suffixed(
904        &dest.join("usr/lib/debug/boot"),
905        &["vmlinux-"],
906        &mut releases,
907    );
908
909    match releases.len() {
910        0 => bail!(
911            "could not determine kernel release: no lib/modules/<rel> or boot/*-<rel> \
912             entries under {}",
913            dest.display()
914        ),
915        1 => Ok(releases.into_iter().next().unwrap()),
916        _ => bail!("packages disagree on kernel release: {releases:?}"),
917    }
918}
919
920fn collect_subdir_names(dir: &Path, out: &mut BTreeSet<String>) {
921    let Ok(rd) = fs::read_dir(dir) else { return };
922    for entry in rd.flatten() {
923        if entry.file_type().map(|t| t.is_dir()).unwrap_or(false)
924            && let Some(name) = entry.file_name().to_str()
925        {
926            out.insert(name.to_string());
927        }
928    }
929}
930
931fn collect_suffixed(dir: &Path, prefixes: &[&str], out: &mut BTreeSet<String>) {
932    let Ok(rd) = fs::read_dir(dir) else { return };
933    for entry in rd.flatten() {
934        let name = entry.file_name();
935        let Some(name) = name.to_str() else { continue };
936        for prefix in prefixes {
937            if let Some(rel) = name.strip_prefix(prefix) {
938                out.insert(rel.to_string());
939            }
940        }
941    }
942}
943
944fn find_image(dest: &Path, release: &str) -> Option<PathBuf> {
945    find_first(
946        dest,
947        &[
948            format!("lib/modules/{release}/vmlinuz"),
949            format!("boot/vmlinuz-{release}"),
950        ],
951    )
952}
953
954/// Return the first of `candidates` (relative to `dest`) that exists.
955fn find_first(dest: &Path, candidates: &[String]) -> Option<PathBuf> {
956    candidates.iter().map(|c| dest.join(c)).find(|p| p.exists())
957}
958
959// ---------------------------------------------------------------------------
960// Image normalization
961// ---------------------------------------------------------------------------
962
963/// "HdrS" setup-header magic at offset 0x202 of an x86 bzImage.
964/// Consumed only by the x86_64 `normalize_image` and by the unit tests
965/// (which synthesize host images on every arch), so gate accordingly to
966/// stay dead-code-free in the aarch64 non-test build under `-D warnings`.
967#[cfg(any(target_arch = "x86_64", test))]
968const BZIMAGE_MAGIC_OFFSET: usize = 0x202;
969#[cfg(any(target_arch = "x86_64", test))]
970const BZIMAGE_MAGIC: [u8; 4] = *b"HdrS";
971/// arm64 flat `Image` magic ("ARM\x64") at offset 0x38.
972const ARM64_MAGIC_OFFSET: usize = 0x38;
973const ARM64_MAGIC: [u8; 4] = [b'A', b'R', b'M', 0x64];
974
975/// EFI zboot container header, from linux
976/// `drivers/firmware/efi/libstub/zboot-header.S`: a PE/COFF DOS
977/// signature ("MZ") at 0x00 and a "zimg" marker at 0x04, the compressed
978/// payload's offset and size as u32-LE at 0x08 and 0x0c, and the
979/// NUL-terminated compression-type string ("gzip"/"zstd") at 0x18. The
980/// size field already excludes the trailing uncompressed-length word
981/// (`ZBOOT_SIZE_LEN`), so it delimits exactly the compressed stream.
982const ZBOOT_ZIMG_OFFSET: usize = 0x04;
983const ZBOOT_PAYLOAD_OFFSET_FIELD: usize = 0x08;
984const ZBOOT_PAYLOAD_SIZE_FIELD: usize = 0x0c;
985const ZBOOT_COMP_TYPE_OFFSET: usize = 0x18;
986
987fn has_magic(bytes: &[u8], offset: usize, magic: &[u8; 4]) -> bool {
988    bytes
989        .get(offset..offset + 4)
990        .is_some_and(|slice| slice == magic)
991}
992
993fn has_gzip_magic(bytes: &[u8]) -> bool {
994    bytes.starts_with(&[0x1f, 0x8b])
995}
996
997fn gunzip(bytes: &[u8]) -> Result<Vec<u8>> {
998    let mut out = Vec::new();
999    flate2::read::GzDecoder::new(bytes)
1000        .read_to_end(&mut out)
1001        .context("gunzip compressed kernel image")?;
1002    Ok(out)
1003}
1004
1005/// Normalize a distro image to a raw bootable image for the host arch.
1006///
1007/// x86_64 distro images (including EFI-signed ones) are already valid
1008/// bzImages and pass through after a magic check. aarch64 images are a
1009/// flat `Image` that may be gzip-wrapped or carried in an EFI zboot
1010/// container (Fedora's aarch64 kernels ship the latter); either wrapper
1011/// is decompressed to a new file beside the tree.
1012#[cfg(target_arch = "x86_64")]
1013fn normalize_image(src: &Path, _dest: &Path, _release: &str) -> Result<PathBuf> {
1014    let prefix = read_prefix(src, BZIMAGE_MAGIC_OFFSET + 4)?;
1015    if !has_magic(&prefix, BZIMAGE_MAGIC_OFFSET, &BZIMAGE_MAGIC) {
1016        bail!(
1017            "{} is not a valid x86_64 bzImage (missing HdrS magic)",
1018            src.display()
1019        );
1020    }
1021    Ok(src.to_path_buf())
1022}
1023
1024#[cfg(target_arch = "aarch64")]
1025fn normalize_image(src: &Path, dest: &Path, release: &str) -> Result<PathBuf> {
1026    let raw = fs::read(src).with_context(|| format!("read image {}", src.display()))?;
1027    // A bare flat Image boots as-is; a gzip- or EFI-zboot-wrapped image
1028    // must be decompressed to a new file beside the tree.
1029    if has_magic(&raw, ARM64_MAGIC_OFFSET, &ARM64_MAGIC) {
1030        return Ok(src.to_path_buf());
1031    }
1032    let image = normalize_arm64_bytes(&raw)?;
1033    let out = dest.join(format!("vmlinuz-{release}.img"));
1034    fs::write(&out, &image).with_context(|| format!("write image {}", out.display()))?;
1035    Ok(out)
1036}
1037
1038/// Decompress (if gzip-wrapped) and verify an aarch64 flat `Image`,
1039/// returning the raw image bytes. Arch-independent so it is unit-
1040/// testable on any host.
1041#[cfg_attr(not(test), allow(dead_code))]
1042fn normalize_arm64_bytes(bytes: &[u8]) -> Result<Vec<u8>> {
1043    let image = if is_zboot(bytes) {
1044        decompress_zboot(bytes)?
1045    } else if has_gzip_magic(bytes) {
1046        gunzip(bytes)?
1047    } else {
1048        bytes.to_vec()
1049    };
1050    if !has_magic(&image, ARM64_MAGIC_OFFSET, &ARM64_MAGIC) {
1051        bail!("decompressed image is not a valid aarch64 Image (missing ARM\\x64 magic)");
1052    }
1053    Ok(image)
1054}
1055
1056/// Detect an EFI zboot container by its PE "MZ" signature and "zimg"
1057/// marker (see [`ZBOOT_ZIMG_OFFSET`] and the constants above it).
1058#[cfg_attr(not(test), allow(dead_code))]
1059fn is_zboot(bytes: &[u8]) -> bool {
1060    bytes.starts_with(b"MZ")
1061        && bytes.get(ZBOOT_ZIMG_OFFSET..ZBOOT_ZIMG_OFFSET + 4) == Some(b"zimg".as_slice())
1062}
1063
1064/// Slice the compressed payload out of an EFI zboot container and
1065/// decompress it per the header's compression-type string. Every offset
1066/// and length taken from the (attacker-controlled) header is
1067/// bounds-checked, so a truncated or malformed container errors rather
1068/// than panics.
1069#[cfg_attr(not(test), allow(dead_code))]
1070fn decompress_zboot(bytes: &[u8]) -> Result<Vec<u8>> {
1071    let read_u32 = |off: usize| -> Result<usize> {
1072        let raw = bytes
1073            .get(off..off + 4)
1074            .ok_or_else(|| anyhow!("EFI zboot header truncated at offset {off:#x}"))?;
1075        Ok(u32::from_le_bytes(raw.try_into().unwrap()) as usize)
1076    };
1077    let payload_offset = read_u32(ZBOOT_PAYLOAD_OFFSET_FIELD)?;
1078    let payload_size = read_u32(ZBOOT_PAYLOAD_SIZE_FIELD)?;
1079    let comp_region = bytes
1080        .get(ZBOOT_COMP_TYPE_OFFSET..)
1081        .ok_or_else(|| anyhow!("EFI zboot header truncated before the compression type"))?;
1082    let comp_len = comp_region
1083        .iter()
1084        .position(|&b| b == 0)
1085        .ok_or_else(|| anyhow!("EFI zboot compression type is not NUL-terminated"))?;
1086    let comp = std::str::from_utf8(&comp_region[..comp_len])
1087        .map_err(|_| anyhow!("EFI zboot compression type is not valid UTF-8"))?;
1088    let end = payload_offset
1089        .checked_add(payload_size)
1090        .ok_or_else(|| anyhow!("EFI zboot payload bounds overflow"))?;
1091    let payload = bytes.get(payload_offset..end).ok_or_else(|| {
1092        anyhow!(
1093            "EFI zboot payload [{payload_offset:#x}..{end:#x}] extends past the {}-byte image",
1094            bytes.len()
1095        )
1096    })?;
1097    decompress_bytes(comp, payload).with_context(|| format!("decompress EFI zboot {comp} payload"))
1098}
1099
1100/// Used only by the x86_64 `normalize_image` (the aarch64 path reads
1101/// the whole image via `fs::read`), so gate it off the aarch64 build.
1102#[cfg(target_arch = "x86_64")]
1103fn read_prefix(path: &Path, len: usize) -> Result<Vec<u8>> {
1104    let mut f = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
1105    let mut buf = vec![0u8; len];
1106    let mut filled = 0;
1107    while filled < len {
1108        let n = f.read(&mut buf[filled..])?;
1109        if n == 0 {
1110            break;
1111        }
1112        filled += n;
1113    }
1114    buf.truncate(filled);
1115    Ok(buf)
1116}
1117
1118// ---------------------------------------------------------------------------
1119// Module dependency closure
1120// ---------------------------------------------------------------------------
1121
1122/// Resolve the transitive `.ko` dependency closure for `wanted`
1123/// modules, in load order (dependencies first).
1124///
1125/// `modules_dir` is the tree root (containing `lib/modules/<release>/`).
1126/// Module names are matched modprobe-style: dashes and underscores are
1127/// interchangeable and any `.ko[.comp]` suffix is ignored. Modules that
1128/// are built into the kernel (listed in `modules.builtin`) are skipped;
1129/// a name found in neither `modules.dep` nor `modules.builtin` is an
1130/// error. Compressed `.ko.{xz,zst,gz}` files are decompressed in place
1131/// and the returned paths point at the raw `.ko` (the guest loads it
1132/// via `finit_module`).
1133pub fn module_closure(
1134    modules_dir: &Path,
1135    kernel_release: &str,
1136    wanted: &[&str],
1137) -> Result<Vec<PathBuf>> {
1138    let base = modules_dir.join(format!("lib/modules/{kernel_release}"));
1139    let dep_text = fs::read_to_string(base.join("modules.dep"))
1140        .with_context(|| format!("read modules.dep for {kernel_release}"))?;
1141
1142    let mut name_to_path: HashMap<String, String> = HashMap::new();
1143    let mut path_deps: HashMap<String, Vec<String>> = HashMap::new();
1144    for line in dep_text.lines() {
1145        let line = line.trim();
1146        if line.is_empty() {
1147            continue;
1148        }
1149        let (key, rest) = line
1150            .split_once(':')
1151            .ok_or_else(|| anyhow!("malformed modules.dep line: {line:?}"))?;
1152        let key = key.trim().to_string();
1153        name_to_path.insert(module_key(&key), key.clone());
1154        path_deps.insert(
1155            key,
1156            rest.split_whitespace().map(|s| s.to_string()).collect(),
1157        );
1158    }
1159
1160    let mut builtin: HashSet<String> = HashSet::new();
1161    if let Ok(text) = fs::read_to_string(base.join("modules.builtin")) {
1162        for line in text.lines() {
1163            let line = line.trim();
1164            if !line.is_empty() {
1165                builtin.insert(module_key(line));
1166            }
1167        }
1168    }
1169
1170    let mut ordered: Vec<String> = Vec::new();
1171    let mut visited: HashSet<String> = HashSet::new();
1172    for name in wanted {
1173        let key = module_key(name);
1174        if builtin.contains(&key) {
1175            continue;
1176        }
1177        let path = name_to_path.get(&key).ok_or_else(|| {
1178            anyhow!(
1179                "module `{name}` not found in modules.dep or modules.builtin for {kernel_release}"
1180            )
1181        })?;
1182        visit_deps(path, &path_deps, &mut visited, &mut ordered);
1183    }
1184
1185    ordered
1186        .into_iter()
1187        .map(|rel| decompress_module(&base.join(&rel)))
1188        .collect()
1189}
1190
1191/// Post-order DFS over the dependency graph so a module's dependencies
1192/// precede it and each module appears once.
1193fn visit_deps(
1194    path: &str,
1195    deps: &HashMap<String, Vec<String>>,
1196    visited: &mut HashSet<String>,
1197    ordered: &mut Vec<String>,
1198) {
1199    if !visited.insert(path.to_string()) {
1200        return;
1201    }
1202    if let Some(children) = deps.get(path) {
1203        for dep in children {
1204            visit_deps(dep, deps, visited, ordered);
1205        }
1206    }
1207    ordered.push(path.to_string());
1208}
1209
1210/// modprobe-style module key: basename with any `.ko[.comp]` suffix
1211/// stripped and dashes folded to underscores.
1212fn module_key(path: &str) -> String {
1213    let base = path.rsplit('/').next().unwrap_or(path);
1214    let stem = base
1215        .strip_suffix(".ko.xz")
1216        .or_else(|| base.strip_suffix(".ko.zst"))
1217        .or_else(|| base.strip_suffix(".ko.gz"))
1218        .or_else(|| base.strip_suffix(".ko"))
1219        .unwrap_or(base);
1220    stem.replace('-', "_")
1221}
1222
1223/// Decompress an in-memory buffer with the codec named by `codec`,
1224/// accepting both the file-extension spelling (`gz`/`zst`/`xz`) and the
1225/// zboot `COMP_TYPE` spelling (`gzip`/`zstd`); an unrecognized codec is
1226/// an error naming it. Shares the flate2/zstd/xz2 stack the rest of the
1227/// module already streams `.ko` and archive payloads through.
1228fn decompress_bytes(codec: &str, data: &[u8]) -> Result<Vec<u8>> {
1229    let mut reader: Box<dyn Read> = match codec {
1230        "gz" | "gzip" => Box::new(flate2::read::GzDecoder::new(data)),
1231        "zst" | "zstd" => Box::new(zstd::stream::read::Decoder::new(data)?),
1232        "xz" => Box::new(xz2::read::XzDecoder::new(data)),
1233        other => bail!("unsupported compression {other:?}"),
1234    };
1235    let mut out = Vec::new();
1236    reader
1237        .read_to_end(&mut out)
1238        .with_context(|| format!("decompress {codec} stream"))?;
1239    Ok(out)
1240}
1241
1242/// Decompress a compressed `.ko` in place (writing the raw `.ko`
1243/// beside it) and return the path to the raw module; an already-raw
1244/// `.ko` is returned unchanged.
1245fn decompress_module(path: &Path) -> Result<PathBuf> {
1246    let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("");
1247    let decoder: Option<Box<dyn Read>> = match ext {
1248        "xz" => Some(Box::new(xz2::read::XzDecoder::new(fs::File::open(path)?))),
1249        "zst" => Some(Box::new(zstd::stream::read::Decoder::new(fs::File::open(
1250            path,
1251        )?)?)),
1252        "gz" => Some(Box::new(flate2::read::GzDecoder::new(fs::File::open(
1253            path,
1254        )?))),
1255        _ => None,
1256    };
1257    let Some(mut decoder) = decoder else {
1258        return Ok(path.to_path_buf());
1259    };
1260    let out = path.with_extension("");
1261    let mut buf = Vec::new();
1262    decoder
1263        .read_to_end(&mut buf)
1264        .with_context(|| format!("decompress module {}", path.display()))?;
1265    fs::write(&out, &buf).with_context(|| format!("write {}", out.display()))?;
1266    Ok(out)
1267}
1268
1269#[cfg(test)]
1270#[path = "extract_tests.rs"]
1271mod tests;