From 6db515b161282ca306f70bf551e351f1d526909d Mon Sep 17 00:00:00 2001 From: Simon Walz Date: Sun, 30 Aug 2026 00:16:34 +0000 Subject: [PATCH 1/3] doc: Issue and pull-request templates for the whole organisation Placed here so every repository inherits them. The bug form asks for the component, the platform and the version, because those three decide almost every answer and are what a report usually lacks. The pull-request template states the DCO sign-off that CI enforces, and asks what was verified rather than offering a checkbox that can mean nothing. Blank issues stay enabled: a report that fits no template is still a report. Signed-off-by: Simon Walz --- .github/ISSUE_TEMPLATE/bug_report.yml | 70 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 13 ++++ .github/ISSUE_TEMPLATE/feature_request.yml | 37 ++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 27 +++++++++ 4 files changed, 147 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..9384c6a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: Apache-2.0 +name: Bug report +description: Something does not work as documented +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this. If it is a **security** + issue, please do not file it here — see the security policy instead. + + - type: dropdown + id: component + attributes: + label: Which part of CuOS? + options: + - cuos — the operating system, updater, factories + - cuos-release — tool.sh, building images and installers + - cuos-iac — IaC manager, WebUI, fleet + - Not sure + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Platform + options: + - x86_64 + - rpi-arm64 (64-bit Raspberry Pi) + - rpi-arm32 (32-bit Raspberry Pi) + - orangepi-zero3 + - LXC container + - Other / not applicable + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened, and what did you expect instead? + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: How can we reproduce it? + description: The commands you ran, and the relevant part of your `system.json` — **with passwords and registry credentials removed**. + render: shell + validations: + required: true + + - type: textarea + id: version + attributes: + label: Version + description: | + On a running system: `cuos version`. + When building: the tag or commit of the repository, and `./tool.sh name your-system.json`. + render: shell + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs + description: "`cuos log`, or `journalctl -u cuos-*` — again with any secrets removed." + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ab9c70f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,13 @@ +# SPDX-License-Identifier: Apache-2.0 +# Blank issues stay enabled: a report that fits no template is still a report. +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: https://github.com/cuos-dev/.github/security/policy + about: Do not open an issue. Report it privately — see the security policy. + - name: Building a system — documentation + url: https://github.com/cuos-dev/cuos-release#readme + about: How to define a system and build an image, installer or container. + - name: The operating system — documentation + url: https://github.com/cuos-dev/cuos/tree/main/docs + about: Architecture, system.json, the update mechanism, platform support. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6280e61 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: Apache-2.0 +name: Feature request +description: Suggest something CuOS should be able to do +labels: ["enhancement"] +body: + - type: dropdown + id: component + attributes: + label: Which part of CuOS? + options: + - cuos — the operating system, updater, factories + - cuos-release — tool.sh, building images and installers + - cuos-iac — IaC manager, WebUI, fleet + - Not sure + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What are you trying to do? + description: The situation you are in, rather than the solution you have in mind — it often turns out there is a shorter way. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: What would you like CuOS to do? + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: What are you doing instead today? + description: A workaround, another tool, or nothing at all — all three are useful to know. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..c7ad36d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,27 @@ +## What does this change, and why? + + + +## How was it verified? + + + +## Checklist + +- [ ] Every commit is signed off (`git commit -s`) — see [DCO.txt](../DCO.txt). + CI checks this and will fail the pull request otherwise. +- [ ] New shell scripts carry `# SPDX-License-Identifier: Apache-2.0`. +- [ ] `shellcheck --severity=warning` is clean, and any `*.test.sh` passes. +- [ ] The documentation matches the change — including any command in a README + that this renames or removes. + + From 10c8abe4500774f70c6421d3643861d0a585c802 Mon Sep 17 00:00:00 2001 From: Simon Walz Date: Sun, 30 Aug 2026 00:16:34 +0000 Subject: [PATCH 2/3] doc: A real reporting channel and response times in SECURITY.md It pointed at an Impressum page rather than a channel, promised only to respond "as quickly as possible", and said nothing about which versions get fixes. Now: GitHub private vulnerability reporting as the route, with an email fallback; acknowledgement in 5 working days and an assessment in 10; and the honest position on versions - pre-1.0, no backports, fixes land in the current release. Scope is stated in both directions, so a report about an application container running on CuOS is not mistaken for a CuOS vulnerability. Private vulnerability reporting has to be enabled per repository before the primary route works. Signed-off-by: Simon Walz --- SECURITY.md | 67 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 5c9698a..45a55ce 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,25 +1,64 @@ # Security Policy -## Supported Versions +## Reporting a vulnerability -We release security updates for the latest stable version of the software. Older versions may not receive security updates. +**Please do not open a public issue for a security problem.** -## Reporting a Vulnerability +Report it through **GitHub's private vulnerability reporting**: go to the +affected repository, open the *Security* tab, and choose *Report a +vulnerability*. That keeps the report private to you and the maintainers until +a fix is available, and gives you a thread to follow it in. -If you discover a security vulnerability, please report it to us privately. Do not create a public issue. +If you cannot use that — no GitHub account, or the repository does not offer +it — email **contact@simonwalz.de** with `CuOS security` in the subject. -Please email [Simon Walz](https://simonwalz.de/?id=impressum) with the details of the vulnerability. Include: +Please include: -- A description of the vulnerability -- Steps to reproduce -- Any relevant logs or screenshots +- which component and version (`cuos version` on a running system, or the tag + or commit you built from) +- what an attacker can do, and what access they need to start +- steps to reproduce, and any logs — **with credentials removed** -We will respond as quickly as possible and coordinate a fix and disclosure timeline. +### What happens next -## Security Best Practices +| | | +|---|---| +| We acknowledge the report | within **5 working days** | +| We tell you whether we can reproduce it, and our assessment | within **10 working days** | +| We agree a disclosure date with you | once a fix or a mitigation exists | -- Keep your dependencies up to date. -- Avoid exposing sensitive data in logs or error messages. -- Use secure coding practices and input validation. +If you do not hear from us in that time, please chase us — a missed +notification is more likely than silence on purpose. -Thank you for helping us keep our project secure! +We will credit you in the release notes unless you would rather stay anonymous. +We have no bug bounty. + +## Which versions get fixes + +CuOS is **pre-1.0 and has no long-term support branches**. Security fixes go +into the current release; there are no backports to older tags. If you run a +pinned version, expect to move forward to take a fix. + +Every CuOS image reference is pinned by digest and a mismatch is fatal, so +updating means changing the pin deliberately rather than drifting onto a new +image by accident. + +## What is in scope + +The four repositories of this organisation: the operating system and its update +mechanism (`cuos`), the build tooling (`cuos-release`), the IaC manager, WebUI +and fleet components (`cuos-iac`), and these org-wide files. + +Out of scope: vulnerabilities in application containers you run **on** CuOS, +which belong to their own projects; and the consequences of a configuration that +deliberately weakens the system — an unprivileged report that CuOS is insecure +when run with `os_root_password` set to a known value tells us nothing. + +## Hardening your own deployment + +- Pin images by digest and update deliberately. +- Keep registry credentials out of images and out of `system.json` files you + share; use the config encryption in `cuos-release`. +- Sign your IaC repository's commits and set `iac_repo_signing_keys`, so a + device only applies configuration it can verify. +- Give the application container only the privileges it needs. From 33a0f0b2c4e31379c9bf0a50216463f0e7dfe11d Mon Sep 17 00:00:00 2001 From: Simon Walz Date: Sun, 30 Aug 2026 00:16:34 +0000 Subject: [PATCH 3/3] doc: The org profile did not mention cuos-release It is where a reader starts - it builds the images - but the overview listed cuos-iac twice and left it out entirely. Added as its own layer, plus a "Start here" line above the table. Signed-off-by: Simon Walz --- profile/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/profile/README.md b/profile/README.md index 8a38c41..35ec558 100644 --- a/profile/README.md +++ b/profile/README.md @@ -4,6 +4,10 @@ The CuOS operating system is also a solid base for IoT, edge, and VM-based products. +## Start here + +**To build a bootable system**, start at [cuos-release](https://github.com/cuos-dev/cuos-release#readme): describe the system you want in a `system.json` and run `./tool.sh image`. It produces a disk image, an ISO installer or an LXC container. + ## Framework overview Components are organized in layers from device to service: @@ -12,7 +16,8 @@ Components are organized in layers from device to service: | --- | --- | --- | | Device management | CuOS Fleet Management — agent + server for device enrollment, health telemetry, remote commands, and rollout orchestration. | [cuos-iac](https://github.com/cuos-dev/cuos-iac#readme) | | Service management | CuOS IaC — Infrastructure-as-Code manager and Web UI for defining services, builds, deployments, and release channels. | [cuos-iac](https://github.com/cuos-dev/cuos-iac#readme) | -| Operating system | CuOS (OS) — minimal OS image with updater, image and installer factories, OTA tooling and reproducible builds. | [cuos](https://github.com/cuos-dev/cuos#readme) | +| Operating system | CuOS (OS) — minimal OS image with updater, OTA tooling and reproducible builds. | [cuos](https://github.com/cuos-dev/cuos#readme) | +| Build & release | CuOS Release Tooling — `tool.sh`, the image and installer factories, pinned image versions, configuration merging, signing and encryption. | [cuos-release](https://github.com/cuos-dev/cuos-release#readme) | All components can be used independently — each CuOS component works standalone (you don’t need to run the others to use a single component).