LumaOps-Public/docs/SECURITY.md

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.