mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-08-22 02:48:15 +00:00

Files

T

ChuckBuildsandClaude Opus 5 e499efb1f0 fix(composer): resolve plugin paths at the filesystem boundary

CodeQL reports 19 alerts against this PR -- 16 high-severity
py/path-injection plus 3 py/stack-trace-exposure -- all in
web_interface/blueprints/composer.py, where a request-supplied plugin_id
reaches Path(plugins_dir) / plugin_id and the result is created, written
to, deleted with shutil.rmtree, and read back.

The path-injection alerts are false positives today. _PLUGIN_ID_RE is
fully anchored and permits only [a-z][a-z0-9-]{0,62}, so every traversal
payload is already rejected; I checked fourteen of them, including
../../etc/passwd, a/../../etc, /etc/passwd and encoded variants, and none
gets past it.

They are worth fixing anyway. The guarantee lived in a regex several
hundred lines from the path building, so relaxing that pattern later --
to allow an underscore, say -- would open a traversal with nothing at the
filesystem boundary to catch it. _plugin_dir() now resolves the candidate
and refuses anything that is not inside plugins_dir, and all three call
sites go through it. That is also the shape static analysis recognises,
which is why sixteen alerts landed on code that was already safe.

The regex anchor moves from $ to \Z. Python's $ also matches just before
a trailing newline, so "myplugin\n" was accepted and would have created a
directory whose name ends in one. Not traversal, but not a name anything
downstream should have to handle.

For the stack-trace exposure: the handlers returned str(exc) for any
ValueError out of _generate_plugin_files. The seven raises there are all
curated, user-facing validation messages, and they now use a
ComposerInputError subclass so they keep reaching the user verbatim. A
ValueError from anywhere else -- json, int(), a library -- is logged with
a traceback and answered generically, since its text can name internal
paths.

Verified: 32 tests covering fourteen traversal payloads and twelve
malformed ids. The key one re-runs every payload with the id pattern
deliberately loosened to allow slashes and dots; removing the containment
check fails it with

    these escaped the base with a loosened regex:
      [('/etc/passwd', '/etc/passwd'), ('//etc/passwd', '//etc/passwd')]

so the boundary is doing real work rather than shadowing the regex.

The 5 failures in test_web_api.py are unrelated and pre-existing on this
branch -- identical counts with these changes stashed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STMbQE4YctTacQXfbYqKuW

2026-08-21 17:18:26 -04:00

blueprints

fix(composer): resolve plugin paths at the filesystem boundary

2026-08-21 17:18:26 -04:00

static/v3

feat(web): add Plugin Composer -- visual drag-and-drop plugin builder

2026-07-14 16:27:50 -04:00

templates/v3

feat(web): add Plugin Composer -- visual drag-and-drop plugin builder

2026-07-14 16:27:50 -04:00

__init__.py

Plugins (#145 )

2025-12-27 14:15:49 -05:00

app.py

perf(display): snapshot mirror — viewer gating, digest skip, keepalive (#404 )

2026-07-13 09:28:30 -04:00

cache.py

Plugins (#145 )

2025-12-27 14:15:49 -05:00

logging_config.py

fix: Codacy security fixes, CVE dependency bumps, and code quality cleanup (#331 )

2026-05-15 10:19:55 -04:00

README.md

docs: refresh and correct stale documentation across repo (#306 )

2026-04-07 21:04:25 -04:00

requirements.txt

fix: Codacy security fixes, CVE dependency bumps, and code quality cleanup (#331 )

2026-05-15 10:19:55 -04:00

run.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

start.py

fix: Codacy round-2 — urllib3 CVEs, missed JS/Python issues (#336 )

2026-05-15 18:04:21 -04:00

README.md

LED Matrix Web Interface V3

Modern, production web interface for controlling the LED Matrix display.

Overview

This directory contains the active V3 web interface with the following features:

Real-time display preview via Server-Sent Events (SSE)
Plugin management and configuration
System monitoring and logs
Modern, responsive UI
RESTful API

Directory Structure

web_interface/
├── app.py                    # Main Flask application
├── start.py                  # Startup script
├── run.sh                    # Shell runner script
├── requirements.txt          # Python dependencies
├── blueprints/               # Flask blueprints
│   ├── api_v3.py            # API endpoints
│   └── pages_v3.py          # Page routes
├── templates/                # HTML templates
│   └── v3/
│       ├── base.html
│       ├── index.html
│       └── partials/
└── static/                   # CSS/JS assets
    └── v3/
        ├── app.css
        └── app.js

Running the Web Interface

Standalone (Development)

From the project root:

python3 web_interface/start.py

Or using the shell script:

./web_interface/run.sh

As a Service (Production)

The web interface can run as a systemd service that starts automatically based on the web_display_autostart configuration setting:

sudo systemctl start ledmatrix-web
sudo systemctl enable ledmatrix-web  # Start on boot

Accessing the Interface

Once running, access the web interface at:

Local: http://localhost:5000
Network: http://:5000

Configuration

The web interface reads configuration from:

config/config.json - Main configuration
config/config_secrets.json - API keys and secrets

API Documentation

The V3 API is mounted at /api/v3/ (app.py:144). For the complete list and request/response formats, see docs/REST_API_REFERENCE.md. Quick reference for the most common endpoints:

Configuration

GET /api/v3/config/main - Get main configuration
POST /api/v3/config/main - Save main configuration
GET /api/v3/config/secrets - Get secrets configuration
POST /api/v3/config/raw/main - Save raw main config (Config Editor)
POST /api/v3/config/raw/secrets - Save raw secrets

Display & System Control

GET /api/v3/system/status - System status
POST /api/v3/system/action - Control display (action body: start_display, stop_display, restart_display_service, restart_web_service, git_pull, reboot_system, shutdown_system, enable_autostart, disable_autostart)
GET /api/v3/display/current - Current display frame
GET /api/v3/display/on-demand/status - On-demand status
POST /api/v3/display/on-demand/start - Trigger on-demand display
POST /api/v3/display/on-demand/stop - Clear on-demand

Plugins

GET /api/v3/plugins/installed - List installed plugins
GET /api/v3/plugins/config?plugin_id=<id> - Get plugin config
POST /api/v3/plugins/config - Update plugin configuration
GET /api/v3/plugins/schema?plugin_id=<id> - Get plugin schema
POST /api/v3/plugins/toggle - Enable/disable plugin
POST /api/v3/plugins/install - Install from registry
POST /api/v3/plugins/install-from-url - Install from GitHub URL
POST /api/v3/plugins/uninstall - Uninstall plugin
POST /api/v3/plugins/update - Update plugin

Plugin Store

GET /api/v3/plugins/store/list - List available registry plugins
GET /api/v3/plugins/store/github-status - GitHub authentication status
POST /api/v3/plugins/store/refresh - Refresh registry from GitHub

Real-time Streams (SSE)

SSE stream endpoints are defined directly on the Flask app (app.py:607-619 — includes the CSRF exemption and rate-limit hookup alongside the three route definitions), not on the api_v3 blueprint:

GET /api/v3/stream/stats - System statistics stream
GET /api/v3/stream/display - Display preview stream
GET /api/v3/stream/logs - Service logs stream

Development

When making changes to the web interface:

Edit files in this directory
Test changes by running python3 web_interface/start.py
Restart the service if running: sudo systemctl restart ledmatrix-web

Notes

Templates and static files use the v3/ prefix to allow for future versions
The interface uses Flask blueprints for modular organization
SSE streams provide real-time updates without polling