feat(zaparoo): select scanout modules by exact kernel identity

[wizzomafizzo]

Select Zaparoo's optional scanout module using the running kernel's GNU build ID as well as its release string. Kernels sharing uname -r no longer automatically accept the same module; missing or mismatched profiles retain fb0.

• Read bounded kernel notes and strict profiles from modules/<release>/<kernel-build-id>/.
• Verify SHA-256 in the asynchronous loader child and load through the same open descriptor; verify the loaded module build ID before granting access, including already-loaded modules.
• Recognize MagiK's Main-window device in the existing mapping conflict check. Preserve Zaparoo's ABI, memory layout, proxy protocol, and ownership lifecycle.

Validation: Main ARM cross-build passed in the development checkout; the identity test cross-compiled with warnings treated as errors on this branch. ARM test execution and physical scanout qualification remain outstanding.

Old flat release-only module installations now fall back to fb0. No module is force-loaded or unloaded, and no pinned/Edge stock build is newly declared qualified. This PR targets integration master, not distribution stable.

Companion PRs: frontend, menu.

Summary by CodeRabbit

• New Features
  • Scanout support now adapts to compatible kernel builds, rather than relying on one fixed release. HDMI and a matching kernel profile are required.
  • Scanout checks now account for mappings of MagiK’s Main window when detecting device conflicts.
• Bug Fixes
  • Devices with missing or mismatched module identity are no longer accepted for scanout. If checks fail, the system falls back to fb0 without unloading or force-loading a module.
  • Unsupported kernel builds and older flat module layouts no longer receive a scanout offer.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: b12177da-d53b-4f66-acfd-5cbc470830c5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 39a834e0-4aa4-49d0-9e4f-46c95011961c

📥 Commits

Reviewing files that changed from the base of the PR and between 7228482 and fb4af89.

📒 Files selected for processing (5)

• support/zaparoo/SCANOUT.md
• support/zaparoo/scanout.cpp
• support/zaparoo/scanout_profile.cpp
• support/zaparoo/scanout_profile.h
• support/zaparoo/tests/scanout_profile_test.cpp

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Scanout eligibility now uses a profile matching the running kernel release and GNU build ID. Module loading verifies the selected module file and checks the loaded module identity. Conflict detection also includes MagiK’s Main-window mapping device.

Changes

Kernel-profiled scanout

Layer / File(s)	Summary
Profile format and selection support/zaparoo/scanout_profile.h, support/zaparoo/scanout_profile.cpp, support/zaparoo/tests/scanout_profile_test.cpp, support/zaparoo/SCANOUT.md	Adds a strict seven-line profile parser, GNU build-ID extraction, and selection by running kernel release and build ID. Tests cover valid and invalid profile and note data. Documentation describes the profile-based eligibility check.
Module verification and scanout gating support/zaparoo/scanout.cpp, support/zaparoo/scanout_profile.cpp, support/zaparoo/SCANOUT.md	Scanout checks loaded-module identity and verifies the selected module file before passing its open descriptor to insmod. Bootstrap availability and ownership checks require a matching profile. Conflict checks include MagiK’s Main-window mapping device.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Main
  participant ProfileSelector
  participant Kernel
  participant ModuleLoader
  participant sha256sum
  participant insmod
  Main->>ProfileSelector: select_profile
  ProfileSelector->>Kernel: Read release and GNU build ID
  ProfileSelector-->>Main: Return matching profile
  Main->>ModuleLoader: Open selected module without following symlinks
  ModuleLoader->>sha256sum: Verify opened file descriptor
  sha256sum-->>ModuleLoader: Return SHA-256 result
  ModuleLoader->>insmod: Load verified file descriptor
  Main->>Kernel: Check loaded module build ID

Loading

Merge Risk: ⚪ Minimal · up to fb4af

No confirmed issue currently blocks merging. ARM execution and physical scanout qualification remain outstanding.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to fb4af

The new checks reduce accidental module mismatches, but loading now depends on installed profiles whose protection and update authority have not been established. No exploitable path is confirmed; the potential consequence warrants a design review because the loader can insert a kernel module.

Retained concerns

• Medium · security · inferred: Installed profile files now determine which kernel builds may reach the module loader. Their hash checks consistency with the adjacent module, not whether an authorized party installed either file. If a less-trusted actor can write that tree and Main can load modules, the new profile path can extend module-loading eligibility beyond the former fixed release. File-write authority and loader privilege are not established, so this is a conditional boundary concern, not a verified attack path.

Security review details

Security Blast Radius

• inferred — The independently relevant exposure is a machine on which Main can insert modules and an actor can influence its selected profile or module files. Kernel-module insertion is the highest-impact sink; neither such actor access nor loader privileges are demonstrated by the available deployment evidence.

Security Findings and Attack Paths

• observed — No verified Security finding is supplied. The candidate concerning descriptor hashing remains deferred: the open uses O_RDONLY without close-on-exec, but availability and location of sha256sum on supported devices are unestablished. Failure to execute it returns verification failure rather than loading the module.

Trust Boundaries and Controls

• observed — The frontend’s request cannot itself select a module or bypass Main’s conflict and identity checks. Descriptor-based verification resists pathname replacement between hashing and insmod, but does not establish who may modify the installation tree or authenticate its profile.

Resilience and Maintainability Implications

• inferred — Fail-closed selection and post-load identity checks protect lease granting during missing-profile and mismatched-module states. A denial while a loader is already in flight need not stop that child, so fallback and cancellation are distinct lifecycle guarantees.

Hardening Proposals

• proposed — Define and verify the authorized writer, update method, and filesystem protections for profiles and modules before treating a profile as permission to load; use an independent trust anchor if lower-trust writers can reach the tree.
• proposed — Confirm the supported device’s sha256sum executable and inherited search path, and specify whether denial of an in-flight request should cancel its loader. These are deployment and lifecycle checks, not established exploits.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 4 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: selecting scanout modules by exact kernel identity. It matches the pull request objectives and changeset.

Full details: Docstring Coverage

Explanation

Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 4 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}