Security model¶
Waylight runs on a home server next to things that matter: the Docker daemon, the WireGuard VPN, the router. The guiding rule is least privilege per component: the application gets read access to exactly what a widget shows, and every capability that could change something lives in a separate, optional, minimal component that you enable on purpose.
This page explains why the optional setups are an extra step and what each component can and cannot do.
The application itself¶
- Network allow-list first. Requests from outside
ALLOWED_CIDRSare refused before anything else runs. Rejected and first-seen addresses are logged so the list can be tuned. Do not forward the port on your router; use a VPN such as WireGuard for remote access. - Sign-in. Passwords are hashed with Argon2id. Sign-ins are limited to five attempts per 15 minutes per address, with a growing lockout after that. Two-factor authentication uses TOTP (RFC 6238) with ten one-time recovery codes; the TOTP secret is encrypted at rest, recovery codes are stored hashed and cannot be reused. Passkeys work as a second factor behind HTTPS.
- Sessions. The session cookie is
HttpOnlyandSameSite=Strict. Every changing request needs a per-session CSRF token and passesSec-Fetch-SiteandOriginchecks. Settings → Account lists all sessions and signs out any of them. - Content. A strict Content Security Policy (
script-src 'self'), Markdown sanitised with DOMPurify, feed links restricted tohttpandhttps. - Secrets. Integration passwords and tokens are encrypted with
AES-256-GCM under
SECRET_KEYand never returned by the API. - Container. Runs as non-root on a read-only root file system without
capabilities and with
no-new-privileges. Docker is only reachable through a read-only socket proxy on an internal network without a published port. - Outside connections. Only to services you configure; the full list is on the outbound requests page.
Trust boundaries¶
flowchart LR
subgraph LAN["Your LAN / VPN (ALLOWED_CIDRS)"]
browser["Browser\n(session cookie, CSRF token)"]
end
subgraph net["Docker network waylight"]
app["waylight\nnon-root, read-only FS,\nno capabilities"]
proxy["docker-socket-proxy\nGET only"]
actions["docker-actions-proxy\n(optional) restart only"]
end
subgraph host["Docker host"]
sock[("/var/run/docker.sock")]
procfs["/proc, /sys, / (read-only)"]
wgdir["./wireguard\n(peer status, no keys)"]
cron["cron: wireguard-export.sh"]
smartdir["./smart\n(smartctl JSON)"]
smartcron["cron: smart-export.sh"]
relay["wol-relay (optional)\nhost network, magic packets only"]
end
internet(("Internet APIs\nyou configured"))
browser -- "HTTP(S) :8090" --> app
app -- "GET /containers" --> proxy --> sock
app -. "POST restart (allow-list)" .-> actions --> sock
app -- "read" --> procfs
app -- "read" --> wgdir
cron -- "wg show dump\n(keys stripped)" --> wgdir
app -- "read" --> smartdir
smartcron -- "smartctl --json -a" --> smartdir
app -. "magic packet" .-> relay -. "broadcast" .-> LAN
app -- "only configured\nintegrations" --> internet
Solid lines are always present, dotted lines only when you enable the optional component.
| Component | Can | Cannot |
|---|---|---|
| Waylight container | Read container list and stats through the read-only proxy, read host metrics from read-only mounts, read the WireGuard peer and S.M.A.R.T. exports, call the integrations you configured | Write to Docker, read files outside its mounts, gain privileges (non-root, no capabilities, no-new-privileges, read-only root FS), be reached from outside ALLOWED_CIDRS |
| docker-socket-proxy | Forward GET requests to the container and image endpoints (plus ping/version); IMAGES=1 lets Waylight read the repo digests and labels of the images of running containers for the update hints |
Write anything (POST: 0) — it cannot pull, delete or build images — read system info, volumes, networks or secrets |
docker-actions-proxy (profile docker-actions) |
Forward POST /containers/<name>/stop\|restart\|kill |
Any read, create, exec, image or volume operation; Waylight itself only calls restart for containers on DOCKER_ACTIONS_CONTAINERS |
| wireguard-export.sh (cron, root) | Run wg show all dump and write peer public keys, endpoints, handshakes and traffic |
Write private or preshared keys — the interface line is dropped and the PSK column blanked |
| smart-export.sh (cron, root) | Run smartctl --scan-open and smartctl --json -a and write one JSON file per disk |
Change disks or read their data — smartctl only reads the health log; the container gets no device access |
wol-relay (profile wol) |
Accept valid magic packets on UDP 9009 and broadcast them into the LAN, rate-limited | Read data, Docker or secrets; forward anything that is not a magic packet; it has no capabilities and a read-only filesystem |
| Stored credentials | Be used by the module they belong to | Be read back through the API or appear in logs: they are encrypted with AES-256-GCM using SECRET_KEY and only returned as "set / not set" |
Integration targets (#191)¶
AdGuard Home / Pi-hole, Nextcloud, the FRITZ!Box, Speedtest Tracker, CalDAV calendars and task lists, Proxmox VE, the WebDAV backup target and the notification channels call an address that only the signed-in owner enters in the settings. These addresses are handled in one place:
- Validation when saving (
kernel.ParseTarget):httporhttpswith a host only; no user name or password in the URL (there are fields for them); no query or fragment (webhooks may carry a token in the query); no path unless the integration needs one (WebDAV folder, CalDAV collection, a Pi-hole or Nextcloud sub path). - Address rule, when saving and again for every connection: loopback and
private ranges stay allowed because home-lab services live there;
link-local addresses (
169.254.0.0/16,fe80::/10, including the cloud metadata service at169.254.169.254), multicast and unspecified addresses are refused. The check runs in the dialer on the resolved address, so a hostname that later resolves elsewhere cannot get around it. - Integration HTTP client (
httpclient.WithIntegrationGuard): no redirects are followed, no proxy is used, a timeout applies and responses are limited to 32 MiB (the WebDAV restore allows a whole backup). - Errors: the browser only sees a generic cause ("not reachable", "did not answer in time", "login rejected", …); the technical detail – host, port, resolver or TLS message – is written to the log only.
- Secrets follow their target: when the address, user name, token ID or certificate fingerprint changes, the stored password or token is not reused – it has to be entered again, so it is never sent to a new server by accident.
http://is accepted for LAN devices without TLS (the FRITZ!Box TR-064 port only speaks http), but the settings show a warning: the password or token then travels unencrypted through your network. Preferhttps://wherever the device supports it, and a pinned certificate fingerprint for self-signed certificates (Proxmox VE).
This narrows what a hijacked owner session could reach through the integrations; it does not change the model that only the owner configures them.
Why each optional setup is an extra step¶
Docker socket proxy¶
Whoever can talk to the Docker socket is root on the host: they can start a
privileged container that mounts /. Mounting the socket into a web
application would turn every bug in that application into a full host
compromise. The proxy reduces the API to the read endpoints the widget needs.
Docker actions¶
Restarting needs POST, which the read-only proxy rightly refuses. Instead
of loosening it, a second proxy allows nothing but stop/restart/kill and
nothing else — not even reads — and Waylight adds its own allow-list of
container names on top. Logs are read through the read-only proxy.
Home Assistant¶
A long-lived access token can do everything its user can, including unlocking
doors. Waylight therefore reads states only and calls exactly one service
per entity type (toggle or press), and only for entities that
SMARTHOME_ACTIONS_ENTITIES lists in the environment. A browser session cannot
widen that list. Entity types without a safe action, such as locks, alarm
panels and covers, are never switched. Use a dedicated Home Assistant user for
the token so it can be revoked on its own.
Proxmox VE¶
The widget only needs to read, so the documented token has the role
PVEAuditor. Proxmox serves a self-signed certificate. Instead of switching
TLS verification off, Waylight pins the certificate's SHA-256 fingerprint
and rejects every other certificate, so a machine in the LAN cannot pose as
the node and catch the token. Start and shutdown need two independent steps:
PROXMOX_ACTIONS_GUESTS in the environment (a browser session cannot change it)
and the VM.PowerMgmt permission for exactly these guests in Proxmox. A hard
stop is never offered, and every action lands in the security event log.
Kiosk displays¶
A kiosk display (#50) is an account of its own role: it reads the tabs it is
given, exactly like a guest, but it has no password and none of the account
self-service (password, two-factor, passkeys, session list). It signs in with
a secret link whose token is stored as a SHA-256 hash and shown to the owner
once. The token sits in the URL fragment (/kiosk#…), so it never reaches the
server log, a proxy log or a referrer; the page posts it to
/api/auth/kiosk/login, which is rate limited like the login and subject to
ALLOWED_CIDRS. A new link, disabling or deleting the display signs the
device out at once. Action buttons of widgets are hidden on displays, and the
server refuses every write anyway.
DNS filter pause¶
Pausing AdGuard Home or Pi-hole switches ad and tracker blocking off for
the whole network, so it is off by default. Only the providers listed in
DNS_PAUSE_PROVIDERS in the environment can be paused, and a browser session
cannot change that list. A pause always has a timer (5, 30 or 60 minutes), and
the DNS filter switches itself back on. Every pause lands in the security
event log, and the setting is refused together with DEMO_MODE=true.
Parcels from e-mails¶
Mail is personal, so the IMAP discovery (#166) is off by default and reads
one folder only. Waylight opens it with EXAMINE and fetches with
BODY.PEEK, so the server itself refuses changes and not even the read flag
moves; a test against a scripted IMAP server fails on any writing command.
Only IMAP over TLS is supported, and the connection goes through the same
address check as the HTTP integrations (no link-local or metadata
addresses). The app password is encrypted with SECRET_KEY, never returned,
and sent again only to the same server and user. Message contents are never
stored, only the extracted tracking number, carrier and label.
WireGuard export¶
wg needs CAP_NET_ADMIN in the network namespace of the VPN, and its
output contains the server's private key. Giving the dashboard either would
put the whole VPN at risk. A tiny script on the host, run by cron, writes only
the public peer status into a directory that is mounted read-only into
Waylight. The script is short enough to read in a minute:
scripts/wireguard-export.sh.
Backup restore¶
Restoring replaces every piece of data, so POST /api/backups/restore is
owner-only (no guests, no API tokens), needs the password and — when enabled —
a fresh 2FA code again (rate-limited and logged like a login), and validates the
file with SQLite's integrity check and the schema version before anything is
replaced. The swap happens on the next start, before the database is opened;
the previous database stays next to it as waylight.db.before-restore.
Off-site copies go to the WebDAV folder you configure; its password is
encrypted with SECRET_KEY. The backups themselves contain your data (secrets
stay encrypted with SECRET_KEY, passwords only as hashes), so use a folder only
you can read.
Prometheus metrics¶
GET /metrics exists only with METRICS_ENABLED=true. It needs a bearer
token of at least 32 characters (compared in constant time) and is limited
by ALLOWED_CIDRS like every other route. It reveals service, container and
disk names, but no credentials and nothing from your data. See
metrics.md.
S.M.A.R.T. export¶
Reading disk health needs raw device access (/dev/sd*, CAP_SYS_RAWIO),
which would let a compromised dashboard read every disk. Instead a host
script run by cron writes the JSON output of smartctl into a directory that
is mounted read-only into Waylight:
scripts/smart-export.sh. The export contains
model and serial numbers and health counters, nothing from the disks' contents.
Wake-on-LAN relay¶
Magic packets are broadcasts, and broadcasts do not leave a Docker bridge network. Putting Waylight itself into the host network would remove the network isolation of the whole application. The relay is the only component in the host network, and it can do exactly one thing: send magic packets — which any device in your LAN can do anyway.
FAQ: alternatives and their trade-offs¶
Can I run Waylight in the host network instead of using the relay?
Yes: set WOL_RELAY= (empty). Waylight then broadcasts itself. The
trade-off: the application can reach every service bound to localhost on
the host and loses the network isolation of its own Docker network.
Can I avoid the extra container for Wake-on-LAN altogether?
Enable directed broadcast forwarding on the host
(net.ipv4.conf.all.bc_forwarding=1 and the same for your LAN interface),
set WOL_RELAY= and WOL_BROADCAST=<lan>.255:9. The trade-off: a host-wide
kernel setting that also affects every other container.
Why not mount the Docker socket read-only (:ro)?
:ro only prevents replacing the socket file; the API behind it is fully
writable. It gives no protection.
Why not give the container CAP_NET_ADMIN for WireGuard?
The capability is not limited to WireGuard: it allows changing routes,
firewall rules and interfaces of that network namespace. The export script
needs no change to the container at all.
Can I expose Waylight to the internet?
It is designed for the LAN or a VPN. If you must, put it behind a reverse
proxy with HTTPS, set COOKIE_SECURE=true, TRUSTED_PROXIES and a strict
ALLOWED_CIDRS, and enable two-factor authentication. Never forward the port
in your router directly. See reverse-proxy.md.
What leaves my network? Only requests to services you configured (weather location, feeds, CalDAV, DHL, …), each listed on the outbound requests page. There is no telemetry; the update check is off by default.
Reporting vulnerabilities¶
See SECURITY.md.