esphome-device-builder

ESPHome Device Builder Dashboard

View on Pypi

View on Github

Activity

Latest release: 1d ago
Total releases: 333
Cadence: ~daily
Last 12 months: 333

Reach

Stars: 109

Details

License: Apache-2.0
First release: May 04, 2026

Releases

Version	Released
`1.14.9` patch	Sep 13, 2026
`1.14.8` patch	Sep 13, 2026
`1.14.8b2` pre	Sep 13, 2026
`1.14.8b1` pre	Sep 13, 2026
`1.14.7` patch	Sep 11, 2026
`1.14.6` patch	Sep 10, 2026
`1.14.5` patch	Sep 08, 2026
`1.14.5b1` pre	Sep 08, 2026
`1.14.4` patch	Sep 06, 2026
`1.14.4b1` pre	Sep 06, 2026
`1.14.3` patch	Sep 06, 2026
`1.14.2` patch	Sep 05, 2026
`1.14.1` patch	Sep 05, 2026
`1.14.0` minor	Sep 03, 2026
`1.13.2b3` pre	Sep 03, 2026
`1.13.2b2` pre	Aug 31, 2026
`1.13.2b1` pre	Aug 28, 2026
`1.13.1` patch	Aug 26, 2026
`1.13.1b1` pre	Aug 26, 2026
`1.13.0` minor	Aug 25, 2026
`1.12.5b2` pre	Aug 24, 2026
`1.12.5b1` pre	Aug 24, 2026
`1.12.4` patch	Aug 22, 2026
`1.12.3` patch	Aug 21, 2026
`1.12.2` patch	Aug 20, 2026
`1.12.2b1` pre	Aug 20, 2026
`1.12.1` patch	Aug 20, 2026
`1.12.1b1` pre	Aug 20, 2026
`1.12.0` minor	Aug 19, 2026
`1.11.5` patch	Aug 19, 2026
`1.11.4` patch	Aug 19, 2026
`1.11.4b1` pre	Aug 19, 2026
`1.11.3` patch	Aug 19, 2026
`1.11.3b1` pre	Aug 19, 2026
`1.11.2` patch	Aug 18, 2026
`1.11.1` patch	Aug 17, 2026
`1.11.0` minor	Aug 15, 2026
`1.10.1b2` pre	Aug 15, 2026
`1.10.1b1` pre	Aug 15, 2026
`1.10.0` minor	Aug 15, 2026
`1.9.7b1` pre	Aug 15, 2026
`1.9.6` patch	Aug 12, 2026
`1.9.6b3` pre	Aug 12, 2026
`1.9.6b2` pre	Aug 12, 2026
`1.9.6b1` pre	Aug 11, 2026
`1.9.5` patch	Aug 10, 2026
`1.9.5b2` pre	Aug 10, 2026
`1.9.5b1` pre	Aug 09, 2026
`1.9.4` patch	Aug 07, 2026
`1.9.4b2` pre	Aug 07, 2026

1–50 of 333

Repository

esphome/device-builder

Forks: 33
Open issues: 0
Language: Python

Dependencies (31)

Depends on

1.14.9

Supply-chain exposure

Known CVEs (2)

CVE-2026-59178 GHSA-rrxg-g2pf-6hh4 Sep 14, 2026

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

9.8 / 10
Critical
Network Low None None Unchanged High High High

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

Affected versions

0.1.0b100.1.0b1000.1.0b1010.1.0b1020.1.0b1030.1.0b1040.1.0b1050.1.0b1060.1.0b1070.1.0b1080.1.0b1090.1.0b11

+ 116 more Show less

