gree-controller/docs/SECURITY.md

Security notes

The controller is designed primarily for a trusted LAN. This release adds safe defaults without forcing authentication on existing installations.

Implemented safeguards

• GREE_CONTROLLER_APP_TOKEN= remains supported. Authentication is optional and existing installations are compatible.
• Permissive CORS was removed. The web UI and API are same-origin by default.
• Responses include X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Content-Security-Policy and a restrictive Permissions-Policy; API responses are marked no-store.
• Runtime secrets for Home Assistant, InfluxDB and notifications are stored server-side and never returned to the browser. Empty secret fields keep the previously stored value.
• Slack and Discord notification webhooks require HTTPS and are restricted to the official webhook hosts. Redirect following is disabled for these outbound webhook requests. Pushover uses its fixed official API endpoint.
• API access tokens are stored hashed. Administrator token behavior is unchanged for backwards compatibility.
• History/event API limits and SQLite indexes bound common read paths. History retention/compaction is configurable.

Remaining risks / recommendations

1. With an empty application token, every client that can reach the controller HTTP port can operate the air conditioners and change configuration. Keep port 8787 on a trusted VLAN or put authentication in the reverse proxy.
2. The WebSocket administrator token is still passed in its query string because browser WebSocket APIs cannot set an Authorization header. Avoid logging query strings at the proxy and prefer HTTPS/WSS when a token is enabled.
3. The application does not terminate TLS. Use a reverse proxy or VPN for traffic crossing an untrusted network.
4. Home Assistant allow_invalid_tls should be used only with a known local instance; keep it disabled otherwise.
5. Configuration exports contain device keys and may contain integration secrets. Treat backup files as secrets.
6. There is no per-client API rate limiter. For exposure beyond a trusted LAN, configure rate limiting at the reverse proxy.
7. No CSRF token is used. Same-origin operation, removal of permissive CORS and bearer-token authentication reduce the risk, but an authenticated public deployment should also use proxy-level origin/access controls.

Suggested reverse-proxy hardening

• TLS only; redirect HTTP to HTTPS.
• Do not log URL query strings if administrator authentication is enabled.
• Pass WebSocket upgrades for /ws.
• Add authentication at the proxy when GREE_CONTROLLER_APP_TOKEN is empty and the service is reachable outside the trusted LAN.
• Limit request body sizes and add basic request-rate limiting.