Skip to content

[web_server] Document lack of cross-site protections #6946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jesserockz merged 1 commit into from
Jul 9, 2026
+31 −0
Merged

[web_server] Document lack of cross-site protections #6946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions src/content/docs/components/web_server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,30 @@ interface are externally hosted at oi.esphome.io. If you want to use your own se
>
> See [Web Server](/components/ota/web_server/) for more information.

## Security

The web server exposes an HTTP API for viewing and controlling your device's entities. When the
[`web_server` OTA platform](/components/ota/web_server/) is enabled, it can also update firmware.

> [!WARNING]
> The web server has no cross-site protections, by design. It performs no CSRF, `Origin`, or `Referer` checks and uses
> a permissive CORS policy, so it can be called from other origins, including a web page you open while on the same
> network as the device. Its only access controls are the `auth:` option and the network the device is on. Treat it as
> an open control surface unless you enable `auth:`.
Comment thread
jesserockz marked this conversation as resolved.

Recommendations:

- Enable `auth:` if the device is on a network you do not fully trust.
Comment thread
jesserockz marked this conversation as resolved.
- Keep devices on a trusted, segmented network and never expose the web server to the internet. See
[Security Best Practices](/guides/security_best_practices/).
- If web OTA is enabled without `auth:`, anyone who can reach the device, including cross-origin through your browser,
can upload firmware. Protect it with web `auth:`, disable web OTA when it is not needed (`ota: false`), or use
password-protected [native OTA](/components/ota/) instead.

Whether this cross-origin behavior is a bug is answered by the project
[threat model](https://github.com/esphome/esphome/blob/dev/THREAT_MODEL.md): it is intentional and not a defended
boundary.

## Example configurations

Enabling HTTP authentication:
Expand Down
7 changes: 7 additions & 0 deletions src/content/docs/guides/security_best_practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,13 @@ web_server:
- Control switches, buttons, and other entities via the web interface
- Potentially interfere with device operation

> [!NOTE]
> The web server has no cross-site (CSRF) protection by design: it does not check the request `Origin` and uses a
> permissive CORS policy. A web page you visit while on the same network can therefore send commands to the device
> through your browser, even though the page's author is never on your network. Enabling `auth:` and keeping devices on
> a trusted, segmented network are the defenses. This is intentional; see the project
> [threat model](https://github.com/esphome/esphome/blob/dev/THREAT_MODEL.md).
Comment thread
jesserockz marked this conversation as resolved.

### 3. OTA Password Protection

[OTA (Over-The-Air)](/components/ota) updates allow you to update firmware wirelessly. Protect this with a password:
Expand Down