0.1.0b1100.1.0b1110.1.0b1120.1.0b1130.1.0b1140.1.0b1150.1.0b1160.1.0b1170.1.0b1180.1.0b1190.1.0b120.1.0b130.1.0b140.1.0b150.1.0b160.1.0b170.1.0b180.1.0b190.1.0b200.1.0b210.1.0b220.1.0b230.1.0b240.1.0b250.1.0b260.1.0b270.1.0b280.1.0b290.1.0b300.1.0b310.1.0b320.1.0b330.1.0b340.1.0b350.1.0b360.1.0b370.1.0b380.1.0b390.1.0b400.1.0b410.1.0b420.1.0b430.1.0b440.1.0b450.1.0b460.1.0b470.1.0b480.1.0b490.1.0b500.1.0b510.1.0b520.1.0b530.1.0b540.1.0b550.1.0b560.1.0b570.1.0b580.1.0b590.1.0b600.1.0b610.1.0b620.1.0b630.1.0b640.1.0b650.1.0b660.1.0b670.1.0b680.1.0b690.1.0b700.1.0b710.1.0b720.1.0b730.1.0b740.1.0b750.1.0b760.1.0b770.1.0b780.1.0b790.1.0b800.1.0b810.1.0b820.1.0b830.1.0b840.1.0b850.1.0b860.1.0b870.1.0b880.1.0b890.1.0b900.1.0b910.1.0b920.1.0b930.1.0b940.1.0b950.1.0b960.1.0b970.1.0b980.1.0b991.0.01.0.11.0.101.0.10b11.0.10b21.0.111.0.11b11.0.2b11.0.2b21.0.2b31.0.2b41.0.31.0.41.0.51.0.61.0.71.0.81.0.9

Fixed in

1.0.12

References

https://github.com/esphome/device-builder/security/advisories/GHSA-rrxg-g2pf-6hh4
https://github.com/esphome/device-builder/pull/1625
https://github.com/esphome/device-builder/commit/9e294f729c3eb7334bb57b9fc49b75b728052f52
https://github.com/esphome/device-builder
https://github.com/esphome/device-builder/releases/tag/1.0.12

Updated Sep 14, 2026 · Source: OSV.dev
CVE-2026-59177 PYSEC-2026-3834 GHSA-vv4j-m4vr-f3g6 Sep 10, 2026

ESPHome Device Builder Dashboard: Unauthenticated dashboard access via the HA add-on ingress site bound to all interfaces

8.8 / 10
High
Adjacent Low None None Unchanged High High High

Summary

On the Home Assistant add-on, the dashboard serves a trusted ingress site that skips authentication because the supervisor authenticates the request upstream. That site was binding 0.0.0.0. The add-on runs in host network mode for mDNS, so binding all interfaces also bound the host's LAN interface, and any device on the local network could reach http://<ha-ip>:<ingress_port>/ and get the full dashboard with no credentials.

Details

The HA add-on ingress site is intentionally unauthenticated: the supervisor's ingress proxy authenticates the browser upstream, and the dashboard's threat model assumes the site is reachable only through the supervisor's docker network. The protection depended on physically binding the site to the supervisor, but the site bound 0.0.0.0 instead. Because the add-on uses host networking, 0.0.0.0 includes the host's LAN address, so the no-auth site was reachable directly from the LAN, bypassing the supervisor and its authentication entirely.

This is an auth bypass on a boundary the dashboard explicitly defends. docs/THREAT_MODEL.md names, under the surface it still defends, "anything that lets external traffic reach the ingress site without going through the supervisor." The bug is exactly that.

The fix, in PR #1565, mirrors what the legacy add-on's nginx did:

Bind the ingress site to loopback plus the supervisor gateway (127.0.0.1 and 172.30.32.1) instead of all interfaces. Loopback serves HA core's host-network ESPHome integration, which connects to 127.0.0.1:<ingress_port> without credentials by design; the gateway serves the supervisor's ingress proxy. The LAN interface is no longer bound; an explicit --ingress-host still overrides the bind.

Add ingress_peer_guard, which returns 403 to any TCP peer other than loopback or the supervisor (172.30.32.2), so another hassio bridge add-on reaching the gateway cannot use the site either. This mirrors the legacy nginx allow 127.0.0.1; allow 172.30.32.2; deny all.

The password-gated public port (6052) is not affected; this only affects the host-network HA add-on's ingress port.

Impact

Any device on the same local network as the Home Assistant host could open the dashboard with no credentials and gain its full authenticated capability. Per docs/THREAT_MODEL.md, that capability is host equivalent: an authenticated caller can run arbitrary Python at compile time via external_components:, run arbitrary shell through the compile and validation subprocesses, and read or write arbitrary files in the config and data directories. So the practical impact is full compromise of the add-on, including the Home Assistant config directory it mounts and the ESPHome devices it manages.

The exposure was present by default on every host-network HA add-on install; no operator misconfiguration was required. The standalone Docker dashboard and the password-gated public port are not affected.

Severity rationale

