mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 22:35:08 +00:00
ChuckandClaude Opus 5.5
e3c85cece6
Optional web login, off by default: a device that sets no password behaves exactly as before. Set under General > Security; then every page and API route needs a session login or an API token (Authorization: Bearer). Loopback, the Wi-Fi setup flow in AP mode, static files, captive-portal probes and a reduced /api/v3/health stay open. Secrets live in the web_auth section of config_secrets.json and no API returns them. scripts/reset_web_password.py turns login off. Stacked on #674. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
# Security Policy
|
|
|
|
## Reporting a vulnerability
|
|
|
|
If you've found a security issue in LEDMatrix, **please don't open a
|
|
public GitHub issue**. Disclose it privately so we can fix it before it's
|
|
exploited.
|
|
|
|
### How to report
|
|
|
|
Use one of these channels, in order of preference:
|
|
|
|
1. **GitHub Security Advisories** (preferred). On the LEDMatrix repo,
|
|
go to **Security → Advisories → Report a vulnerability**. This
|
|
creates a private discussion thread visible only to you and the
|
|
maintainer.
|
|
- Direct link: <https://github.com/ChuckBuilds/LEDMatrix/security/advisories/new>
|
|
2. **Discord DM**. Send a direct message to a moderator on the
|
|
[LEDMatrix Discord](https://discord.gg/RdrC37rEag). Don't post in
|
|
public channels.
|
|
|
|
Please include:
|
|
|
|
- A description of the issue
|
|
- The version / commit hash you're testing against
|
|
- Steps to reproduce, ideally a minimal proof of concept
|
|
- The impact you can demonstrate
|
|
- Any suggested mitigation
|
|
|
|
### What to expect
|
|
|
|
- An acknowledgement within a few days (this is a hobby project, not
|
|
a 24/7 ops team).
|
|
- A discussion of the issue's severity and a plan for the fix.
|
|
- Credit in the release notes when the fix ships, unless you'd
|
|
prefer to remain anonymous.
|
|
- For high-severity issues affecting active deployments, we'll
|
|
coordinate disclosure timing with you.
|
|
|
|
## Scope
|
|
|
|
In scope for this policy:
|
|
|
|
- The LEDMatrix display controller, web interface, and plugin loader
|
|
in this repository
|
|
- The official plugins in
|
|
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
|
- Installation scripts and systemd unit files
|
|
|
|
Out of scope (please report upstream):
|
|
|
|
- Vulnerabilities in `rpi-rgb-led-matrix` itself —
|
|
report to <https://github.com/hzeller/rpi-rgb-led-matrix>
|
|
- Vulnerabilities in Python packages we depend on — report to the
|
|
upstream package maintainer
|
|
- Issues in third-party plugins not in `ledmatrix-plugins` — report
|
|
to that plugin's repository
|
|
|
|
## Known security model
|
|
|
|
LEDMatrix is designed for trusted local networks. Several limitations
|
|
are intentional rather than vulnerabilities:
|
|
|
|
- **Web UI authentication is optional and off by default.** Out of the
|
|
box the web interface assumes the network it's running on is trusted.
|
|
Setting a password under **General > Security** makes every page and
|
|
API route require a login or an API token (`Authorization: Bearer`),
|
|
with wrong passwords rate-limited per address
|
|
(`web_interface/auth.py`). Deliberately left open even then: requests
|
|
from the Pi itself (loopback without proxy headers; a reverse proxy on
|
|
the Pi must add `X-Forwarded-For`, or every request it relays counts as
|
|
local), the Wi-Fi setup flow while the Pi is in access-point mode,
|
|
static files, and a status-only `/api/v3/health`. The password is a
|
|
werkzeug hash and tokens are stored as SHA-256, in
|
|
`config/config_secrets.json`, which no API returns. There is no TLS:
|
|
over plain HTTP the password and tokens cross the LAN in the clear, so
|
|
still don't expose port 5000 to the internet; put a TLS reverse proxy
|
|
or a VPN in front for remote access. Anyone with shell access to the Pi
|
|
can turn login off (`scripts/reset_web_password.py`), which is the
|
|
documented recovery path.
|
|
"Trusted network" does not mean "trusted websites", though: any page
|
|
a LAN user opens could make their browser POST to the Pi. So the
|
|
interface refuses a `POST`/`PUT`/`PATCH`/`DELETE` whose `Origin` (or
|
|
`Referer`) header names another site (`web_interface/origin_guard.py`),
|
|
and `/api/v3/system/action` only accepts JSON or HTMX requests. Tools
|
|
that send neither header (curl, Home Assistant, the MQTT bridge) are
|
|
unaffected. Not covered: DNS rebinding, and anyone who can reach the
|
|
port directly.
|
|
- **Plugins run unsandboxed.** Installed plugins execute in the same
|
|
Python process as the display loop with full file-system and
|
|
network access. Review plugin code (especially third-party plugins
|
|
from arbitrary GitHub URLs) before installing. The Plugin Store
|
|
marks community plugins as **Custom** to highlight this.
|
|
- **The display service runs as root** for hardware GPIO access. This
|
|
is required by `rpi-rgb-led-matrix`.
|
|
- **`config_secrets.json` is plaintext.** API keys and tokens are
|
|
stored unencrypted on the Pi. Lock down filesystem permissions on
|
|
the config directory if this matters for your deployment.
|
|
|
|
These are documented as known limitations rather than bugs. If you
|
|
have ideas for improving them while keeping the project usable on a
|
|
Pi, open a discussion — we're interested.
|
|
|
|
## Supported versions
|
|
|
|
LEDMatrix is rolling-release on `main`. Security fixes land on `main`
|
|
and become available the next time users run **Update Code** from the
|
|
web UI's Overview tab (which does a `git pull`). There are no LTS
|
|
branches.
|