Docs: add ci/cd general info

Signed-off-by: Jenni Nikolaenko <[email protected]>

README.md

@@ -19,13 +19,6 @@ This repository contains the source files (code and documentation) of Ghaf Frame
 
 For information on build instructions and supported hardware, see the [Reference Implementations](https://tiiuae.github.io/ghaf/ref_impl/reference_implementations.html) section of Ghaf documentation.
 
-### Other Project Repositories
-
-Other repositories that are a part of the Ghaf project:
-
-* <https://github.com/tiiuae/sbomnix>: a utility that generates SBOMs given Nix derivations or out paths
-* <https://github.com/tiiuae/ci-public>, <https://github.com/tiiuae/ci-test-automation>: CI/CD related files
-
 
 ### Documentation
 
@@ -38,6 +31,24 @@ To build Ghaf documentation, use:
 See the documentation overview under [README-docs.md](./docs/README-docs.md).
 
 
+## Other Project Repositories
+
+Other repositories that are a part of the Ghaf project:
+
+* [sbomnix](https://github.com/tiiuae/sbomnix): a utility that generates SBOMs given Nix derivations or out paths
+* [ghaf-infra](https://github.com/tiiuae/ghaf-infra), [ci-public](https://github.com/tiiuae/ci-public), [ci-test-automation](https://github.com/tiiuae/ci-test-automation): CI/CD related files
+
+
+## Build System
+
+Ghaf images are built and tested by our continuous integration system. For more information on a general process, see [Continuous Integration and Distribution](./docs/src/scs/ci-cd-system.md).
+
+Targets: <https://github.com/tiiuae/ghaf/blob/main/hydrajobs.nix>  
+Hydra builders on x86 servers: <https://hydra.vedenemo.dev/>  
+Disk images successfully built with Hydra are published to <https://vedenemo.dev/>.  
+Build results: <https://vedenemo.dev/files/build_reports/>  
+
+
 ## Contributing
 
 We welcome your contributions to code and documentation.

docs/src/SUMMARY.md

@@ -39,12 +39,12 @@
         - [NVIDIA Jetson AGX Orin: UART Passthrough](technologies/nvidia_agx_pt_uart.md)
         - [NVIDIA Jetson AGX Orin: PCIe Passthrough](technologies/nvidia_agx_pt_pcie.md)
         - [Generic x86: PCIe Passthrough on crosvm](technologies/x86_pcie_crosvm.md)
-    - [Platform Bus Virtualization - NVIDIA BPMP](technologies/nvidia_virtualization_bpmp.md)
+    - [Platform Bus Virtualization: NVIDIA BPMP](technologies/nvidia_virtualization_bpmp.md)
     - [Hypervisor Options](technologies/hypervisor_options.md)
 
 # Build System and Supply Chain
 
-- [CI/CD System]()
+- [Continuous Integration and Distribution](scs/ci-cd-system.md)
 - [Supply Chain Security](scs/scs.md)
     - [SLSA Framework](scs/slsa-framework.md)
     - [Basic Security Measures](scs/basics.md)

docs/src/appendices/glossary.md

@@ -25,7 +25,7 @@ All acronyms are abbreviations, but not all abbreviations are acronyms. ASAP tha
 * Articles (a, an, the) are common with initialisms. The indefinite article should be chosen according to the first sound—not the first letter:
     * ‘A’ is correct before initialisms beginning with a consonant sound, including a vowel pronounced as a ‘w’ or ‘y’ sound. For example: ‘a NASA launch’, but ‘NASA launches take place’.
     * When an initialism begins with a vowel sound (including silent consonants or a consonant pronounced with an initial vowel sound), ‘an’ should be used instead. For example, ‘read about an FBI raid’.
-* Acronyms not require articles except when they are used adjectivally. For example: ‘the patient was diagnosed with AIDS’, but ‘the AIDS patient’;‘the NASA launch takes place’.
+* Acronyms not require articles except when they are used adjectivally. For example: ‘the patient was diagnosed with AIDS’, but ‘the AIDS patient’; ‘the NASA launch takes place’.
 
 So, read the abbreviation aloud: it may be either an initialism or an acronym. Focus on the sounds, not on the letters: ‘_an_ unidentified flying object’ but ‘_a_ UFO’ as it pronounced “a YOO-ef-OH” (/ˌjuːɛfˈəʊ/). More examples: a EULA (“YOO-luh”), a LAN router, an XML file, an HTML page.
 
@@ -50,9 +50,14 @@ Groups of terms and abbreviations:
 
 ### Ghaf
 
-_The project code name that represents the Ghaf tree._  
+_The project code name that represents the Ghaf tree._   
 Source: <https://connectwithnature.ae/knowledge-hub/ghaf-tree>
 
+### CI/CD
+
+_Continuous Integration and Continuous Delivery is a Ghaf software development lifecycle. Continuous Integration refers to regularly integrating code changes into a shared repository, where they are automatically tested and verified. Continuous Delivery—software is released in short iterations._  
+> Currently, Continuous Deployment is not set up. Continuous Deployment—code is deployed to customers automatically.
+
 ### SSRC
 
 _Secure Systems Research Center is a global center of excellence in the development of end-to-end security and resilience for cyber-physical and autonomous systems. SSRC is a part of TII._  
@@ -72,6 +77,11 @@ Source: <https://www.tii.ae/>
 _An Architecture Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log._  
 Source: <https://adr.github.io/>
 
+### BPMP
+
+_Boot and Power Management Processor. The NVIDIA processor provides a set of hardware functions that support booting process handling and offloading the power management, clock management, and reset control tasks from the CPU._  
+Source: [NVIDIA Orin Series System-on-Chip, Technical Reference Manual, Version: 1.2, Date: 29-September-2023](https://developer.download.nvidia.com/assets/embedded/secure/jetson/agx_orin/Orin-TRM_DP10508002_v1.2p.pdf?iuc0WbcuowCBOIVqmVy-NHasaaKLPPoH_J74-C98Mnf_nPX-3LeG7pG9bUoWq28u9X2cW9dNB5bbIJwjmGcuGpdG3BErfZoaGTB0lzfWAUrpxZcO0nP9Z8SW4whsNkrGn6RFSM5_P9if4YR2RVXWLzjwoXbpzRWBvBk_De_WBM_4Erk=&t=eyJscyI6IndlYnNpdGUiLCJsc2QiOiJkZXZlbG9wZXIubnZpZGlhLmNvbS9lbWJlZGRlZC9kb3dubG9hZHMifQ==)
+
 ### BSP
 
 _A board support package is a collection of software used to boot and run the embedded system._
@@ -94,6 +104,10 @@ _embedded MultiMediaCard_
 
 _end-user license agreement_
 
+### FW
+
+_firmware_
+
 ### GALA
 
 _The Google Android Look Alike application. Mobile client application for connecting to a Cloud Android device in Secured Google Cloud Platform VMs. Users see a remotely rendered Android phone desktop on their own device screen and interact with the Cloud Android device like the real mobile device. All application processing runs in the cloud._
@@ -160,7 +174,7 @@ _Peripheral Component Interconnect Express_
 ### QEMU
 
 _A generic and open source machine emulator and virtualizer._  
-Source: <https://www.qemu.org/docs/master/about/index.html>
+Source: [QEMU’s documentation](https://www.qemu.org/docs/master/about/index.html)
 
 ### SBSA
 
@@ -182,7 +196,7 @@ _solid-state drive_
 ### TCB
 
 _Trusted computing base defines the security requirements by providing separation of users and data or resources._  
-Source: [Department of Defense trusted computer system evaluation criteria, DoD 5200.28-STD, 1985.](https://csrc.nist.gov/csrc/media/publications/conference-paper/1998/10/08/proceedings-of-the-21st-nissc-1998/documents/early-cs-papers/dod85.pdf)
+Source: [Department of Defense trusted computer system evaluation criteria, DoD 5200.28-STD, 1985](https://csrc.nist.gov/csrc/media/publications/conference-paper/1998/10/08/proceedings-of-the-21st-nissc-1998/documents/early-cs-papers/dod85.pdf)
 
 ### TLS
 
@@ -192,6 +206,11 @@ _Transport Layer Security, a security protocol._
 
 _An universal asynchronous receiver-transmitter, a hardware communication protocol._
 
+### UEFI
+
+_Unified Extensible Firmware Interface is a specifications that defines a new model for the interface between personal-computer operating systems and platform firmware._  
+Source: [Unified Extensible Firmware Interface Forum](https://uefi.org/faq)
+
 ### UI
 
 _user interface_

docs/src/release_notes/ghaf-23.12.md

@@ -50,8 +50,7 @@ Fixed bugs that were in the ghaf-23.09 release:
 
 * Chromium AppVM does not boot up on X1.
 * Shutdown or reboot of Lenovo X1 takes a lot of time (7 minutes).
-* Copy and paste text from or to Chromium AppVM does not work.
-  > NOTE: copy text from the address bar does not work.
+* Copy and paste text from or to Chromium AppVM does not work. Copy text from the address bar does not work as well.
 * Personal security keys cannot be created.
 * Cannot move the Element window by dragging with the mouse.
 
@@ -60,7 +59,7 @@ Fixed bugs that were in the ghaf-23.09 release:
 
 | Issue           | Status      | Comments                             |
 |-----------------|-------------|--------------------------------------|
-| The GALA app does not work | In Progress | Will be fixed in the next release. |
+| The GALA application does not work | In Progress | Will be fixed in the next release. |
 | Cannot log in to the Element chat with a Google account  | In Progress | Workaround for x86: create a user specifically for Element. |
 | Copying text from the browser address bar to another application does not work  | In Progress | Under investigation |
 | Windows launcher application does not work on NUC and AGX  | In Progress | Workaround: launch Windows VM from the command line. |

docs/src/scs/basics.md

@@ -5,17 +5,20 @@
 
 # Basic Security Measures
 
+
 ## Source Code / Version Control Security
 
 The source code security is based on the fact that the source code is two-person reviewed, version controlled, and the history is verified and retained indefinitely.
 
+
 ### Commit Signing
 All the commits to repositories must be GPG-signed. This can be achieved by enabling GPG commit signatures in the config:
 
 `git config --global commit.gpgsign true`
 
 For more detailed information, see the [Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits "Signing Commits on GitHub") article of the GitHub Docs.
 
+
 ### Branch Protection
 In the case of GitHub the following settings should be considered:
 
@@ -25,6 +28,7 @@ In the case of GitHub the following settings should be considered:
   + Require signed commits.
   + Deletions should be forbidden (req: immutable history).
 
+
 ## Software Signing
 
 Software signing is an important measure to validate the author and ensure that the code has not been altered on the way from the developer to the customer. Nix tooling is offering means to sign the derivations using libsodium with EdDSA, however, as the modular system is assumed, scripts need to be developed to support signing mechanisms in an absence of Nix tooling.
@@ -34,18 +38,21 @@ By default, the software image is signed only at the binary cache per request. W
   + Enabling the image signing on Hydra
   + Shared Nix Store
 
+
 ### Enabling Image Signing on Hydra
 
 Enabling the image signing on Hydra requires some extra work due to the lack of well-documented support of image signing at Hydra at the time of writing this document. As already mentioned, NixOS is using libsodium-based EdDSA solution for image signing. So similar scripts can be implemented. For example, in Python by using existing libsodium bindings, such as PyNaCl.
 
 ![Enabling Image Signing on Hydra](../img/threat_processing_2serv.drawio.png "Enabling The Image Signing On Hydra")
 
+
 ### Shared Nix Store
 
 The shared NixStore option is rather straightforward if Hydra is combined with the binary cache. This kind of setup is lacking the extra transition path. Thus the packages signed by the binary cache will be served straight from the Hydra NixStore.
 
 ![Shared NixStore Solution](../img/threat_processing_1serv.drawio.png "Shared NixStore")
 
+
 ## Data Encryption in Transit
 
 All the data should be transported over secure encrypted channels. Since all the transportation is done over TCP/IP protocol stack, it is possible to use native solutions like TLS to secure the traffic between the nodes. Version 1.2 is a minimum requirement.

docs/src/scs/ci-cd-system.md

@@ -0,0 +1,40 @@
+<!--
+    Copyright 2022-2024 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Continuous Integration and Distribution
+
+Ghaf Framework uses a CI/CD (Continuous Integration and Continuous Delivery) approach that aims to automate the process of building, testing, and deploying software.
+
+Our goal is to have the ability to deploy code quickly and safely: once a build is deployed, the next build undergoes testing, while the latest build is being coded.
+
+> Currently, Continuous Deployment is not set up.
+
+
+## General Process
+
+![CI/CD Architecture](../img/CICD_general.drawio.png "Ghaf CI/CD Architecture")
+
+The software delivery pipeline consists of several stages:
+
+1. Contributors make changes in the code and create a pull/merge request to merge changes from one personal fork or branch into the upstream repository/branch.
+
+2. Builder Controller checks source code repositories for changes and fetches them.
+
+3. Builder Controller arranges builds on Remote Builders to make disk images and other release artifacts.
+
+4. After the building is done, Remote Builder sends disk images to Builder Controller to create provenance files and sign disk images and provenance files.
+
+5. On build failure, Builder Controller sends failure notifications to Message Service.
+
+6. Builder Controller uploads all build artifacts to Binary Cache and disk images to Web Server.
+
+7. Test Automation fetches disk images from Binary Cache and runs the hardware test on them.
+
+8. Test Automation uploads test reports to Web Server.
+
+9.  Users can download images from Web Server:
+
+    * release images <https://vedenemo.dev/files/releases/>
+    * images for testing <https://vedenemo.dev/files/build_reports/>.

docs/src/scs/ghaf-security-fix-automation.md

@@ -9,6 +9,7 @@ The Nix community is able to identify and fix security issues relatively quickly
 
 Indeed, Ghaf should not solely rely on the community to provide security fixes but take action to understand the vulnerabilities that impact Ghaf and take an active role in fixing such issues.
 
+
 ## Semi-Automated Upstream-First Process
 
 The following image captures the high-level process we propose to identify and remediate the security vulnerabilities that impact Ghaf:

docs/src/scs/patching-automation.md

@@ -18,8 +18,10 @@ The patch management automation (PMA) system processes data in cycles. Every cyc
   6. A package passing the testing will be presented to the concerned developers for review and approval. The SBOM, scan and test results along with the package are published to a web server. The developer downloads the artifacts for review and approval.
   7. All approved artifacts become release candidates and can be found on the web server.
 
+
 ## Implementation
 
+
 ### Dependency Tracking
 
 The dependency tracking solution is based on Package URL (PURL), natively supported by ClyconeDX. PURL is a URL, composed of seven components:
@@ -36,6 +38,7 @@ The dependency tracking solution is based on Package URL (PURL), natively suppor
 
 In addition to PURL, each component should contain at least one hash value, computed from cryptographic hash functions. The hash values help to verify the original package integrity and source prior to update the download. Thus minimizing security risks during the process.
 
+
 ### Package Update
 
 The update mechanism implementation depends on a system and will differ from one build system to another.

docs/src/scs/pki.md

@@ -12,7 +12,8 @@ The PKI of SCS should consist of:
   + Registration authority (RA) for requesting entity identity verification.
   + Central directory for the secure storage of the keys.
   + Certificate Management System (CMS) for managing access to stored certificates.
-
+
+
 ## Private Certificate Authority (PCA)
 
 PCA enables the creation of private certificate authority hierarchies, consisting of Root and Subordinate CAs. It issues end-entity X.509 certificates, that are used for: 
@@ -22,6 +23,7 @@ PCA enables the creation of private certificate authority hierarchies, consistin
 
 PCA can be established in the cloud or on-premises. Initially, the OpenSSL-based solution deployed on-premises is assumed, however, some of the target projects might consider using commercial cloud solutions. 
 
+
 ## Hardware Security Module
 
 On-premises solution can be further improved by adding a Hardware Security Module (HSM). It is a physical device for managing cryptographic material such as digital keys. 
@@ -30,6 +32,7 @@ HSM can be also used to perform cryptographic operations such as digital signing
 
 One example of affordable HSM solutions is YubiHSM developed by Yubico.
 
+
 ### HSM Variants for Consideration
 
 The following HSM solutions are considered for the Ghaf project:
@@ -63,6 +66,7 @@ The main benefit of YubiHSM2 from SCS perspective is its native support of EdDSA
 
 BreadboardHSM solution is based on Microchip ATECC608B (TrustFLEX + cryptoauthlib + gtutls), though development work is still ongoing at the time of writing this document. The SoftHSMv2 and BreadboardHSM are taken for comparison showing what can be achieved using FOSS variants. 
 
+
 ## CA Hierarchy Options
 
 CA usually consists of:
@@ -75,6 +79,7 @@ In a two-tier hierarchy, the Root CA and issuing (Subordinate) CAs are separated
 
 In a three-tier CA, an intermediate CA is placed between the Root CA and the Subordinate (issuing) CA. This is done to separate the Root CA from low-level CA operations. The middle layer (intermediate CA) is only used to sign Subordinate CAs that issue the end-entity certificates. 
 
+
 ## Proposed CA Hierarchy
 
 The following diagram describes the proposed CA for the SCS. The three-tier CA is chosen based on the high-security level and the potential need to scale it to several projects, later on, keeping the main control under the same Root CA.

docs/src/scs/slsa-framework.md

@@ -7,6 +7,7 @@
 
 Supply chain Levels for Software Artifacts (SLSA) is a security framework for tampering prevention, integrity improvement, and securing packages and infrastructure of a project. For more information about the SLSA framework, see the offical website <https://slsa.dev>.
 
+
 ## SLSA Terminology
 
 **Immutable reference:** An identifier, guaranteed to always point to the same, immutable artifact.
@@ -15,6 +16,7 @@ Supply chain Levels for Software Artifacts (SLSA) is a security framework for ta
 
 **Revision:** An immutable, coherent state of a source.
 
+
 ## Levels of Assurance
 
 One of the requirements for the solution is to reach SLSA Level 4 and even go beyond that. This requires a lot of process changes as well as technical work. 
@@ -33,6 +35,7 @@ The SLSA model consists of 4 levels, offering an incremental level of anti-tampe
 
 SLSA level is not transitive, thus level of the artifact is not dependent on the level of dependencies, which are expected to have their own SLSA levels. This makes it possible to build a Level 4 artifact from Level 0 dependencies. 
 
+
 ## Requirements
 
 | Requirements | Level 1 | Level 2 | Level 3 | Level 4 |