From 38773044e9ceb4ff3ba118e4151f615509064d24 Mon Sep 17 00:00:00 2001 From: Chuck Date: Tue, 7 Apr 2026 12:52:48 -0400 Subject: [PATCH] Add CODE_OF_CONDUCT, SECURITY, PR template; link them from README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tier 1 organizational files that any open-source project at LEDMatrix's maturity is expected to have. None of these existed before. They're additive — no existing content was rewritten. CODE_OF_CONDUCT.md - Contributor Covenant 2.1 (the de facto standard for open-source projects). Mentions both the Discord and the GitHub Security Advisories channel for reporting violations. SECURITY.md - Private vulnerability disclosure flow with two channels: GitHub Security Advisories (preferred) and Discord DM. - Documents the project's known security model as intentional rather than vulnerabilities: no web UI auth, plugins run unsandboxed, display service runs as root for GPIO access, config_secrets.json is plaintext. These match the limitations already called out in PLUGIN_QUICK_REFERENCE.md and the audit flagging from earlier in this PR. - Out-of-scope section points users at upstream (rpi-rgb-led-matrix, third-party plugins) so reports land in the right place. .github/PULL_REQUEST_TEMPLATE.md - 10-line checklist that prompts for the things that would have caught the bugs in this very PR: did you load the changed plugin once, did you update docs alongside code, are there any plugin compatibility implications. - Linked from CONTRIBUTING.md for the full flow. README.md - Added a License section near the bottom (the README previously said nothing about the license despite the project being GPL-3.0). - Added a Contributing section pointing at CONTRIBUTING.md and SECURITY.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/PULL_REQUEST_TEMPLATE.md | 62 ++++++++++++++ CODE_OF_CONDUCT.md | 137 +++++++++++++++++++++++++++++++ README.md | 24 ++++++ SECURITY.md | 86 +++++++++++++++++++ 4 files changed, 309 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..d78232d9 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,62 @@ +# Pull Request + +## Summary + + + +## Type of change + + + +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation +- [ ] Refactor (no functional change) +- [ ] Build / CI +- [ ] Plugin work (link to the plugin) + +## Related issues + + + +## Test plan + + + +- [ ] Ran on a real Raspberry Pi with hardware +- [ ] Ran in emulator mode (`EMULATOR=true python3 run.py`) +- [ ] Ran the dev preview server (`scripts/dev_server.py`) +- [ ] Ran the test suite (`pytest`) +- [ ] Manually verified the affected code path in the web UI +- [ ] N/A — documentation-only change + +## Documentation + +- [ ] I updated `README.md` if user-facing behavior changed +- [ ] I updated the relevant doc in `docs/` if developer behavior changed +- [ ] I added/updated docstrings on new public functions +- [ ] N/A — no docs needed + +## Plugin compatibility + + + +- [ ] No plugin breakage expected +- [ ] Some plugins will need updates — listed below +- [ ] N/A — change doesn't touch the plugin system + +## Checklist + +- [ ] My commits follow the message convention in `CONTRIBUTING.md` +- [ ] I read `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` +- [ ] I've not committed any secrets or hardcoded API keys +- [ ] If this adds a new config key, the form in the web UI was + verified (the form is generated from `config_schema.json`) + +## Notes for reviewer + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..a1594b71 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,137 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +This includes the LEDMatrix Discord server, GitHub repositories owned by +ChuckBuilds, and any other forums hosted by or affiliated with the project. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement on the +[LEDMatrix Discord](https://discord.gg/uW36dVAtcT) (DM a moderator or +ChuckBuilds directly) or by opening a private GitHub Security Advisory if +the issue involves account safety. All complaints will be reviewed and +investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/README.md b/README.md index 1b5e10ee..eb8f244a 100644 --- a/README.md +++ b/README.md @@ -878,3 +878,27 @@ sudo systemctl enable ledmatrix-web.service ### If you've read this far — thanks! + +----------------------------------------------------------------------------------- + +## License + +LEDMatrix is licensed under the +[GNU General Public License v3.0 or later](LICENSE). + +LEDMatrix builds on +[`rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix), +which is GPL-2.0-or-later. The "or later" clause makes it compatible +with GPL-3.0 distribution. + +Plugin contributions in +[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins) +are also GPL-3.0-or-later unless individual plugins specify otherwise. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the PR +flow, and how to add a plugin. Bug reports and feature requests go in +the [issue tracker](https://github.com/ChuckBuilds/LEDMatrix/issues). +Security issues should be reported privately per +[SECURITY.md](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..52124d5f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,86 @@ +# 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: +2. **Discord DM**. Send a direct message to a moderator on the + [LEDMatrix Discord](https://discord.gg/uW36dVAtcT). 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 +- 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: + +- **No web UI authentication.** The web interface assumes the network + it's running on is trusted. Don't expose port 5000 to the internet. +- **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.