feat: add build architecture article (#296)

_headers

@@ -7,3 +7,7 @@
 /install
   ! Content-Security-Policy
   Content-Security-Policy: default-src 'none'; style-src 'self'; style-src-attr 'none'; font-src 'self'; img-src 'self'; manifest-src 'self'; form-action https://isos.secureblue.dev https://fosstorrents.com; frame-ancestors 'none'; base-uri 'none'; sandbox allow-popups-to-escape-sandbox allow-downloads allow-popups allow-forms; upgrade-insecure-requests;
+
+/articles/build-architecture
+  ! Content-Security-Policy
+  Content-Security-Policy: default-src 'none'; style-src 'self'; style-src-attr 'none'; font-src 'self'; img-src 'self'; manifest-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'; sandbox allow-popups; upgrade-insecure-requests;

_layouts/page.html

@@ -14,6 +14,8 @@
 
         <main>
             {{ content | replace: '<table>', '<div class="table-container"><table>' | replace: '</table>', '</table></div>' }}
+            {{ content | replace: '&lt;ul&gt;', '<ul>' | replace: '&lt;/ul&gt;, '</ul>' }}
+            {{ content | replace: '&lt;li&gt;', '<li>' | replace: '&lt;/li&gt;, '</li>' }}
         </main>
 
         {% include footer.html %}

assets/main.css

@@ -660,3 +660,17 @@ details[open] summary {
         background-color: #2c2c2e;
     }
 }
+
+figure {
+  border: thin silver solid;
+  padding: 5px;
+  margin: auto;
+}
+
+figcaption {
+  background-color: #222222;
+  color: white;
+  font: italic smaller sans-serif;
+  padding: 3px;
+  text-align: center;
+}

content/CODE_OF_CONDUCT.md

@@ -1,6 +1,6 @@
 ---
-title: "Code of Conduct | secureblue"
-description: "secureblue's Code of Conduct"
+title: "Code of conduct | secureblue"
+description: "secureblue's code of conduct"
 permalink: /code-of-conduct
 ---
 

content/IMAGES.md

@@ -6,7 +6,7 @@ permalink: /images
 
 # Images
 
-## Table of Contents
+## [Table of Contents](#table-of-contents)
 {: #table-of-contents}
 
 - [Security recommendation](#security-recommendation)
@@ -18,6 +18,7 @@ permalink: /images
   - [IoT](#iot)
 
 ## [Security recommendation](#security-recommendation)
+{: #security-recommendation}
 
 GNOME, KDE Plasma, Sway, and COSMIC (Silverblue, Kinoite, Sericea, and COSMIC images, respectively) secure privileged Wayland protocols like screencopy. This means that on environments outside of GNOME, KDE Plasma, Sway, and COSMIC, applications can access screen content of the entire desktop. This implicitly includes the content of other applications. It\'s primarily for this reason that Silverblue, Kinoite, and Sericea images are recommended.
 
@@ -36,10 +37,12 @@ This section is a relative recommendation between the desktop environments avail
 
 
 ## [Desktop](#desktop)
+{: #desktop}
 
 <b>nvidia-open</b> images are recommended for systems with NVIDIA GPUs Turing or newer (GTX 16XX+, RTX 20XX+). These include the new <a href="https://github.com/NVIDIA/open-gpu-kernel-modules">open kernel modules</a> from NVIDIA, not Nouveau. <b>nvidia</b> images are recommended for systems with NVIDIA GPUs Pascal or older. These include the closed kernel modules from NVIDIA.
 
 ### [Stable](#stable)
+{: #stable}
 
 #### Silverblue (GNOME)
 
@@ -67,6 +70,7 @@ This section is a relative recommendation between the desktop environments avail
 | `sericea-nvidia-open-hardened`            | Sericea   | Yes, open drivers       | No                     |
 
 ### [Experimental](#experimental)
+{: #experimental}
 
 Note that there are no ISOs available for experimental images. If you want to try out an experimental image, you can use `ujust rebase-secureblue` on an existing secureblue installation.
 
@@ -79,7 +83,9 @@ Note that there are no ISOs available for experimental images. If you want to tr
 | `cosmic-nvidia-open-hardened`             | COSMIC                | Yes, open drivers       | No                     |
 
 ## [Server](#server)
+{: #server}
 ### [CoreOS](#coreos)
+{: #coreos}
 {% include alert.html type='note' content='After you finish setting up your <a href="https://fedoraproject.org/coreos/">Fedora CoreOS</a> installation, you will need to disable <code>zincati.service</code> before rebasing to securecore.' %}
 
 | Name                                      | Base      | NVIDIA Support          | ZFS Support | ARM64 Support          |
@@ -92,6 +98,7 @@ Note that there are no ISOs available for experimental images. If you want to tr
 | `securecore-zfs-nvidia-open-hardened`     | CoreOS    | Yes, open drivers       | Yes         | No                     |
 
 ### [IoT](#iot)
+{: #iot}
 
 | Name                               | Base      | NVIDIA Support          | ZFS Support | ARM64 Support          |
 |------------------------------------|-----------|-------------------------|-------------|------------------------|

content/INDEX.md

@@ -5,13 +5,16 @@ permalink: /
 ---
 
 ## [About](#about)
+{: #about}
 
 secureblue is a security-focused desktop and server Linux operating system, developed as an open-source project. It is shipped as a set of [OCI](https://en.wikipedia.org/wiki/Open_Container_Initiative) bootable container images, which are generated with [BlueBuild](https://blue-build.org/), using [Fedora Atomic Desktop](https://fedoraproject.org/atomic-desktops/)'s [base images](https://pagure.io/workstation-ostree-config) as a starting point. Fedora is one of the few Linux distributions that ships with SELinux and associated tooling built-in and enabled by default. This makes it advantageous as a starting point for building a secure desktop system. However, the security architecture of desktop Linux is broadly and significantly lacking. The goal of secureblue is to build a maximally secure Linux operating system by proactively increasing defenses against the exploitation of both known and unknown vulnerabilities, while avoiding sacrificing usability for most use cases where possible. For more details, see the [features list](/features).
 
 ## [Who is secureblue for?](#who-is-secureblue-for)
+{: #who-is-secureblue-for}
 
 secureblue is for those whose first priority is using Linux, and second priority is security. secureblue does not claim to be the most secure option available on the desktop. We are limited in that regard by the current state of desktop Linux standardization, tooling, and upstream security development. What we aim for instead is to be the most secure option for those who already intend to use Linux. As such, if security is your first priority, secureblue may not be the best option for you.
 
 ## [Support and community](#support-and-community)
+{: #support-and-community}
 
 Both [GitHub issues](https://github.com/secureblue/secureblue/issues) and [Discord](https://discord.gg/qMTv5cKfbF) are available for support from the secureblue community.

content/articles/ARTICLES.md

@@ -10,6 +10,7 @@ The main documentation for secureblue is at the top-level of the site, accessibl
 
 Other articles on assorted topics related to secureblue:
 
-- [User Namespaces](/articles/userns) - Brief overview of unprivileged User Namespaces, the security risk they enabled and how secureblue handles that risk.
-- [Kernel Arguments](/articles/kargs) - List and brief explanation of the hardening kargs that the `ujust set-kargs-hardening` command can set.
+- [User namespaces](/articles/userns) - Brief overview of unprivileged User Namespaces, the security risk they enabled and how secureblue handles that risk.
+- [Kernel arguments](/articles/kargs) - List and brief explanation of the hardening kargs that the `ujust set-kargs-hardening` command can set.
 - [Flatpak](/articles/flatpak) - Flatpak: the good, the bad, the ugly.
+- [Build architecture](/articles/build-architecture) - Build architecture for secureblue

content/articles/BUILD_ARCHITECTURE.md

@@ -0,0 +1,145 @@
+---
+title: "Build architecture | secureblue"
+description: "Build architecture for secureblue"
+permalink: /articles/build-architecture
+---
+
+# Build architecture
+
+## [Table of Contents](#table-of-contents)
+{: #table-of-contents}
+
+- [Introduction](#introduction)
+- [Definitions](#definitions)
+- [Mitigation logic](#mitigation-logic)
+  - [Provenance](#provenance)
+  - [Signatures](#signatures)
+  - [Egress auditing](#egress-auditing)
+  - [Branch protection](#branch-protection)
+- [Build process](#build-process)
+  - [Trivalent Build](#trivalent-build)
+  - [Secureblue Build](#secureblue-build)
+  - [Image Updates](#image-updates)
+
+## [Introduction](#introduction)
+{: #introduction}
+
+Supply chain security is a priority for secureblue. During the the build process, we use complementary security mechanisms to protect against a variety of supply chain attack vectors. The documentation below covers each of these mechanisms, the protections they provide, and where secureblue uses these mechanisms.
+
+## [Definitions](#definitions)
+{: #definitions}
+
+| Security mechanism  | Implementation tooling | Attack vectors | Scope   |
+|------------|---------------------------------------|-------------------------|--------------|---------------------------------|
+| Provenance      | [SLSA](https://slsa.dev)                                   | &lt;ul&gt;&lt;li&gt;Maintainer signing key theft&lt;/li&gt;&lt;li&gt;Rogue maintainers&lt;/li&gt;&lt;/ul&gt; | • All secureblue [OCI](https://opencontainers.org/) images<br />• Trivalent RPM packages<br />• BlueBuild build tools |
+| Signatures | [cosign](https://github.com/sigstore/cosign), [GPG](https://gnupg.org/) | • Artifact tampering<br />• Artifact forgery<br />• Registry credential theft | • All secureblue OCI images<br />• All secureblue ISOs and torrents<br />• All secureblue RPM packages<br />• All Fedora RPM packages<br />• All Flatpaks from Flathub ([centrally signed](https://flathub.org/repo/flathub.gpg))<br />• BlueBuild build tools |
+| Egress auditing | [Harden-Runner](https://docs.stepsecurity.io/harden-runner) | • Maintainer secrets exfiltration<br />• Source code tampering<br />• Dependency tampering<br />• Registry credential theft | • All secureblue OCI image builds<br />• Trivalent RPM builds |
+| Branch protection | [GitHub Rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | • Maintainer source code repository credential theft<br />• Rogue maintainers | • All secureblue source code repositories |
+
+## [Mitigation logic](#mitigation-logic)
+{: #mitigation-logic}
+
+### [Provenance](#provenance)
+{: #provenance}
+
+To generate provenance, the build platform (in our case, [GitHub Actions](https://github.com/features/actions)) generates and signs an attestation file containing metadata about the build environment. Crucially, it cryptographically attests to the authenticity of runner and the source commit on which the artifact is being built. This attestation is then published in the repository or registry alongside the artifact.
+
+On the client side, when the artifact is pulled, the signature of the attestation is [validated](https://github.com/slsa-framework/slsa-verifier) against the build platform's public key and the contents of the attestation are validated to confirm that the artifact was built: on an authorized runner from a commit in a specific branch in the source repository (in our case, protected by branch policies, pull request review, and maintainer login 2FA). This means that even in the event that a maintainer's artifact signing keys and artifact repository credentials were both stolen, any malicious builds pushed by the credential thief would be rejected by clients due to provenance validation.
+
+### [Signatures](#signatures)
+{: #signatures}
+
+A private key owned by the artifact maintainer is used in combination with a [hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function) of the artifact to compute a [signature](https://en.wikipedia.org/wiki/Digital_signature). The signature is then provided alongside the artifact so that clients can verify the artifact signature before installing or using the artifact. For example, for our ISOs, each signature is shipped in a corresponding `-CHECKSUM` file.
+
+Once the client has all of the required information, it can use the maintainer's public key to verify the signature, revealing a hash that it then compares against a locally-generated hash of the artifact. This means that in the event that an artifact registry was compromised or artifacts otherwise tampered with by malicious third parties, any corresponding signature file would either not be present or fail validation.
+
+### [Egress auditing](#egress-auditing)
+{: #egress-auditing}
+
+StepSecurity [Harden-Runner](https://docs.stepsecurity.io/harden-runner) provides network traffic controls and source code integrity monitoring, among other mechanisms. It restricts outbound traffic to a configurable list of authorized outbound domains, and enforces this at multiple levels (DNS, HTTPS, network layer, transport layer). It has several other functions as well, like  monitoring the source code as the build progresses to ensure tampering doesn't occur, monitoring for anomalous privileged processes, etc.
+
+### [Branch protection](#branch-protection)
+{: #branch-protection}
+
+Branch protection via [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) prevents any changes being made to secureblue source code without those changes first meeting specific criteria. Among those criteria is a minimum number of code reviews from maintainers, excluding of course the author of the pull request should they be a maintainer. This means that in the event that a maintainer's source code repository credentials were stolen, the thief would be unable to push changes to the repository. This includes the repo owner credentials, since bypassing rulesets is only possible after 2FA has been granted.
+
+## [Build process](#build-process)
+{: #build-process}
+
+<figure>
+  <a href="/assets/architecture.png" target="_blank">
+    <img src="/assets/architecture.png" alt="Secureblue Architecture">
+  </a>
+  <figcaption>Tap or click image to open larger</figcaption>
+</figure>
+
+### [Trivalent Build](#trivalent-build)
+{: #trivalent-build}
+
+#### SRPM Build Job
+
+1. Run on a [GitHub-hosted runner](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners)
+1. Run with [StepSecurity Harden-Runner](https://docs.stepsecurity.io/harden-runner) provisioned
+1. Install the [Trivalent source cache](https://github.com/secureblue/trivalent-chromium-clean-source) package from [secureblue's COPR repos](https://copr.fedorainfracloud.org/coprs/secureblue/packages/)
+  - Validate the package's GPG signature
+1. Push built [SRPM](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/packaging_and_distributing_software/index) to GitHub Artifacts
+
+#### RPM Build Job
+
+1. Run on a GitHub-hosted runner
+1. Run on a secureblue-owned, AWS-hosted runner via [Runs-On](https://runs-on.com/)
+1. Run with StepSecurity Harden-Runner provisioned
+1. Pull SRPM from GitHub Artifacts
+1. Push built [RPM](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/packaging_and_distributing_software/index) to GitHub Artifacts
+
+#### Signing Job
+
+1. Run with StepSecurity Harden-Runner provisioned
+1. Pull RPM from GitHub Artifacts
+1. Sign and push the RPM to [secureblue's RPM repo](https://repo.secureblue.dev/secureblue.repo)
+
+#### Provenance Job
+
+1. Run on a GitHub-hosted runner
+1. Run with StepSecurity Harden-Runner provisioned
+1. Fetch hash information from the Signing Job
+1. Fetch context information from the GitHub Control Plane
+1. Generate, sign, and push the attestation to GitHub Artifacts
+
+### [Secureblue Build](#secureblue-build)
+{: #secureblue-build}
+
+#### Build Job
+
+1. Run on a GitHub-hosted runner
+1. Run with StepSecurity Harden-Runner provisioned
+1. Pull base image from [Fedora Quay](https://quay.io/organization/fedora-ostree-desktops)
+  - Validate the image's cosign signature
+1. Install packages from [Fedora's repos](https://packages.fedoraproject.org/)
+  - Validate each package's GPG signature
+1. Install packages from secureblue's COPR repos
+  - Validate each package's GPG signature
+1. From [Negativo17](https://negativo17.org/), replace certain packages that Fedora [strips of patent-encumbered codecs](https://docs.fedoraproject.org/en-US/project/#_freedom)
+  - Validate each package's GPG signature
+1. Pull the Trivalent provenance from the [Trivalent repo](https://github.com/secureblue/Trivalent)
+1. From secureblue's RPM repo, install Trivalent
+  - Validate the repo metadata signature
+  - Validate the package's GPG signature
+  - Validate the package's provenance
+1. Sign and push the completed image to [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
+  - Push the image's signature to GHCR
+
+#### Provenance Job
+
+1. Run on a GitHub-hosted runner
+1. Run with StepSecurity Harden-Runner provisioned
+1. Fetch digest information from the Build Job
+1. Fetch context information from the GitHub Control Plane
+1. Generate, sign, and push the attestation to GHCR
+
+### [Image Updates](#image-updates)
+{: #image-updates}
+
+1. Pull the new image to the client machine
+  - Validate the image signature
+  - Validate the image's provenance

content/articles/KARGS.md

@@ -1,11 +1,13 @@
 ---
-title: "kargs | secureblue"
-description: "An overview of the hardened boot kargs used in secureblue"
+title: "Kernel arguments | secureblue"
+description: "An overview of the kernel arguments used by secureblue"
 permalink: /articles/kargs
 ---
 
-# Table of contents
 
+# Kernel arguments
+
+## [Table of Contents](#table-of-contents)
 {: #table-of-contents}
 
 - [Introduction](#introduction)
@@ -15,7 +17,8 @@ permalink: /articles/kargs
   - [Force disable simultaneous multithreading](#smt)
   - [Unstable kargs](#unstable)
 
-# Introduction
+## [Introduction](#introduction)
+{: #introduction}
 
 On secureblue and other systems that use `rpm-ostree`, kernel arguments (kargs)
 can be managed using `rpm-ostree kargs`. Run `rpm-ostree kargs --help` for usage
@@ -29,7 +32,8 @@ To remove all kernel arguments that secureblue adds, you can run
 For details on what each kernel argument does, see
 [the kernel documentation](https://www.kernel.org/doc/html/v6.17/admin-guide/kernel-parameters.html).
 
-# Standard
+## [Standard](#standard)
+{: #standard}
 
 Stable kernel arguments that are set by default on a fresh secureblue
 installation, and are always applied by the script `ujust set-kargs-hardening`.
@@ -87,30 +91,28 @@ installation, and are always applied by the script `ujust set-kargs-hardening`.
 - `vsyscall=none`: Disable vsyscall as it is both obsolete and enables an ROP
   attack vector.
 
-# Additional
+## [Additional](#additional)
+{: #additional}
 
 Sets of additional kargs that can be selectively set alongside the standard
 kargs detailed above. The `set-kargs-hardening` command prompts the user on
 whether to add apply of the 3 sets of kargs detailed below:
 
-## Disable 32-bit processes and syscalls
-
+### Disable 32-bit processes and syscalls
 {: #32bit}
 
 {% include alert.html type='note' content='32-bit support is needed by some legacy software, such as Steam.' %}
 
 - `ia32_emulation=0`: Disables 32-bit processes and syscalls.
 
-## Force disable simultaneous multithreading
-
+### Force disable simultaneous multithreading
 {: #smt}
 
 - `nosmt=force`: Disables this hardware feature on user request, regardless of
   whether it is affected by known vulnerabilities. Note that this
   [halves the number of CPU cores](/faq#smt).
 
-## Unstable kargs
-
+### Unstable kargs
 {: #unstable}
 
 {% include alert.html type='caution' content='These may cause issues on some hardware.' %}

content/articles/USERNS.md

@@ -1,5 +1,5 @@
 ---
-title: "User Namespaces | secureblue"
+title: "User namespaces | secureblue"
 description: "Brief explanation of unprivileged user namespaces and how the feature is handled in secureblue"
 permalink: /articles/userns
 ---