Web and API Security

Librux can expose a browser console, REST APIs, and WebSocket endpoints from the host control backend. Treat those endpoints as an operations surface, not as an open development dashboard.

The security model has two gates.

network admission decides where requests may come from
authentication decides who may call the API

Use both when the API binds to anything broader than loopback.

Configuration

Security is one area of the host configuration described in Runtime Configuration. It is configured in runtime/config.yaml.

security:
  enabled: true
  network:
    allow_cidrs:
      - "127.0.0.1/32"
      - "192.168.60.0/24"
    allowed_origins:
      - "http://192.168.60.20:8001"
    trust_forwarded_for: false
  api:
    require_auth: true
    token_env: "LIBRUX_API_TOKEN"
    tokens_file: "/opt/librux/var/lib/security/api_tokens.yaml"
  web:
    login_required: true
    admin_password_env: "LIBRUX_WEB_ADMIN_PASSWORD"
    admin_password_file: "/opt/librux/var/lib/security/admin_password"
    session_timeout_sec: 3600
    session_cookie_name: "librux_session"
  health:
    unauthenticated: true

allow_cidrs should include only the management network and loopback. A browser Origin allowlist is optional, but recommended when a fixed management URL is used.

API Keys

REST and WebSocket APIs accept either header form.

Authorization: Bearer <api-key>

X-Librux-API-Key: <api-key>

Use the Web Console Settings page to create and revoke normal API keys. API keys are displayed once at creation time and are hidden afterwards. If a key is lost or suspected to be exposed, revoke it and create a new one.

API keys are intended for external clients, automation, monitoring, and federation/bootstrap clients. The browser Web Console should not store a long-lived API key. It uses the Web login session described below.

The API key storage file is YAML. The configuration field names use token internally because the stored secret value is an authentication token.

tokens:
  - name: operator-laptop
    role: operator
    token: replace-with-long-random-token
  - name: monitoring
    role: viewer
    token: replace-with-long-random-token

Roles are enforced by protected Host Control routes when security is enabled.

Role	Access
`viewer`	read runtime state, specs, health, and Event streams
`operator`	viewer access plus Control WebSocket and managed package instance lifecycle operations
`admin`	operator access plus configuration writes, package install/removal, security management, and runtime apply/restart

Unknown roles authenticate but do not satisfy protected mutating operations.

The browser console uses session cookies. Configure the admin password through a root-owned file or environment variable. Avoid putting real passwords directly in the main runtime YAML.

Example.

sudo install -d -m 0700 /opt/librux/var/lib/security
printf '%s\n' '<admin-password>' | sudo tee /opt/librux/var/lib/security/admin_password >/dev/null
sudo chmod 0600 /opt/librux/var/lib/security/admin_password

After login, the browser receives an HttpOnly SameSite=Lax session cookie. The frontend uses that cookie for same-origin REST calls and WebSocket handshakes. This is the supported authentication path for the browser Console when security.api.require_auth=true.

Do not disable Web login on a host where the browser Console is expected to operate with API authentication enabled.

security:
  enabled: true
  api:
    require_auth: true
  web:
    login_required: true

The combination api.require_auth=true and web.login_required=false is an external API-client mode. It is useful for headless hosts or custom product UIs where automation sends Authorization: Bearer <api-key> or X-Librux-API-Key, but the bundled browser Console cannot create an authenticated session in that mode.

Use the Web Console Settings page to change the admin password when security.web.admin_password_file points to a managed password file. If the password is supplied by environment variable, the runtime reports it as externally controlled and the Web Console will not rewrite it.

Gate Combinations

The security options are intentionally separated so development, API-only, and browser-console deployments can use different policies.

`security.enabled`	`api.require_auth`	`web.login_required`	Result
`false`	any	any	Security gates are disabled. Use only for local or trusted development.
`true`	`false`	`false`	Network admission applies, but API calls do not require identity.
`true`	`true`	`true`	Recommended browser Console mode. External clients use API keys; browser users log in and receive a session cookie.
`true`	`true`	`false`	External API-client mode. Browser Console login is unavailable, so clients must send an API key header.

security.network.allow_cidrs belongs to the network-admission gate. It decides which source IP/CIDR ranges may reach REST, WebSocket, package frontend, and Web Console routes. security.api.require_auth and security.web.login_required belong to the identity gate.

Federation Security

Web/API security does not encrypt the cross-host federation data plane. It protects browser and Host Control API access only.

Use federation.security when raw TCP federation traffic must be protected from sniffing, peer impersonation, frame tampering, or replay.

federation:
  security:
    mode: "required"             # disabled, optional, required
    key_id: "robot-cell-a"
    key_file: "/opt/librux/var/lib/security/federation.key"

disabled keeps the lowest-overhead plaintext path. required is the recommended appliance/product setting for a trusted closed federation group. optional is useful during migration because it can accept plaintext inbound peers while using secure outbound connections when key material is configured.

When federation security is required, configure federation peers with api_port and keep Host API security enabled. The plaintext TCP federation-status fallback is intentionally skipped in that mode.

The common federation security fields are editable from Web Console Settings and from librux config.

librux config set federation.security.mode required
librux config set federation.security.key_id robot-cell-a
librux config set federation.security.key_env LIBRUX_FEDERATION_KEY
librux config set federation.security.key_file /opt/librux/var/lib/security/federation.key

Inline federation.security.key is accepted for lab smoke tests, but it is not shown in the normal settings form. Prefer key_file or key_env for product deployments.

Public Health Endpoints

/api/v1/health and /api/v1/ready may remain unauthenticated for local service probes when security.health.unauthenticated=true. Network admission still applies. Disable that option if the deployment requires every HTTP endpoint to authenticate.

Binding Policy

For local development, prefer.

control:
  api_host: "127.0.0.1"
security:
  enabled: false

For an appliance or managed robot host, prefer.

control:
  api_host: "0.0.0.0"
security:
  enabled: true

Then restrict security.network.allow_cidrs, configure at least one API key, and configure a web admin password before exposing the UI on the management network.