Security Hardening

Security Hardening

EZ-Kea edits the configuration of a DHCP server. Anyone who can log in can change what addresses your network hands out, where clients point their DNS, and which devices get reserved addresses. Treat access to it the way you'd treat access to the DHCP server itself.

Before exposing it

Set SECRET_KEY

SECRET_KEY="$(python3 -c 'import secrets;print(secrets.token_hex(32))')"

It signs session cookies and CSRF tokens. EZ-Kea refuses to start on a non-loopback bind address while this is still the default dev, and prints a loud warning even on loopback.

Store it in a mode-0600 environment file owned by the service account, not in the systemd unit — unit files are world-readable.

Change the default account immediately

A fresh database seeds admin / changeme. EZ-Kea forces both the username and password to be changed at first login, but the window between first boot and first login is real. Don't start a fresh install on an untrusted network and walk away.

That first account is marked break-glass: it can't be deleted and can't have its admin rights revoked, so you can't lock yourself out of your own install.

Put TLS in front

EZ-Kea serves plain HTTP via waitress. Bind it to loopback and terminate TLS at nginx, Caddy, or equivalent. See Installation.

Access control

There is no read-only role. This is the most important thing to understand about EZ-Kea's permission model:

• Every DHCP configuration route requires only a valid login. Any authenticated user can create and delete subnets, shared networks, reservations, and options, edit HA configuration, and apply or restore configs.
• The is_admin flag gates exactly three areas: user management, licensing, and email settings.

So an account you create for someone to "just look at leases" can also delete every subnet you have. Grant logins accordingly, and prefer a read-only database replica or a screenshot over a guest account.

Two-factor authentication

TOTP is available per-user under Profile, and admins can force enrollment for an account — the next login is redirected through setup before reaching the dashboard. A user's totp_enabled flag stays false until a real code is verified, so a half-finished enrollment can't lock anyone out.

The break-glass account generates one-time recovery codes when it completes enrollment. Store them somewhere that isn't the machine running EZ-Kea.

File permissions

The service account needs write access to your Kea config, the backup directory, and its own data directory — and read access to lease and log files. It does not need write access to anything else under /etc.

Systemd can enforce that:

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/etc/kea /var/lib/ez-kea

The SQLite database holds password hashes, TOTP secrets, and any SMTP credentials you enter. It should be mode 0600 and owned by the service account.

Email settings

SMTP credentials entered under Email Settings are stored in the database in plaintext, so they're readable by anyone who can read the database file or who gains admin access in the UI. Use a dedicated sending account with an app password scoped to that purpose, not a primary mailbox credential.

Reporting issues

See SECURITY.md. Please report privately rather than opening a public issue.