Correct the dm-verity and secure-boot claims

[jetm]

Problem

The security pages describe two capabilities the product does not have.

docs-overview/security/filesystem-integrity.md tells customers that every filesystem read is verified against a Merkle hash tree, that the roothash is signed into the boot chain, and that each extension carries its own independent hash tree. features.md adds that a single altered bit is detected in every extension. None of that is implemented: meta-avocado has no veritysetup call, no roothash generation, and no verity device activation in any recipe, class, or script. The only dm-verity artifact is a kernel fragment that sets CONFIG_DM_VERITY=y and then disables CONFIG_PKCS7_MESSAGE_PARSER, so a signed roothash could not be verified even if a hash tree existed.

docs-overview/security/secure-boot.md documents avocado secure-boot enable as its headline example. No such command exists: the string secure-boot appears nowhere in avocado-cli, and avocado --help lists no such subcommand. The same page says avocado provision programs fuses as part of the manufacturing flow; that command is a shortcut to runtime provision, touches no fuses, and no board layer carries fuse-burning tooling either.

Someone building a compliance answer or an RFP response from these pages would be citing controls we do not ship, and someone following the secure-boot page would run a command that does not resolve.

Solution

Describe the properties that exist, and say plainly where the rest stands.

Filesystem integrity today comes from a read-only erofs root that nothing at runtime can rewrite, update payloads checked against signed metadata before they install, and A/B slots that roll back rather than leave a half-written root. That is a weaker guarantee than per-block verification, and it is one we can stand behind. dm-verity stays on the page as a roadmap section naming exactly what changes when it lands, so a reader evaluating the gap can see it rather than finding a feature they had read about silently deleted.

Secure boot is a build-time story rather than a CLI one. The secureboot distro feature is already on by default and generates the per-machine UEFI key chain; whether a bootloader then enforces a signature is per-silicon and configured per board. Enforcement gets a caution naming where it actually stands.

Two claims survive on their merits and are stated more precisely rather than cut. Signing-key management is real: avocado signing-keys registers keys, including ones generated inside a PKCS#11 token so the private half never leaves the device, which is what makes the multi-vendor signing story true. That section keeps its substance and loses only "end-to-end chain of trust", since there is no verified chain for those signatures to hang off yet.

Key changes

• Rewrite filesystem-integrity.md around immutability, signature-verified updates, and A/B rollback, with dm-verity as an explicit roadmap section
• Scope secure-boot.md to what ships: replace the non-existent command with the real build-time path and the signing-key commands, correct the fuse-provisioning section, and add an enforcement-status caution
• Correct the same dm-verity claim in ten further places found by a repo-wide sweep, beyond the two originally identified: features.md, core-concepts.mdx, about.mdx, atomic-update-architecture.md, hardware-backed-encryption.md, production-ready-features.md, and four docs-hardware board pages
• Fix an adjacent factual error in three pages: the root filesystem is erofs, not SquashFS
• Add an irreversibility and byte-order warning to the fuse section, which cost us a board

Reviewer notes

This changes customer-facing security claims and reads as a walk-back, deliberately. The strongest sentence in the diff says boot chain enforcement is not enabled on any target in the current release. That is accurate as of this commit, and it is the kind of claim with sales consequences, so it is worth a second reader rather than a rubber stamp. If you would rather that framing be softer, the secure-boot.md commit is separable from the dm-verity one.

Verified with npm run build (Docusaurus 3.10.1), exit 0, no broken links. Command shapes checked against avocado 1.0.0-rc.1 help output. No runtime or hardware testing applies; this is a docs-only change.

Two things intentionally not in scope. The i.MX 93 field note repeats these claims and is handled in #477, which already owns that file and carries its verification-status caution. And the pages will need a second pass once verity actually ships, to state the delivered per-machine scope rather than reverting to the universal phrasing removed here.

[Copilot]

Pull request overview

This PR corrects customer-facing security documentation that previously claimed shipped dm-verity and secure-boot capabilities that are not implemented, reframing the docs around the integrity and key-management properties that exist today and explicitly scoping dm-verity / enforcement as future work.

Changes:

