VelaOS security architecture

This document describes the security primitives VelaOS inherits from the AlmaLinux 10.1 bootc base + the Linux kernel, and the additional controls the platform layers on top at image build time. It is written for security architects, procurement teams, and compliance officers evaluating VelaOS for fleets of 100 devices or more.

Every claim in this document is verifiable by reading HARDENING.md in the public repo, inspecting the image's kernel cmdline + systemd unit set, and running `cosign verify` against the published release key.

VelaOS endpoints operate in physically exposed environments — retail floors, hospital corridors, shop-floor workstations, substations, branch lobbies. The assumption is that an attacker with local physical access will eventually be possible. The security model is designed to fail closed under that assumption.

We do not rely on physical security. We do not assume the user is trusted. We do not assume the network is trusted.

UEFI firmware + Secure Boot verify the AlmaLinux shim + MOK-enrolled VelaOS key. Shim verifies GRUB 2, GRUB verifies the signed kernel + initramfs, the initramfs verifies the cosign signature on the bootc rootfs image before activating the new A/B slot. If any link in the chain fails verification, the device refuses to activate the deployment and rolls back.

The kernel also enforces module.sig_enforce=1 — unsigned kernel modules cannot load, ever. Combined with fapolicyd's userspace execution trust anchors, there is no path for an attacker with root to run an unsigned binary.

Every update writes to the parallel A/B slot. Greenboot runs 10 required health checks on the new slot's first boot: SELinux enforcing, firewalld active, usbguard active, cosign signature verified, vela-agent healthy with fresh heartbeat, LUKS mounted, /etc/selinux/config persistent-enforcing, kernel lockdown=confidentiality active, plus network-online and kiosk-session-alive. A failed check triggers automatic rollback to the previous slot before any user sees the regression.

Ring rollouts layer on top: canary 5% → pilot 20% → broad 100%, with auto-halt if more than a configurable threshold of pilot devices report failure.

Kernel cmdline: lockdown=confidentiality, init_on_alloc=1, init_on_free=1, slab_nomerge, page_alloc.shuffle=1, vsyscall=none, randomize_kstack_offset=on, mitigations=auto,nosmt, IMA policy=tcb + EVM. Every one of these is a measurable protection enforced by the kernel itself, not by userspace policy.

SELinux ships in enforcing mode with per-domain policy for vela_agent_t, vela_shell_t, vela_kiosk_t, and per-VelaApp domains for Citrix / Horizon / Chrome. fapolicyd denies execution from /tmp, /var/tmp, /dev/shm. usbguard default-blocks USB; allowlists HID, audio, video (webcams), CCID smart-card. Mass-storage is explicitly rejected.

On first boot the agent generates an ed25519 keypair sealed via systemd-creds to TPM PCRs 7+11. The private key never leaves the sealed blob. Device-to-cloud MQTT on port 8883 uses mutual TLS against a per-tenant certificate authority. Every cloud-to-device command is wrapped in a signed envelope (ed25519 v0.2); the agent verifies the signature before acting.

The VelaOS CA is generated per tenant and its root certificate can be downloaded as PEM from the console's Security settings for external validation. Auto-cert-rotation runs hourly in the cloud rotator — any certificate within the tenant's rotation window is automatically re-issued before expiry.

LUKS2 with Argon2id (128 MiB memory, 3 iterations) encrypts the root filesystem. The key is sealed via Clevis to TPM 2.0 with PCR 7 (Secure Boot policy) and PCR 11 (systemd-boot stub measurement). A firmware update or Secure Boot policy change invalidates the unseal until the operator re-enrols — the recovery passphrase held by the tenant admin unlocks the disk in that case.

Recovery passphrases are optionally stored in Supabase Vault encrypted per-tenant when the customer opts in to cloud recovery. Key rotation adds a new LUKS slot and removes the old one; scheduled via policy, tied to device-cert rotation.

firewalld ships with target=DROP on the default zone. No listening ports. No sshd (masked at image build). Remote support goes through the agent's outbound-only WebSocket tunnel to VelaCloud for Live View; no inbound channel exists.

802.1X network profiles support EAP-TLS, EAP-TTLS, PEAP, and EAP-FAST. Per-device certificates for 802.1X are generated by the tenant CA, pushed over the signed-envelope MQTT channel, and installed via systemd-creds — no manual cert handling.

The base image is `quay.io/almalinuxorg/almalinux-bootc:10` pinned by digest in production Containerfiles. Every VelaApp OCI image is cosign-signed; devices verify before `podman run`. Every VelaOS Linux image is cosign-signed; bootc verifies before activate. SBOMs attach as cosign attestations on every image. The `sbom-diff` tooling computes a material diff between any two versions for procurement review.

SOC 2 Type II: observation window opens at Phase 3, report delivered at v3.0.0 GA. HIPAA § 164.312 technical safeguards directly implemented. GDPR: cloud infrastructure is EU-hosted (Frankfurt primary, secondary EU region for backups); no tenant configuration allows data to leave the EU. Full mapping to CIS AlmaLinux 10 L2, DISA STIG RHEL 10, NIST 800-53 moderate, PCI 4.0 in COMPLIANCE_MATRIX.md.

This whitepaper does not describe the internal architecture of the cloud control plane. It does not describe the CI/CD pipeline or the release engineering process in detail. These details are available to enterprise customers under NDA.