98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# 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.
|