Security model

This page describes the Firmware v3.0.2 security model, not a security certification or a claim of full official-client policy parity.

Administering the ESP32 and authorizing network traffic are separate concerns, and the firmware treats them separately.

Web administration

• Salted PBKDF2-HMAC-SHA256 password verifier and a one-time login challenge; no plaintext password storage for current records.
• Device-wide login budget shared by the Web UI and the remote console.
• Session cookie is HttpOnly and SameSite=Strict; state-changing requests from other origins or cross-site contexts are refused.
• Without a password, requests carrying an untrusted Host are refused to block DNS rebinding.
• Content-Security-Policy, frame and content-type protection headers.

Network authorization

• Tailnet policy is checked on original packets before NAT or 4via6; malformed or revoked policy fails closed.
• A Service Gateway source CIDR filters addresses; it does not prove who the client is. Prefer /32.
• Peers see the ESP32's tailnet identity and apply their own ACLs.
• No claim of full official-client policy parity; see Tailnet authorization.

Updates

GitHub updates are opt-in. Only release assets from the project repository are accepted, over HTTPS with certificate validation, with a SHA-256 digest, board and version checks. The bootloader returns to the previous image if the new one does not confirm a healthy boot.

Known limits

• The local Web UI is HTTP: administer it from a trusted LAN or over the tailnet.
• The portable image does not enable Secure Boot, flash encryption or NVS encryption; physical access can expose stored credentials.
• MQTT, ntfy and SNMP are as trustworthy as their transport and server configuration.

Reporting a vulnerability

Use GitHub's private vulnerability reporting. Please do not open a public issue. Details: SECURITY.md.