ESPHome Device Builder: Renamed auth env vars silently disable dashboard authentication on upgrade

Summary

The dashboard reads its authentication credentials from $ESPHOME_USERNAME and $ESPHOME_PASSWORD. Earlier versions, and the legacy esphome dashboard, read the bare $USERNAME and $PASSWORD instead. When the env vars were renamed the bare names were dropped with no fallback, so an operator who had protected their dashboard with USERNAME / PASSWORD (as the older getting started guide documented) loses authentication on upgrade and the dashboard starts open to anyone who can reach its port.

Details

Credentials are resolved in DashboardSettings.parse_args. The fallback originally read os.getenv("USERNAME") and os.getenv("PASSWORD"). The env var rename (#265) replaced those with ESPHOME_USERNAME / ESPHOME_PASSWORD and intentionally removed the bare names, because $USERNAME collides with the OS login user on Linux and Windows and reading it on its own would silently promote the shell user to the dashboard username.

The rename closed that footgun but introduced a backward compatibility break: a deployment that set only the bare names now resolves to no credentials, using_password is false, and the REST auth middleware and the WebSocket login gate are both disabled. The process logs a WITHOUT AUTHENTICATION banner at startup, but a container started detached (docker run -d) never surfaces it, so the exposure is silent in practice.

This reaches users because the dashboard subcommand of the ghcr.io/esphome/esphome container runs this package: the container pins esphome-device-builder and execs it for dashboard, inheriting whatever env the operator passed. The standalone Docker path runs without --ha-addon, so it is the affected path. Home Assistant add on installs are not affected; they pass --ha-addon and authenticate through the supervisor ingress proxy, and do not use these env vars.

The rename was tagged as a breaking change but was not surfaced in the 2026.6.0 changelog, so operators had no signal to migrate before upgrading.

Impact

An unauthenticated client with network access to the dashboard port can manage devices, including editing configurations and flashing firmware. Only deployments that relied on the bare $USERNAME / $PASSWORD env vars for authentication are affected; deployments using --username / --password, the new $ESPHOME_* env vars, or HA add on ingress are not.

Severity rationale

An unauthenticated network client crosses the dashboard's only security boundary, and a client past that boundary has host equivalent capability. ESPHome's threat model documents that an authenticated dashboard caller can run arbitrary code at compile time and read or write files in the config and data directories, so confidentiality, integrity, and availability are all High, with no credentials, no user interaction, and low attack complexity.

The base score is rated for the worst case, an internet reachable dashboard. That worst case is the right anchor here, because this issue only affects operators who had deliberately configured a dashboard password, and setting a password is the control an operator uses precisely when the dashboard is reachable by parties they do not fully trust, including a deployment exposed to the internet or a network segment shared with untrusted devices. For the affected population a trusted network cannot be assumed, so authentication should be restored as urgent.

Operational risk is lower for the subset of affected installations that run on a single trusted home or business network behind a firewall, since reaching the dashboard there requires an attacker who is already inside that network. ESPHome is designed for deployment on trusted networks with the network perimeter as the primary defense, so that deployment context reduces real world exposure; it does not lower the base severity, and operators on shared, guest, or internet reachable networks remain at full risk.

Patches

Fixed in 1.0.12. The bare $USERNAME / $PASSWORD are accepted again as a deprecated fallback so previously protected instances stay protected across the upgrade without operator intervention, with a loud deprecation warning at startup directing operators to rename them to $ESPHOME_USERNAME / $ESPHOME_PASSWORD. The fallback is gated on $PASSWORD being set and is only adopted as a pair, so the OS provided $USERNAME is never read on its own and the original collision footgun stays closed. A lone bare $PASSWORD with no username still fails loud as a credential mismatch rather than starting unauthenticated.

This restores compatibility rather than failing closed on the legacy names, because the priority is that an instance which was protected before the upgrade stays protected without the operator having to act; the deprecation warning plus a future removal handles the migration. Operators should migrate to the $ESPHOME_* names.

The esphome container delivers the fix in the 2026.6.2 release, which bumps its pinned esphome-device-builder version to 1.0.12.

Workarounds

Without upgrading, restore authentication immediately by setting the new env vars to the same values, on any affected version:

ESPHOME_USERNAME=<your-username>
ESPHOME_PASSWORD=<your-password>

Alternatively, do not expose the dashboard port to untrusted networks, and check the startup logs for the WITHOUT AUTHENTICATION banner to confirm whether a given instance is currently open.

References

• Original report against the esphome container: GHSA-446m-c8jp-v37m
• Env var rename that introduced the regression: esphome/device-builder#265
• 2026.6.0 changelog (breaking change was not documented): https://esphome.io/changelog/2026.6.0
• Old setup documentation that used the bare names: https://esphome.io/guides/getting_started_command_line