Security
Updates and security for a boneIO ESP controller, and how to report a vulnerability
boneIO ESP controllers run ESPHome. You can use them in two ways, and the choice decides who looks after updates and security:
- factory firmware — you add the controller in Home Assistant and that is all; boneIO delivers the updates;
- adoption in ESPHome Builder — you take over the configuration and compile it yourself; updates and security are then on your side.
Factory firmware
This is the firmware a controller ships with, and the one the installer at boneio.eu/esp flashes.
Updates. In Home Assistant the controller has a Firmware entity. When boneIO releases a new version the entity shows an available update — install it with Update. The controller checks after every start and every 6 hours. Controllers running older firmware, without that entity, get it after flashing once from the installer.
Security.
| Factory firmware | |
|---|---|
Connection to Home Assistant (api) | Encrypted. Home Assistant sets the key, different for every controller, on its first connection and keeps it |
Firmware upload over the network (ota) | No password — anyone on the network can flash their own firmware. ESPHome requires it: it is how you install your own configuration after adoption |
Device web page (web_server) | None. The installer's + web panel option or the Firmware variant list in Home Assistant turns it on — the page on port 80 then has no password and can switch outputs |
| Firmware upload through the browser | None |
Add the controller to Home Assistant as soon as it is on the network: until then the connection is not encrypted, and whoever connects first sets the key. Keep the controller on a trusted network, ideally separate from guest devices.
The key survives reflashing. The controller keeps its key even after firmware is flashed over USB. When you sell the controller, move it to another Home Assistant, or Home Assistant has lost the key (for example a reinstall without a backup), flash firmware from the installer and accept erase device — only that removes the key.
After adoption in ESPHome Builder
Adoption copies the controller's public configuration — without boneIO updates, so the Firmware entity goes away and you install new firmware by compiling the configuration in ESPHome Builder. Do it regularly: that is how you get fixes to ESPHome and to the boneIO packages.
1. Take control with an API key. In the Take control dialog leave
Enable API encryption ticked (ESPHome Builder 2026.10 or newer). If Home
Assistant then asks for the key in the ESPHome integration, copy it from the
api block of the device configuration.
In an older ESPHome Builder add the key yourself (32 bytes in base64, Builder can generate one):
api:
reboot_timeout: 0s
encryption:
key: !secret boneio_api_key2. Close OTA and the device page. The public configuration has a device page with no password. Change these blocks and install again:
ota:
- platform: esphome
encryption:
web_server:
port: 80
local: true
auth:
type: digest
username: admin
password: !secret boneio_web_passwordota.encryption— the controller accepts only firmware encrypted with its API key: nobody else can flash it, and the firmware image (which contains the key) never crosses the network in plain text. Needs ESPHome 2026.9 or newer; on older versions setpassword: !secret boneio_ota_passwordinstead ofencryption:— a password only checks who is uploading. The two cannot be combined.web_server.authprotects the device page. If you do not use the page, remove the wholeweb_serverblock.- A controller adopted earlier may have a
- platform: web_serverline inota— that is firmware upload through the browser. Remove it, or keep it only together withweb_server.auth.
Keep the password in secrets.yaml, different for every controller.
Reporting a vulnerability
Please do not open a public issue. Email security@boneio.eu with SECURITY
in the subject — we acknowledge within 5 working days. You can also report
through CERT Polska. Report problems in ESPHome itself
to the ESPHome project.