Security and Secure Deployment

DearScenario Player is a local-network playback node. HTTP, OSC, and Remote Debug are plaintext control protocols for trusted show-control deployments; they are not internet-facing management APIs.

Network and source policy

network.listen_address controls where HTTP, OSC/UDP, and Maintenance Remote Debug accept connections. The default 0.0.0.0 listens on all IPv4 interfaces. An explicit address is respected and is never replaced by an automatically chosen network interface. If it becomes unavailable, the bind fails and the operator must correct the configuration or restart the process.

network.advertise_address is display-only. auto selects a current local address for the QR code; an explicit value is useful on multi-NIC systems. It never grants access and never changes the listener.

The optional network.controller_ip_whitelist is an exact source-IP allowlist:

• empty means no additional player-level source restriction;
• non-empty means HTTP, OSC, Maintenance, and Remote Debug must come from a listed IP;
• loopback remains available for local diagnostics when the corresponding service is running.

There is no physical-NIC trust model, private-subnet inference, or automatic subnet gate. Routing, VLANs, VPNs, and host firewalls decide which clients can reach the listener; the optional list adds a simple application-level restriction.

Maintenance mode is selected at process start (--maintenance / -m). It is not created by a browser request, Cookie, PIN, takeover flow, or runtime privilege escalation.

Browser boundaries

The embedded Web Console is served by the player. Cross-origin browser write requests are rejected, and Remote Debug validates the WebSocket Origin. Native HTTP/OSC clients do not need browser credentials; they still need network access and must satisfy the optional source allowlist.

Health, capabilities, API descriptions, and static assets are not authorization endpoints. Reachability of those resources does not grant command execution.

Resource limits

HTTP request bodies, worker backlogs, command queues, and Remote Debug output are bounded. Overload is rejected where a response protocol exists; OSC keeps its best-effort datagram behavior.

Recommended deployment

{
  "network": {
    "listen_address": "0.0.0.0",
    "advertise_address": "auto",
    "controller_ip_whitelist": ["192.168.31.10"]
  }
}

Keep the player, controller, and maintenance workstation on a dedicated control VLAN or isolated switch. If cross-site maintenance is required, use a VPN, SSH tunnel, or a project security gateway with its own authentication and ACLs. Never publish the player's HTTP, OSC, or Remote Debug ports through public port forwarding. A public explicit listen address is allowed but should produce a warning; DearScenario Player does not pretend that it supplies internet-grade protection.

Go-live checklist

• The intended Normal or Maintenance process entry is running.
• listen_address matches the intended bind scope and advertise_address is correct for the QR code.
• If used, every whitelist entry is the controller's exact source IP.
• Remote Debug is unavailable in Normal mode and enabled only when required.
• VLAN, firewall, VPN, and gateway rules prevent untrusted access.
• A real controller command and a rejected unauthorized/cross-origin request have both been tested.

If exposure is suspected

1. Remove public forwarding and disconnect untrusted networks.
2. Restart through the ordinary Normal entry, or correct the Maintenance launch configuration before reopening the maintenance path.
3. Review firewall, VPN, router, and gateway ACLs; the player cannot recover an original client identity after a gateway rewrites it.
4. Re-run the deployment checklist before reconnecting the control network.

Related documentation

• Control Network
• Configuration Reference
• Health API
• Remote Debug

Previous / Next

• Previous: Health API
• Next: OSC Protocol