Security Model

API Authentication

The web UI works without any API key — the server trusts same-origin browser requests using the Sec-Fetch-Site header, a Fetch Metadata Request Header that browsers set automatically and JavaScript cannot spoof. Cross-origin requests send cross-site, so CSRF is handled automatically.

External API consumers (scripts, Home Assistant, other *arr apps) authenticate with an X-Api-Key header. The key is generated automatically on first start using Go's crypto/rand — 32 bytes of cryptographically random data, rendered as a 64-character hex string. Find it in Settings → General.

Key behaviour

• Key is generated with crypto/rand.Read — no Math.random, no time seeds.
• Comparison uses crypto/subtle.ConstantTimeCompare to prevent timing attacks regardless of key length or match prefix.
• The GET /health endpoint is intentionally unauthenticated so load balancers and container orchestrators can probe liveness without credentials.
• The API key persists in /config/config.yaml and is stable across restarts.
• The config API returns a masked key (****…); the full key is only available via a separate /api/v1/system/config/apikey endpoint.

WebSocket authentication

WebSocket connections go through the same auth middleware as REST endpoints. Browser connections must include Sec-Fetch-Site: same-origin; external clients must send a valid X-Api-Key header. The auth check runs before the HTTP-to-WebSocket upgrade — unauthenticated connections are rejected at the HTTP level and never reach the WebSocket handler.

Import path validation

Content paths submitted through the import API are validated using pathutil.ValidateContentPath, which rejects path traversal attempts (.. components), symlink escapes, and paths outside allowed directories. This prevents a compromised download client from writing files to arbitrary locations.

Email header injection

SMTP notification fields (recipient, subject) are stripped of \r and \n characters before being set as mail headers. This prevents header injection attacks that could add arbitrary recipients or headers to outgoing email.

The Secret Type

Credentials that Luminarr stores — indexer API keys, download client passwords, notification webhook URLs — are all wrapped in a Secret type that actively prevents accidental exposure. It is not enough to be careful; the type makes leakage structurally impossible in the common cases.

// Every rendering surface redacts the value automatically.
func (s Secret) String()      string        { return "***" }
func (s Secret) MarshalJSON() ([]byte, error) { return json.Marshal("***") }
func (s Secret) LogValue()    slog.Value    { return slog.StringValue("***") }
func (s Secret) GoString()    string        { return "***" }
func (s Secret) MarshalText() ([]byte, error) { return []byte("***"), nil }

// Call .Value() only when you actually need to send the secret.
func (s Secret) Value() string { return s.value }

This means that printing a Secret to a log line, marshalling it to JSON for an API response, or formatting it in a %v or %#v call all produce "***". The only way to retrieve the actual value is an explicit call to .Value(), which is reserved for the moment the credential is sent to the external service it belongs to.

Credentials covered by this type include:

• Indexer API keys (Torznab, Newznab)
• Download client passwords (qBittorrent, Deluge)
• Notification webhook URLs and auth tokens (Discord, email credentials)

SSRF Protection

Server-side request forgery is a meaningful threat when users can configure arbitrary URLs — for indexers, download clients, notification targets, and media servers. Luminarr wraps net.Dialer in a custom safedialer package that intercepts every outbound TCP connection, resolves the hostname, and validates every IP returned by DNS before allowing the connection to proceed.

Two modes are available, applied per connection type based on whether the target is expected to be on your local network.

Security Headers & Limits

Every response from the Luminarr server includes a standard set of security headers. Request bodies are also limited in size to prevent resource exhaustion attacks from malformed or oversized payloads.

The Content Security Policy limits image sources to TMDB's image CDN in addition to same-origin assets. This is intentional — movie posters and backdrops are fetched directly from image.tmdb.org and displayed inline. All other external origins are blocked.

Network Boundaries

Luminarr makes outbound connections only to services you have explicitly configured. The table below documents every connection type, the direction, when it occurs, and which transport mode is used.

Script Sandbox

Luminarr can execute user-provided shell scripts in response to events — post-import processing, custom notifications, library maintenance. Because scripts are a power-user feature, the security model is explicit rather than restrictive: scripts run with full container user permissions by design, but the path to invoking them is hardened against injection.

Path traversal protection

Script names submitted through the API are validated before any filesystem access occurs. Only plain filenames are accepted — no forward slashes, no backslashes, no .. components. The filename is then resolved through three independent checks: filepath.Join, filepath.Clean, and filepath.Rel. All three must confirm the resolved path stays within the configured scripts directory. If any check fails, the request is rejected.

Execution model

• Scripts inherit the environment of the Luminarr process, including any variables set at container start.
• A configurable timeout (default 30 seconds) bounds execution time. After the timeout, a SIGKILL is sent — the script cannot prevent termination.
• Standard output and standard error are captured and returned in the API response for debugging.
• Exit codes are reported; non-zero exits are treated as failures and logged.

What Luminarr Does Not Do

These are not aspirational statements — they are structural properties of the codebase. There is no telemetry library. There is no analytics endpoint. There is no update check URL. The source code is auditable.