Description

ESPHome Device Builder Dashboard is a dashboard for the ESPHome home management software. Prior to version 1.0.12, 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. The issue is 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. Without upgrading, restore authentication immediately by setting the new env vars to the same values, on any affected version. 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.

Executive Summary

Technical Details

Mitigations

References

Additional Metadata

{
  "score": "9.8",
  "pubDate": "2026-09-14T19:17:37.617Z",
  "pubdate": "2026-09-14T19:17:37.617Z",
  "executiveSummary": "The ESPHome Device Builder Dashboard suffered an authentication regression prior to version 1.0.12. During a refactoring process where environment variable naming conventions were updated from $USERNAME/$PASSWORD to $ESPHOME_USERNAME/$ESPHOME_PASSWORD, the application failed to implement a backward-compatibility fallback. This resulted in an unintentional security configuration change where existing, password-protected instances became publicly accessible upon upgrading to the new version if the environment variables were not updated simultaneously.\nThis vulnerability effectively bypasses mandatory authentication for the dashboard, allowing unauthorized users to gain full access to the management interface if exposed to a network. The risk is critical for users relying on legacy environment variable configurations, as the application defaults to an open state when it fails to detect the newly named variables. An attacker with network access to the dashboard port can interact with the system without providing credentials. The issue is resolved in version 1.0.12, which restores legacy variable support as a deprecated fallback, ensuring that previously secured instances maintain their authorization requirements post-upgrade.",
  "technicalDetails": "The root cause of this vulnerability lies in a breaking change to the authentication initialization logic within the ESPHome Device Builder Dashboard. In versions prior to 1.0.12, the application transitioned from using generic environment variables ($USERNAME and $PASSWORD) to namespaced variables ($ESPHOME_USERNAME and $ESPHOME_PASSWORD). Due to the absence of a legacy fallback mechanism, the application failed to validate credentials when the new variables were absent, defaulting the dashboard to an unauthenticated, publicly accessible state.\nThe exploitation flow is triggered by the deployment of an affected version in an environment where the operator has configured legacy $USERNAME/$PASSWORD variables. Upon process startup, the dashboard application fails to map these variables to its internal authentication configuration. Because the application logic does not enter a failure-stop state, it initializes the web interface without enforcing authorization headers or session management. Consequently, any HTTP request directed at the service port bypasses all security controls.\nThe impact of this vulnerability is significant, as it grants an unauthenticated remote attacker full control over the ESPHome management interface. This includes the ability to manage device configurations, modify firmware, and potentially influence the underlying host system if the dashboard service is running with elevated privileges. The vulnerability is categorized as an authentication bypass resulting from improper state handling during a configuration migration.\nVersion 1.0.12 remediates this by re-introducing the legacy environment variables as a deprecated fallback. The implementation enforces a strict dependency: the fallback is only utilized if both $PASSWORD and a corresponding username are detected, preventing partial configuration leakage. Furthermore, the updated application issues a loud deprecation warning at startup to prompt operators to migrate to the new naming convention. A lone $PASSWORD variable without a username remains ignored, ensuring that the system does not incorrectly transition to an unauthorized state based on incomplete configuration data. Instances failing to migrate will continue to alert operators until the legacy variables are either explicitly renamed or the service is moved to a secure network segment."
}