From 18b2a25af5d1a59824f45a3e37b0ea749b44166a Mon Sep 17 00:00:00 2001 From: Malix Date: Thu, 7 Nov 2024 06:30:51 +0100 Subject: [PATCH] chore: docs dir (#527) * chore: docs dir * docs: feat support --------- Co-authored-by: RoyalOughtness <129108030+RoyalOughtness@users.noreply.github.com> --- CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md => docs/CONTRIBUTING.md | 30 +++++++++---------- DONATE.md => docs/DONATE.md | 2 -- FAQ.md => docs/FAQ.md | 8 ++--- .../POSTINSTALL-README.md | 4 +-- .../PREINSTALL-README.md | 0 README.md => docs/README.md | 16 +++++----- RECOMMENDED.md => docs/RECOMMENDED.md | 2 +- docs/SUPPORT.md | 1 + USERNS.md => docs/USERNS.md | 2 +- 10 files changed, 32 insertions(+), 33 deletions(-) rename CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md (100%) rename CONTRIBUTING.md => docs/CONTRIBUTING.md (92%) rename DONATE.md => docs/DONATE.md (99%) rename FAQ.md => docs/FAQ.md (97%) rename POSTINSTALL-README.md => docs/POSTINSTALL-README.md (99%) rename PREINSTALL-README.md => docs/PREINSTALL-README.md (100%) rename README.md => docs/README.md (98%) rename RECOMMENDED.md => docs/RECOMMENDED.md (96%) create mode 100644 docs/SUPPORT.md rename USERNS.md => docs/USERNS.md (98%) diff --git a/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to docs/CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 92% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index 42fcb5b..9ede95e 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,14 +1,14 @@ # Welcome to secureblue Thanks for taking the time to look into helping out! -All contributions are appreciated! +All contributions are appreciated! Please refer to our [Code of Conduct](/CODE_OF_CONDUCT.md) while you're at it! Feel free to report issues as you find them! # Contributing -All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. > And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: > - Star the project @@ -42,7 +42,7 @@ to secureblueadmin@proton.me ## I Want To Contribute -> ### Legal Notice +> ### Legal Notice > When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. ### Reporting Bugs @@ -55,7 +55,7 @@ A good bug report should describe the issue in detail. Generally speaking: - Remember that these are unofficial builds, it's usually prudent to investigate an issue before reporting it here or in Fedora! - Collect information about the bug: - `rpm-ostree status -v` usually helps -- Image and Version +- Image and Version - Possibly your input and the output - Can you reliably reproduce the issue? And can you also reproduce it with older versions? @@ -72,13 +72,13 @@ A good pull request should be ready for review before it is even created. For al ### How to test incoming changes -One of the nice things about the image model is that we can generate an entire OS image for every change we want to commit, so this makes testing way easier than in the past. You can rebase to it, see if it works, and then move back. This also means we can increase the amount of testers! +One of the nice things about the image model is that we can generate an entire OS image for every change we want to commit, so this makes testing way easier than in the past. You can rebase to it, see if it works, and then move back. This also means we can increase the amount of testers! We strive towards a model where proposed changes are more thoroughly reviewed and tested by the community. So here's how to do it. If you see a pull request that is opened up on an image you're following you can leave a review on how it's working for you. ## Building Locally -The minimum tools required are git and a working machine with podman enabled and configured. +The minimum tools required are git and a working machine with podman enabled and configured. Building locally is much faster than building in GitHub and is a good way to move fast before pushing to a remote. ### Clone the repo @@ -86,22 +86,22 @@ Building locally is much faster than building in GitHub and is a good way to mov git clone https://github.com/secureblue/secureblue.git ### Build the image - -First make sure you can build an existing image: - + +First make sure you can build an existing image: + podman build . -t something - + Then confirm your image built: - - podman image ls + + podman image ls TODO: Set up and push to your own local registry - + ### Make your changes -This usually involved editing the `Containerfile`. Most techniques for building containers apply here, if you're new to containers using the term "Dockerfile" in your searches usually shows more results when you're searching for information. +This usually involved editing the `Containerfile`. Most techniques for building containers apply here, if you're new to containers using the term "Dockerfile" in your searches usually shows more results when you're searching for information. -Check out CoreOS's [layering examples](https://github.com/coreos/layering-examples) for more information on customizing. +Check out CoreOS's [layering examples](https://github.com/coreos/layering-examples) for more information on customizing. ## Styleguides ### Commit Messages diff --git a/DONATE.md b/docs/DONATE.md similarity index 99% rename from DONATE.md rename to docs/DONATE.md index da02846..028ecf3 100644 --- a/DONATE.md +++ b/docs/DONATE.md @@ -27,5 +27,3 @@ There are multiple options available for donation: `0x10289B51aEF109BBc07F68341F2Df8Ef60a5b618` - - diff --git a/FAQ.md b/docs/FAQ.md similarity index 97% rename from FAQ.md rename to docs/FAQ.md index f2c323e..8dcfb68 100644 --- a/FAQ.md +++ b/docs/FAQ.md @@ -14,7 +14,7 @@ During rpm-ostree operations, it's normal. Outside of that, make sure you follow #### Should I use firejail? -[No](https://madaidans-insecurities.github.io/linux.html#firejail), use ``bubblejail`` if there's no flatpak available for an app. +[No](https://madaidans-insecurities.github.io/linux.html#firejail), use ``bubblejail`` if there's no flatpak available for an app. #### An app I use won't start due to a malloc issue. How do I fix it? @@ -61,7 +61,7 @@ This is an issue with rpm-ostree image-based systems generally, and not specific #### Why can't I install new KDE themes? -The functionality that provides this, called GHNS, is disabled by default due to the risk posed by the installation of potentially damaging or malicious scripts. This has caused [real damage](https://blog.davidedmundson.co.uk/blog/kde-store-content/). +The functionality that provides this, called GHNS, is disabled by default due to the risk posed by the installation of potentially damaging or malicious scripts. This has caused [real damage](https://blog.davidedmundson.co.uk/blog/kde-store-content/). If you still want to enable this functionality, run: @@ -106,9 +106,9 @@ On the secureblue github page, click "Watch", and then "Custom", and select Rele #### Why don't my AppImages work? -AppImages depend on fuse2, which is unmaintained and depends on a suid root binary. For this reason, fuse2 support is removed by default. It's strongly recommended that you find alternative mechanisms to install your applications (flatpak, distrobox, etc). If you can't find an alternative and still need fuse2, you can add it back by layering something that depends on it. +AppImages depend on fuse2, which is unmaintained and depends on a suid root binary. For this reason, fuse2 support is removed by default. It's strongly recommended that you find alternative mechanisms to install your applications (flatpak, distrobox, etc). If you can't find an alternative and still need fuse2, you can add it back by layering something that depends on it. -For example: +For example: ``` rpm-ostree install zfs-fuse diff --git a/POSTINSTALL-README.md b/docs/POSTINSTALL-README.md similarity index 99% rename from POSTINSTALL-README.md rename to docs/POSTINSTALL-README.md index c93ac34..c4f6eae 100644 --- a/POSTINSTALL-README.md +++ b/docs/POSTINSTALL-README.md @@ -51,7 +51,7 @@ If you answer `N`, or press enter without any input, support for 32-bit programs However, there are certain exceptions. A couple common usecases are if you need Steam, or run an ocassional application in Wine you'll likely want to keep support for 32-bit programs. If this is the case, answer `Y`. ### Unstable hardening kargs -If you answer `Y` when prompted, additional (unstable) hardening kargs will be applied, which can cause issues on some hardware, but stable on other hardware. +If you answer `Y` when prompted, additional (unstable) hardening kargs will be applied, which can cause issues on some hardware, but stable on other hardware. ## Setup USBGuard @@ -122,7 +122,7 @@ To enable TPM2 LUKS unlocking, run: ``` ujust setup-luks-tpm-unlock -``` +``` Type `Y` when asked if you want to set a PIN. ## Validation diff --git a/PREINSTALL-README.md b/docs/PREINSTALL-README.md similarity index 100% rename from PREINSTALL-README.md rename to docs/PREINSTALL-README.md diff --git a/README.md b/docs/README.md similarity index 98% rename from README.md rename to docs/README.md index 368aa2a..73c92d7 100644 --- a/README.md +++ b/docs/README.md @@ -32,7 +32,7 @@ The following are not in scope: - Remove SUID-root from [numerous binaries](https://github.com/secureblue/secureblue/blob/live/files/scripts/removesuid.sh) and replace functionality [using capabilities](https://github.com/secureblue/secureblue/blob/live/files/system/usr/bin/setcapsforunsuidbinaries) - Disable Xwayland by default (for GNOME, Plasma, and Sway images) - Mitigation of [LD_PRELOAD attacks](https://github.com/Aishou/wayland-keylogger) via `ujust toggle-bash-environment-lockdown` -- Disabling coredumps +- Disabling coredumps - Disabling all ports and services for firewalld - Adds per-network MAC randomization - Blacklisting numerous unused kernel modules to reduce attack surface [details](https://github.com/secureblue/secureblue/blob/live/files/system/etc/modprobe.d/blacklist.conf) @@ -63,7 +63,7 @@ For more info on BlueBuild, check out the [BlueBuild homepage](https://blue-buil # Customization -If you want to add your own customizations on top of secureblue, you are advised strongly against forking. Instead, create a repo for your own image by using the [BlueBuild template](https://github.com/blue-build/template), then change your `base-image` to a secureblue image. This will allow you to apply your customizations to secureblue in a concise and maintainable way, without the need to constantly sync with upstream. +If you want to add your own customizations on top of secureblue, you are advised strongly against forking. Instead, create a repo for your own image by using the [BlueBuild template](https://github.com/blue-build/template), then change your `base-image` to a secureblue image. This will allow you to apply your customizations to secureblue in a concise and maintainable way, without the need to constantly sync with upstream. # FAQ @@ -78,8 +78,8 @@ Sponsorship options are on the [Donate](DONATE.md) page. All donations are appre Have a look at [PREINSTALL-README](PREINSTALL-README.md) before proceeding. ## Rebasing (Recommended) -> [!NOTE] -> If you don't already have a Fedora Atomic installation, use a Fedora Atomic ISO that matches your secureblue target image to install one. If you want to use a secureblue Silverblue image, start with the Fedora Silverblue ISO, Kinoite for Kinoite, Sericea (Sway Atomic) for Sericea and all the Wayblue images, and CoreOS for all the securecore images. +> [!NOTE] +> If you don't already have a Fedora Atomic installation, use a Fedora Atomic ISO that matches your secureblue target image to install one. If you want to use a secureblue Silverblue image, start with the Fedora Silverblue ISO, Kinoite for Kinoite, Sericea (Sway Atomic) for Sericea and all the Wayblue images, and CoreOS for all the securecore images. To rebase a [Fedora Atomic](https://fedoraproject.org/atomic-desktops/) or [Fedora CoreOS](https://fedoraproject.org/coreos/) installation, follow these steps‡: @@ -104,7 +104,7 @@ To rebase a [Fedora Atomic](https://fedoraproject.org/atomic-desktops/) or [Fedo ``` ‡ Replace `IMAGE_NAME` with the *full name* of your preferred image from the [list below](README.md#images). -## ISO +## ISO While it's recommended to use a Fedora Atomic ISO to install and then rebase that installation to secureblue, you can also generate an ISO and install that directly using [this script](generate_secureblue_iso.sh). Please note you should still follow the [post-install steps](README.md#post-install) when installing from a generated ISO: @@ -201,8 +201,8 @@ While it's recommended to use a Fedora Atomic ISO to install and then rebase tha | `wayblue-sway-nvidia-open-userns-hardened` | Wayblue-Sway | Yes, open drivers | Yes | ## Server -> [!NOTE] -> After you finish setting up your [Fedora CoreOS](https://fedoraproject.org/coreos/) installation, you will need to disable `zincati.service` before rebasing to securecore. +> [!NOTE] +> After you finish setting up your [Fedora CoreOS](https://fedoraproject.org/coreos/) installation, you will need to disable `zincati.service` before rebasing to securecore. | Name | Base | Nvidia Support | ZFS Support | Unpriv. Userns | |-------------------------------------------|-----------|-------------------------|-------------|------------------------------| @@ -246,5 +246,5 @@ Follow the [contributing documentation](CONTRIBUTING.md#contributing), and make For local Development [building locally](CONTRIBUTING.md#building-locally) is the recommended approach. -## Community +## Community Opening issues is preferred, but [Discord](https://discord.gg/qMTv5cKfbF) is available as well. diff --git a/RECOMMENDED.md b/docs/RECOMMENDED.md similarity index 96% rename from RECOMMENDED.md rename to docs/RECOMMENDED.md index 58cf5a7..8059b39 100644 --- a/RECOMMENDED.md +++ b/docs/RECOMMENDED.md @@ -1,3 +1,3 @@ -GNOME is the only desktop that secures privileged wayland protocols like screencopy. This means that on non-GNOME systems, applications can access screen content of the entire desktop. This implicitly includes the content of other applications. It's primarily for this reason that GNOME images are recommended. KDE has [plans](https://invent.kde.org/plasma/xdg-desktop-portal-kde/-/issues/7) to fix this. +GNOME is the only desktop that secures privileged wayland protocols like screencopy. This means that on non-GNOME systems, applications can access screen content of the entire desktop. This implicitly includes the content of other applications. It's primarily for this reason that GNOME images are recommended. KDE has [plans](https://invent.kde.org/plasma/xdg-desktop-portal-kde/-/issues/7) to fix this. GNOME also provides [thumbnailer sandboxing](https://gitlab.gnome.org/GNOME/gnome-desktop/-/issues/213) in Gnome Files, which mitigates attacks [via thumbnailers](https://scarybeastsecurity.blogspot.com/2016/11/0day-exploit-compromising-linux-desktop.html). diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md new file mode 100644 index 0000000..4ada772 --- /dev/null +++ b/docs/SUPPORT.md @@ -0,0 +1 @@ +Support and Discussion with the Community : https://discord.gg/gNr3Kbks34 diff --git a/USERNS.md b/docs/USERNS.md similarity index 98% rename from USERNS.md rename to docs/USERNS.md index 5351235..7aac482 100644 --- a/USERNS.md +++ b/docs/USERNS.md @@ -2,7 +2,7 @@ [User namespaces](https://en.wikipedia.org/wiki/Linux_namespaces#User_ID_(user)) are a kernel feature introduced in kernel version 3.8. When an unprivileged user asks the kernel to create a namespace, the kernel needs to permit that user to do so. Whether this is permitted by the kernel is controlled via a sysctl flag. -There is a [long history](https://madaidans-insecurities.github.io/linux.html#kernel) of vulnerabilities made possible by allowing this functionality for unprivileged users ever since its [introduction](https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction). Given this history, you might think we should just disable this functionality altogether. However if this functionality is disabled, then flatpak can't function without the suid bit set on the bubblewrap binary. In this scenario bubblewrap creates namespaces on behalf of the user instead of the kernel, by running as root. This means trusting bubblewrap (a significantly less battle-tested piece of software than the kernel) to run as root. However, some see this as still a preferable tradeoff (trusting one small program with root in exchange for reducing the kernel's attack surface). +There is a [long history](https://madaidans-insecurities.github.io/linux.html#kernel) of vulnerabilities made possible by allowing this functionality for unprivileged users ever since its [introduction](https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction). Given this history, you might think we should just disable this functionality altogether. However if this functionality is disabled, then flatpak can't function without the suid bit set on the bubblewrap binary. In this scenario bubblewrap creates namespaces on behalf of the user instead of the kernel, by running as root. This means trusting bubblewrap (a significantly less battle-tested piece of software than the kernel) to run as root. However, some see this as still a preferable tradeoff (trusting one small program with root in exchange for reducing the kernel's attack surface). Ultimately we leave both options available because it's a tradeoff and neither is demonstrably preferable from a security standpoint. It should also be noted that podman, toolbox, and distrobox require unprivileged user namespaces to function and are therefore [removed in the non-userns images](https://github.com/secureblue/secureblue/blob/live/recipes/common/disableuserns-packages.yml).