fix(updater): pin OS release archives with SHA256

[Eli Bosley (elibosley)]

Summary

Pin the OS release ZIP to the SHA256 stored in its published plugin manifest, and enforce that pin before extraction on older plugin managers too.

Why This Exists

The updater currently compares the ZIP with a separately downloaded MD5 file. Replacing both files defeats that check. The release publisher already fills a sha256 entity, but this template does not declare or use it.

Resolution

Declare the existing sha256 entity, use it in the ZIP's <SHA256> element, and verify it explicitly in the install script before extraction. Remove the redundant MD5 sidecar download and comparison, including the legacy Unraid 5 download path.

Reviewer Considerations

• Unraid 6.9.0 recognizes <SHA256>. The 6.8.3 plugin manager ignores it, so the inline check is necessary for compatibility.
• This changes the OS updater template only. It does not impose a new requirement on other plugins or change the plugin manager.
• The release publisher's existing OsVersionFull::getPluginFile() and OsVersionBase::updateEntityTag() fill the new template without a publisher deployment. Older templates continue to generate with their existing MD5 behavior.
• Publish the template through the normal release process so the hash is populated. An unfilled or malformed hash stops installation.

Behavior Changes

A mismatched archive, absent/malformed digest, or failed SHA256 calculation stops the upgrade before archive extraction. The separate MD5 file is no longer fetched. Existing SHA256 checks of extracted boot files remain.

Implementation Summary

• Wire the archive digest into both the XML download declaration and the inline verification.
• Add focused tests that execute only the integrity gate, never the OS installer.

Verification

• python3 tests/unraidserver-integrity.py: all 8 tests passed with Bash 5.3 and Bash 3.2.
• Confirmed the declaration regression test fails against the base template.
• Docker contract check using the actual current publisher classes with an isolated SQLite row: new and stored templates receive the digest in both the XML and inline script; versioned/channel publication and legacy MD5 templates pass; a missing stored hash is rejected.
• Inspected the 6.8.3 and 6.9.0 plugin-manager implementations for element handling and inline execution.
• git diff --check: passed.

Risk

This changes OS upgrade verification. No complete upgrade or Unraid 5 runtime test was performed. Older systems must provide /usr/bin/sha256sum; if it is unavailable, installation stops. The hash pins the archive to the manifest; authenticity of the manifest remains a separate trust boundary.

Summary by CodeRabbit

• Security

  • Replaced MD5-based plugin archive verification with SHA-256 validation.
  • Installations now stop when the expected hash is missing, malformed, or does not match the downloaded archive.

• Bug Fixes

  • Added integrity checks covering valid, invalid, missing, and altered plugin archives before extraction.

[github-actions]

🔧 PR Test Plugin Available

A test plugin has been generated for this PR that includes the modified files.

Version: 2026.09.05.2123
Build: View Workflow Run

📥 Installation Instructions:

Install via Unraid Web UI:

1. Go to Plugins → Install Plugin
2. Copy and paste this URL:

https://preview.dl.unraid.net/pr-plugins/pr-2743/webgui-pr-2743.plg

3. Click Install

Alternative: Direct Download

• 📦 Download PLG
• 📦 Download TXZ

⚠️ Important Notes:

• Testing only: This plugin is for testing PR changes
• Backup included: Original files are automatically backed up
• Easy removal: Files are restored when plugin is removed
• Conflicts: Remove this plugin before installing production updates
• Post-merge behavior: This preview stays available after merge until preview storage expires or it is manually cleaned up

📝 Modified Files:

Click to expand file list

emhttp/plugins/unRAIDServer/unRAIDServer.plg

🔄 To Remove:

Navigate to Plugins → Installed Plugins and remove webgui-pr-2743, or run:

plugin remove webgui-pr-2743

---

_{🤖 This comment is automatically generated and will be updated with each new push to this PR.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: d3cc2c57-ad3d-41c7-9cb9-1135849074f0

📥 Commits

Reviewing files that changed from the base of the PR and between 10fabce and 8f0b1e1.

📒 Files selected for processing (2)

• emhttp/plugins/unRAIDServer/unRAIDServer.plg
• tests/unraidserver-integrity.py

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

Walkthrough

The plugin replaces MD5 release verification with SHA-256 verification. The install script validates the hash before extraction. New tests cover valid, invalid, missing, and failed hash checks.

Changes

Release archive integrity

Layer / File(s)	Summary
SHA-256 manifest and install gate emhttp/plugins/unRAIDServer/unRAIDServer.plg	The manifest declares sha256. The release archive includes a <SHA256> value. The install script validates the hash format and archive digest before extraction.
Integrity gate validation tests/unraidserver-integrity.py	Tests cover matching archives, modified archives, invalid or missing digests, missing archives, hash-command failures, and verification order.

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

Merge Risk: ⚪ Minimal · up to 8f0b1

Release archives are now pinned and verified with SHA-256 before extraction, replacing the legacy MD5 check. The integrity gate is covered for successful and failing checksum cases, with no current merge-blocking risk identified.

Suggested reviewers: simonfair

Poem

A rabbit checks the archive bright
SHA-256 guards it day and night
Bad hashes stop before unzip
Good hashes let the files hop up
Tests watch each gate with care

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: pinning OS release archives with SHA256 verification.
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.

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/os-release-integrity

---

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.}