• Rewrites the Secure Boot and Filesystem Integrity pages to accurately describe today’s guarantees (immutability + signature verification at install/update time) and to clearly call out what is not enforced yet.
• Updates overview/security collateral to remove or qualify dm-verity and “verified chain through extensions” claims, and corrects several root filesystem format references to erofs.
• Adjusts hardware target pages and related overview pages to align their security messaging with the updated scope.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/docs-overview/security/secure-boot.md	Replaces non-existent CLI flow with build-time configuration + key management; adds explicit enforcement-status caution.
src/docs-overview/security/filesystem-integrity.md	Reframes integrity around immutable erofs + signed metadata verification + A/B rollback; keeps dm-verity as explicit roadmap.
src/docs-overview/security/atomic-update-architecture.md	Updates verification step to reflect signed-metadata/hash+length checks instead of dm-verity verification.
src/docs-overview/security/hardware-backed-encryption.md	Removes dm-verity-as-shipped wording; points integrity discussion back to filesystem integrity page.
src/docs-overview/security/production-ready-features.md	Replaces dm-verity mentions with “immutable signature-verified root” framing; updates immutable core description to erofs + install-time verification.
src/docs-overview/features.md	Removes claims that sysext/confext “inherit dm-verity” and that the secure boot chain extends through extensions; clarifies current verification boundaries.
src/docs-overview/core-concepts.mdx	Updates extension description to immutable/signable images rather than dm-verity inheritance.
src/docs-overview/about.mdx	Updates extension bullet to remove dm-verity-signed phrasing (but still contains a rootfs-format inconsistency needing adjustment).
src/docs-hardware/stmicroelectronics/stm32mp257f-dk/index.mdx	Updates board “Production Security” blurb to remove dm-verity claim.
src/docs-hardware/nvidia/jetson-orin-nano-developer-kit/index.mdx	Updates board “Production Security” blurb to remove dm-verity claim.
src/docs-hardware/intel/x86-64-v3/index.mdx	Corrects root filesystem format claim to “immutable read-only erofs”.
src/docs-hardware/intel/x86-64-v2/index.mdx	Corrects root filesystem format claim to “immutable read-only erofs”.

Suppressed comments (1)

src/docs-overview/security/production-ready-features.md:121

• This section still claims each extension is "independently signed" and "independently verified". That contradicts the updated security pages in this PR (and the secure boot page’s note) that per-extension verification before overlay is not enabled yet. Reword to match the shipped behavior (immutable images, optional signing at build time).

The read-only root filesystem prevents runtime modification of system binaries, libraries, and configuration. Even with root access in production mode, the read-only erofs root cannot be written to. Combined with signature verification at install time, this means the system running in the field is the system that was built and signed, short of the storage medium being modified offline.

### Extension isolation

System extensions overlay onto the immutable root but maintain clear boundaries. Each extension is independently signed, independently verified, and independently updatable. A compromised application extension cannot modify the core OS or other extensions — the overlay architecture enforces this structurally, not just by policy.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

src/docs-overview/about.mdx:48

• about.mdx still describes the immutable root filesystem as SquashFS and claims avocado provision handles fuse burning. That contradicts the corrections in this PR (root is erofs; fuse burning is not performed by avocado provision). Please update these bullets to avoid readers carrying forward the same inaccurate claims.

- **Composable extensions** — systemd-sysext and confext. Read-only images, signable at build time. Overlaid at boot. No container runtime.
- **Immutable rootFS** — SquashFS, read-only. A/B boot slots. BTRFS `/var` for extensions and data.
- **Declarative config** — `avocado.yaml` defines target, runtimes, extensions, packages, overlay, SDK tools. One file.
- **Cross-compilation SDK** — Composable. Declare `nativesdk-rust`, `nativesdk-go`, whatever you need. Automatically configured for your target arch.
- **Hardware-in-the-loop** — NFS mount your code onto running hardware. Edit locally, see it on the device. No rebuild cycle.

src/docs-overview/security/production-ready-features.md:77

• This IEC 62443 summary still risks implying that extension signing/verification is a shipped integrity control (“immutable root with signed extensions”). Elsewhere in this PR we clarify that per-extension verification before overlay is not enabled yet. Suggest rephrasing this line to avoid overstating current guarantees.

**How Avocado addresses this:** The layered security architecture — secure boot, an immutable signature-verified root, LUKS encryption, extension isolation — provides the defense-in-depth that IEC 62443 requires. Hardware-backed key storage supports SL-3 deployments. The immutable root with signed extensions provides data integrity at the OS level. Audit logging and boot mode separation support access control and use control requirements. Atomic updates with rollback provide resource availability during maintenance.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

src/docs-overview/security/production-ready-features.md:77

• This still presents "secure boot" as part of the shipped defense-in-depth story for IEC 62443, but the updated Secure Boot page in this PR states boot chain enforcement is not enabled on any target in the current release. Rephrase this line to avoid implying secure boot enforcement is currently providing defense-in-depth.

**How Avocado addresses this:** The layered security architecture — secure boot, an immutable signature-verified root, LUKS encryption, extension isolation — provides the defense-in-depth that IEC 62443 requires. Hardware-backed key storage supports SL-3 deployments. The immutable root with signed extensions provides data integrity at the OS level. Audit logging and boot mode separation support access control and use control requirements. Atomic updates with rollback provide resource availability during maintenance.

src/docs-overview/about.mdx:45

• This page still describes the immutable root filesystem as SquashFS, but the surrounding security docs in this PR update the root filesystem to erofs. This should be made consistent to avoid contradicting the updated security claims.

- **Composable extensions** — systemd-sysext and confext. Read-only images, signable at build time. Overlaid at boot. No container runtime.
- **Immutable rootFS** — SquashFS, read-only. A/B boot slots. BTRFS `/var` for extensions and data.

src/docs-overview/security/secure-boot.md:79

• "un-burned" is a nonstandard spelling here; "unburned" is the usual form.

