Publish LumaOps source

2026-09-03 01:18:36 +02:00
commit 7f1c0e5f71
2363 changed files with 501543 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Security model
+
+LumaOps controls hardware. Treat its web access, persistent configuration, and
+connector credentials as administrator-level assets.
+
+## Safe defaults
+
+- OpenRGB binds only to `127.0.0.1:6742`; Docker never publishes 6742.
+- Authentication is enabled for the default LAN bind and requires a unique
+  administrator token of at least 32 characters.
+- Bridge networking, unprivileged runtime users, and selected device mappings
+  are preferred over host networking or privileged mode.
+- Inventory and discovery do not write to devices.
+- Mock mode cannot start in production.
+- Unknown, blocked, read-only, or identity-mismatched devices reject writes.
+- Mutations are rate-limited, locked per device, time-bounded, and audited.
+
+## OpenRGB SDK boundary
+
+The SDK has no authentication, authorization, or TLS. Anyone who can reach it
+can control attached hardware. Never add a compose `ports` entry for 6742 and
+never bind it to a LAN address. A manually configured remote SDK endpoint is
+accepted only with a persistent warning and is suitable solely for a protected
+LAN or tunnel.
+
+## Application access
+
+Authentication is mandatory for a production process that binds to a non-loopback
+address. Authenticated mode uses an HttpOnly, Secure (when HTTPS), SameSite cookie
+and a separate CSRF token for state-changing requests. The administrator token can
+also be supplied as an API bearer token and must be stored outside source control.
+
+`TRUSTED_PROXIES` is empty by default. Forwarded headers are honored only from
+explicit proxy addresses. Setting `EXTERNAL_ACCESS=true` without authentication
+is a startup error.
+
+TLS terminates at an administrator-managed reverse proxy. LumaOps does not
+provision DNS, certificates, port forwarding, or Nginx Proxy Manager.
+
+## Secrets at rest
+
+Connector secrets are authenticated-encrypted with the persistent LumaOps key.
+Use one of:
+
+1. `LUMAOPS_SECRET_KEY` supplied through a protected container secret; or
+2. `/config/lumaops/secret.key`, generated on first start with restrictive
+   permissions.
+
+Back up the key with appdata and store a second protected offline copy. If it is
+lost, encrypted connector credentials cannot be recovered and must be entered
+again. Database contents, device metadata, scenes, and audit records remain
+usable.
+
+OpenRGB may place Hue or Espurna credentials directly in
+`/config/openrgb/OpenRGB.json`. Protect and back up that directory as sensitive
+data too.
+
+Key rotation creates a database backup, decrypts and reencrypts every connector
+secret inside one transaction, verifies all ciphertext, atomically replaces the
+keyfile, and then removes the old key only when the administrator confirms the
+backup.
+
+## Logging and diagnostics
+
+Structured logging redacts known secret field names, authorization/cookie
+headers, query tokens, encryption keys, and connector credentials. Do not enable
+raw HTTP or SDK packet logging in production. Request, connector, device, and
+command identifiers are logged instead.
+
+The diagnostic bundle uses an allowlist. It includes versions, health,
+redacted schema-level configuration, device metadata, device-node visibility,
+and recent normalized errors. It excludes environment dumps, database files,
+cookies, access tokens, secret ciphertext, raw OpenRGB settings, serial numbers
+unless explicitly selected, and arbitrary log tails.
+
+## Hardware risk controls
+
+- Validate controller identity immediately before writes.
+- Clamp neither invalid input nor unknown enum values silently; reject them.
+- Respect advertised mode and zone capabilities.
+- Limit realtime updates and stop effects when the backend connection ends.
+- Use a static low-brightness colour for first physical validation.
+- Do not unload host drivers, change ACPI policy, flash firmware, or probe SMBus
+  addresses destructively.
+- Treat user plugins as trusted native code with the same privileges as OpenRGB.
+
+The temporary privileged compose profile exists only to diagnose permissions.
+After identifying the required `/dev/bus/usb`, hidraw, I2C, or serial nodes,
+return to explicit mappings and remove privileged access.
+
+## Vulnerability reporting and updates
+
+Never publish live deployment values, environment files or diagnostic exports.
+Review OpenRGB upstream changes, Python/npm lockfiles, and base-image security updates
+regularly. Build an updated image from source, run the complete test/smoke suite,
+back up appdata, and then replace the running container. Never update OpenRGB in
+place inside a running container.