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. + + 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. 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).