Treat it as one-way. A fuse cannot be un-burned, a wrong value cannot be corrected, and a board whose key hash is burned incorrectly can no longer establish a root of trust at all. Practice the procedure on a board you are willing to lose before running it on anything else, and check the byte order the vendor's tool expects against the byte order your key hash is printed in, because the two do not always match.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (6)

Previously missed (4) — in code that hasn't changed since the last review.

src/docs-overview/security/production-ready-features.md:77

• This section presents "secure boot" as a currently shipped defense-in-depth layer, but the Secure Boot page now states boot-chain enforcement is not enabled on any target in the current release. Please qualify this sentence so it doesn't contradict the Secure Boot documentation.

**How Avocado addresses this:** The layered security architecture — secure boot, an immutable signature-verified root, LUKS encryption, extension isolation — provides the defense-in-depth that IEC 62443 requires. Hardware-backed key storage supports SL-3 deployments. The immutable root with signed extensions provides data integrity at the OS level. Audit logging and boot mode separation support access control and use control requirements. Atomic updates with rollback provide resource availability during maintenance.

src/docs-hardware/stmicroelectronics/stm32mp257f-dk/index.mdx:81

• This board page still advertises "Secure boot" as a shipped feature, but the updated Secure Boot documentation states boot-chain enforcement is not enabled on any target in the current release. Consider removing the secure-boot claim here or qualifying it to match the enforcement-status note.

Secure boot with TrustZone, an immutable signature-verified root, and LUKS encryption. Industrial-grade security from day one.

src/docs-hardware/nvidia/jetson-orin-nano-developer-kit/index.mdx:86

• This board page still advertises "Secure boot" as a shipped feature, but the updated Secure Boot documentation states boot-chain enforcement is not enabled on any target in the current release. Consider removing the secure-boot claim here or qualifying it to match the enforcement-status note.

Secure boot, an immutable signature-verified root, and LUKS encryption across all architectures. Reproducible images simplify certification.

src/docs-overview/features.md:201

• This section claims a "secure boot chain" and a "verified boot chain" as current properties. That conflicts with the updated Secure Boot page, which now states boot-chain enforcement is not enabled on any target in the current release. Please reword to reflect that enforcement is in development and link readers to the Secure Boot status note.

Security in Avocado OS is not a feature you bolt on later — it's structural. The secure boot chain starts at the hardware root of trust and runs through the bootloader into the kernel. From there, the root filesystem and every extension are immutable images, verified when they are installed.

- [Secure boot](/avocado-os/security/secure-boot) with a verified boot chain from the hardware root of trust through the bootloader and kernel

src/docs-overview/about.mdx:45

• The "Immutable rootFS" bullet still says the root filesystem is SquashFS, but the rest of this PR updates the docs to state the root is erofs. This leaves the About page inconsistent and factually incorrect.

- **Composable extensions** — systemd-sysext and confext. Read-only images, signable at build time. Overlaid at boot. No container runtime.
- **Immutable rootFS** — SquashFS, read-only. A/B boot slots. BTRFS `/var` for extensions and data.

src/docs-overview/security/atomic-update-architecture.md:36

• Update verification is performed using public verification keys/trust anchors on the device; referring to "signing keys provisioned on the device" is misleading (and implies private signing material is present on-device).

2. **Verify** — Cryptographic signatures are validated against the signing keys provisioned on the device, and each image is checked against the hash and length recorded in that signed metadata. A payload that fails either check is not installed, and the active slot is left untouched.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

src/docs-overview/about.mdx:48

• This section still states the immutable root filesystem is SquashFS and that avocado provision handles fuse burning. Elsewhere in this PR (and in secure-boot.md) the root is described as read-only erofs, and fuse programming is explicitly not performed by avocado provision. Keeping these bullets as-is reintroduces the two claims this PR is correcting.

- **Composable extensions** — systemd-sysext and confext. Read-only images, signable at build time. Overlaid at boot. No container runtime.
- **Immutable rootFS** — SquashFS, read-only. A/B boot slots. BTRFS `/var` for extensions and data.
- **Declarative config** — `avocado.yaml` defines target, runtimes, extensions, packages, overlay, SDK tools. One file.
- **Cross-compilation SDK** — Composable. Declare `nativesdk-rust`, `nativesdk-go`, whatever you need. Automatically configured for your target arch.
- **Hardware-in-the-loop** — NFS mount your code onto running hardware. Edit locally, see it on the device. No rebuild cycle.

src/docs-overview/security/production-ready-features.md:121

• The "Extension isolation" paragraph still states extensions are "independently verified". In this PR’s updated security docs, per-extension verification before overlay is explicitly not enabled yet; extensions can be signed, but are not currently verified at boot/overlay time. This sentence should be scoped to what is actually enforced today.

The read-only root filesystem prevents runtime modification of system binaries, libraries, and configuration. Even with root access in production mode, the read-only erofs root cannot be written to. Combined with signature verification at install time, this means the system running in the field is the system that was built and signed, short of the storage medium being modified offline.

### Extension isolation

System extensions overlay onto the immutable root but maintain clear boundaries. Each extension is independently signed, independently verified, and independently updatable. A compromised application extension cannot modify the core OS or other extensions — the overlay architecture enforces this structurally, not just by policy.