An unauthenticated network client reaches a dashboard site that performs no authentication of its own, and a client that reaches the dashboard has host equivalent capability. ESPHome's threat model documents that a 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 exposed surface is the Home Assistant host's local network interface rather than the internet, so the attack vector is adjacent, giving a CVSS base score of 8.8.

The rating is anchored at the worst case because the exposure was present by default on every host-network HA add-on install, the dominant deployment, and required nothing of the victim. Any party able to reach the host's local network, including a guest network that is not isolated, an untrusted IoT device, or a compromised local host, obtains full control with a single unauthenticated request.

Operational risk is lower for installations 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, and ESPHome is designed for deployment on trusted networks with the network perimeter as the primary defense. That deployment context reduces real world exposure; it does not change the base severity. The ingress site is intended to require the supervisor's authentication even on the local network, and the fix restores that.

Patches

Fixed in device-builder 1.0.10 (PR #1565). The ingress site is bound to loopback and the supervisor gateway only, and a peer guard rejects any TCP peer other than loopback or the supervisor regardless of --ingress-host. The esphome container delivers the fix by bundling device-builder 1.0.10 or newer.

Workarounds

Upgrade to 1.0.10 or newer (an esphome container bundling device-builder 1.0.10+). Without upgrading, restrict access to the add-on's ingress port at the network layer, for example a host or router firewall rule that allows only the Home Assistant host and the supervisor to reach it, and keep the Home Assistant host on a trusted LAN segment. Accessing the dashboard through Home Assistant's normal ingress URL is unaffected and stays authenticated.

Resources

Fix: esphome/device-builder#1565

Ingress site introduction: esphome/device-builder#25

Originating investigation: esphome/device-builder#1560

ESPHome security best practices: https://esphome.io/guides/security_best_practices/

Affected versions

0.1.0b100.1.0b1000.1.0b1010.1.0b1020.1.0b1030.1.0b1040.1.0b1050.1.0b1060.1.0b1070.1.0b1080.1.0b1090.1.0b11

+ 113 more Show less

0.1.0b1100.1.0b1110.1.0b1120.1.0b1130.1.0b1140.1.0b1150.1.0b1160.1.0b1170.1.0b1180.1.0b1190.1.0b120.1.0b130.1.0b140.1.0b150.1.0b160.1.0b170.1.0b180.1.0b190.1.0b200.1.0b210.1.0b220.1.0b230.1.0b240.1.0b250.1.0b260.1.0b270.1.0b280.1.0b290.1.0b300.1.0b310.1.0b320.1.0b330.1.0b340.1.0b350.1.0b360.1.0b370.1.0b380.1.0b390.1.0b400.1.0b410.1.0b420.1.0b430.1.0b440.1.0b450.1.0b460.1.0b470.1.0b480.1.0b490.1.0b500.1.0b510.1.0b520.1.0b530.1.0b540.1.0b550.1.0b560.1.0b570.1.0b580.1.0b590.1.0b600.1.0b610.1.0b620.1.0b630.1.0b640.1.0b650.1.0b660.1.0b670.1.0b680.1.0b690.1.0b700.1.0b710.1.0b720.1.0b730.1.0b740.1.0b750.1.0b760.1.0b770.1.0b780.1.0b790.1.0b800.1.0b810.1.0b820.1.0b830.1.0b840.1.0b850.1.0b860.1.0b870.1.0b880.1.0b890.1.0b900.1.0b910.1.0b920.1.0b930.1.0b940.1.0b950.1.0b960.1.0b970.1.0b980.1.0b991.0.01.0.11.0.10b11.0.10b21.0.2b11.0.2b21.0.2b31.0.2b41.0.31.0.41.0.51.0.61.0.71.0.81.0.9

Fixed in

1.0.10

References

https://github.com/esphome/device-builder/security/advisories/GHSA-vv4j-m4vr-f3g6
https://github.com/esphome/device-builder/pull/1565
https://github.com/esphome/device-builder/commit/b6387db3f8bf1d3df5771f40e9856b959ae4f6a1
https://github.com/esphome/device-builder
https://pypi.org/project/esphome-device-builder
https://github.com/advisories/GHSA-vv4j-m4vr-f3g6

Updated Sep 10, 2026 · Source: OSV.dev

Insights

Releases per month

last 12 months

Release mix

minor 14
patch 69
pre 249

333 releases

Dependencies over time

per release

Release calendar

2026

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

Less More