From d6b602568769e1073555edaadbd734cfc025974f Mon Sep 17 00:00:00 2001 From: Jenni Nikolaenko Date: Fri, 14 Jun 2024 16:58:41 +0300 Subject: [PATCH] Docs: proofread PR 422 Signed-off-by: Jenni Nikolaenko --- docs/src/appendices/glossary.md | 11 +++++++ docs/src/architecture/adr.md | 6 ++-- docs/src/architecture/adr/idsvm.md | 35 ++++++++++----------- docs/src/architecture/adr/minimal-host.md | 4 +-- docs/src/architecture/adr/netvm.md | 35 ++++++++++++--------- docs/src/architecture/adr/template.md | 13 ++++---- docs/src/architecture/variants.md | 8 ++--- docs/src/features/features.md | 26 +++++++-------- docs/src/ref_impl/creating_appvm.md | 31 ++++++++---------- docs/src/ref_impl/example_project.md | 8 ++--- docs/src/ref_impl/idsvm-development.md | 30 +++++++++--------- docs/src/ref_impl/labwc.md | 2 +- docs/src/ref_impl/systemd-service-config.md | 15 +++++++-- docs/src/release_notes/ghaf-23.09.md | 6 ++-- docs/src/release_notes/ghaf-23.12.md | 4 +-- docs/style_guide.md | 10 ++++-- 16 files changed, 136 insertions(+), 108 deletions(-) diff --git a/docs/src/appendices/glossary.md b/docs/src/appendices/glossary.md index a50fd266d..f79cce444 100644 --- a/docs/src/appendices/glossary.md +++ b/docs/src/appendices/glossary.md @@ -86,6 +86,10 @@ Source: [NVIDIA Orin Series System-on-Chip, Technical Reference Manual, Version: _A board support package is a collection of software used to boot and run the embedded system._ +### CA + +_A certificate authority or certification authority is an entity that stores, signs, issues digital certificates, and bind them to cryptographic keys._ + ### DHCP _The Dynamic Host Configuration Protocol is a network protocol that automatically sets IP addresses and other attributes to enable information transfer between network nodes._ @@ -194,6 +198,10 @@ _A stock keeping unit, is a unique code used by sellers to identify and track pr _A system on chip, a microchip that contains the necessary electronic circuits for a fully functional system on a single integrated circuit (IC)._ +### SPKI + +_simple public-key infrastructure_ + ### SSD _solid-state drive_ @@ -301,3 +309,6 @@ Source: _Supply chain Levels for Software Artifacts is a security framework, a check-list of standards and controls to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises._ Source: + +[Back to Top ⏫](./glossary.md#glossary) +--- diff --git a/docs/src/architecture/adr.md b/docs/src/architecture/adr.md index c3b000d20..559ac7bbf 100644 --- a/docs/src/architecture/adr.md +++ b/docs/src/architecture/adr.md @@ -12,9 +12,9 @@ The Ghaf platform decision log: | Decision Record | Status | | -------- | ----------- | | [Minimal Host](../architecture/adr/minimal-host.md) | Proposed. | -| [netvm—Networking Virtual Machine](../architecture/adr/netvm.md) | Proposed, partially implemented for development and testing. | -| [idsvm—Intrusion Detection System Virtual Machine](../architecture/adr/idsvm.md) | Proposed, partially implemented for development and testing. | -| [Platform Bus for RustVMM](../architecture/adr/platform-bus-passthrough-support.md) | Proposed, WIP. | +| [Networking VM](../architecture/adr/netvm.md) | Proposed, partially implemented for development and testing. | +| [IDS VM](../architecture/adr/idsvm.md) | Proposed, partially implemented for development and testing. | +| [Platform Bus for Rust VMM](../architecture/adr/platform-bus-passthrough-support.md) | Proposed, WIP. | To create an architectural decision proposal, open [a pull request](https://github.com/tiiuae/ghaf/blob/main/CONTRIBUTING.md#contributing-documentation) and use the [decision record template](https://github.com/tiiuae/ghaf/blob/main/docs/src/architecture/adr/template.md). Contributions to the Ghaf architecture decisions are welcome. diff --git a/docs/src/architecture/adr/idsvm.md b/docs/src/architecture/adr/idsvm.md index 39b761cb7..769b7978f 100644 --- a/docs/src/architecture/adr/idsvm.md +++ b/docs/src/architecture/adr/idsvm.md @@ -3,38 +3,35 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> -# idsvm-Itrusion Detection System Virtual Machine +# Intrusion Detection System Virtual Machine + ## Status Proposed, partially implemented for development and testing. -*idsvm* reference declaration will be available at [microvm/idsvm.nix] -(https://github.com/tiiuae/ghaf/blob/main/modules/virtualization/microvm/idsvm.nix) +Intrusion Detection VM (IDS VM) reference declaration will be available at [microvm/idsvm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/idsvm/idsvm.nix). + ## Context -Ghaf high-level design target is to secure a monolithic OS by modularizing -the OS to networked VMs. The key security target is to detect intrusions by -analyzing the network traffic in the internal network of the OS. +Ghaf's high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to detect intrusions by analyzing the network traffic in the internal network of the OS. + ## Decision -The main goal is to have networking entity in Ghaf internal network so that -all network traffic goes via that entity. Traffic then can be analysed to -detect possible intrusions in inter VM communication and outgoing network -traffic (from VM to internet). This goal is achieved itroducing a dedicated -virtual machine and route all networking from other virtual machines to go -through it. Then it is possible to use various IDS software solutions in -idsvm to detect possible suspicious network activities. +The main goal is to have a networking entity in Ghaf's internal network so that all network traffic goes through that entity. Traffic then can be analyzed to detect possible intrusions in inter VM communication and outgoing network traffic (from VM to the Internet). This goal is achieved by introducing a dedicated VM and routing all networking from other VMs to go through it. Then it is possible to use various IDS software solutions in IDS VM to detect possible suspicious network activities. + +![Scope!](../../img/idsvm.drawio.png "IDS VM Solution") -![Scope!](../../img/idsvm.drawio.png "idsvm Solution") ## Consequences -A dedicated idsvm provides a single checkpoint to detect intrusions -and anomalies in the internal network of the OS and to initiate required -countermeasures. +A dedicated IDS VM provides a single checkpoint to detect intrusions and anomalies in the internal network of the OS and to initiate required countermeasures. + +Routing and analyzing the network traffic in a separate VM will reduce network performance. + + +## References -Routing and analysing the network traffic in separate VM will reduce network -performance. +[IDS VM Further Development](/docs/src/ref_impl/idsvm-development.md) diff --git a/docs/src/architecture/adr/minimal-host.md b/docs/src/architecture/adr/minimal-host.md index d5645b5ec..eba393962 100644 --- a/docs/src/architecture/adr/minimal-host.md +++ b/docs/src/architecture/adr/minimal-host.md @@ -85,8 +85,8 @@ No networking may have impact on how the guest-to-guest inter virtual machine co ### No graphics (MH04) -Ghaf minimal host profile for release target has no graphics. Graphics will be compartmentalized to GUIVM. -All graphics and display output related components and dependencies, including kernel drivers, must be removed from kernel configuration. Those are to be passed through to GUIVM. +Ghaf minimal host profile for release target has no graphics. Graphics will be compartmentalized to GUI VM. +All graphics and display output related components and dependencies, including kernel drivers, must be removed from kernel configuration. Those are to be passed through to GUI VM. ### No getty (MH05) diff --git a/docs/src/architecture/adr/netvm.md b/docs/src/architecture/adr/netvm.md index fecc29959..573f5e0a6 100644 --- a/docs/src/architecture/adr/netvm.md +++ b/docs/src/architecture/adr/netvm.md @@ -3,45 +3,50 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> -# netvm—Networking Virtual Machine +# Networking Virtual Machine + ## Status Proposed, partially implemented for development and testing. -*netvm* reference declaration is available at [netvm/default.nix](https://github.com/tiiuae/ghaf/blob/main/microvmConfigurations/netvm/default.nix). +Networking VM (Net VM) reference declaration is available at [microvm/netvm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/netvm.nix). + ## Context -Ghaf high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to not expose the trusted host directly to the Internet. This isolates the attack surface from the Internet to *netvm*. +Ghaf's high-level design target is to secure a monolithic OS by modularizing the OS to networked VMs. The key security target is to not expose the trusted host directly to the Internet. This isolates the attack surface from the Internet to Net VM. The following context diagram illustrates development and secure scenarios: -![Scope!](../../img/netvm.drawio.png "netvm Context") +![Scope!](../../img/netvm.drawio.png "Net VM Context") **Left**: An insecure development scenario. The host is directly connected to the Internet, and the network is bridged from the host to other parts of the system. -**Right**: A secure scenario. The network is passed through to *netvm* and routed to other parts of the system. +**Right**: A secure scenario. The network is passed through to Net VM and routed to other parts of the system. + ## Decision -The development scenario simplifies the target system network access and configuration. This ADR proposes the development *netvm* configuration is maintained to support system development. +The development scenario simplifies the target system network access and configuration. This ADR proposes the development Net VM configuration is maintained to support system development. -The secure scenario is proposed to be implemented with the use of passthrough to DMA and remap the host physical network interface card (PHY NIC) to *netvm*. This cannot be generalized for all hardware targets as it requires: -- Low-level device tree configuration for bootloader and host (at least on platform NIC). -- VMM host user space NIC bus mapping from the host to *netvm*. -- Native network interface driver (not virtual) in *netvm*. Native driver is bound the vendor BSP supported kernel version. +The secure scenario is proposed to be implemented with the use of passthrough to DMA and remap the host physical network interface card (PHY NIC) to Net VM. This cannot be generalized for all hardware targets as it requires: + +* Low-level device tree configuration for bootloader and host (at least on platform NIC). +* VMM host user space NIC bus mapping from the host to Net VM. +* Native network interface driver (not virtual) in Net VM. Native driver is bound the vendor BSP supported kernel version. These depend on the hardware setup. The proposed target setup is that the passthrough network device(s) are implemented as declarative nix-modules for easier user hardware-specific configuration. In practice, a user may configure the declaration of a PCI or USB network card that is available to the available hardware setup. -*netvm* will provide: -- dynamic network configuration: - - A DHCP server for *netvm* to provide IP addresses for the other parts of the system, both static and dynamic. - - Routing from *netvm* to the Internet and/or inter VM. +Net VM will provide a dynamic network configuration: + +* A DHCP server for Net VM to provide IP addresses for the other parts of the system, both static and dynamic. +* Routing from Net VM to the Internet and/or Inter VM. For common reference hardware with platform NIC, the configured modules for network interface passthrough are provided. For more information, see [i.MX 8QM Ethernet Passthrough](https://tiiuae.github.io/ghaf/research/passthrough/ethernet.html). -Details of other network components, such as default firewall rules, DHCP (static and dynamic client addresses), routing, reverse proxies and security monitoring are to be described in their respective architecture decision records. In this context, these are illustrated in the context diagram on the right side of the *netvm* network interface driver. +Details of other network components, such as default firewall rules, DHCP (static and dynamic client addresses), routing, reverse proxies and security monitoring are to be described in their respective architecture decision records. In this context, these are illustrated in the context diagram on the right side of the Net VM network interface driver. + ## Consequences diff --git a/docs/src/architecture/adr/template.md b/docs/src/architecture/adr/template.md index a53fd0207..0630d1e09 100644 --- a/docs/src/architecture/adr/template.md +++ b/docs/src/architecture/adr/template.md @@ -3,19 +3,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> -# Decision record template - +# Decision Record Template -This is the template for managing the ADR files. - -In each ADR file, write these sections: +This is the template[^note1] for managing the ADR files. Use the following sections in each ADR file: # Title + ## Status -What is the status: proposed, accepted, rejected, deprecated, superseded, etc.? +What is the status? *Proposed*, *Accepted*, *Rejected*, *Deprecated*, *Superseded*, etc. ## Context @@ -31,3 +29,6 @@ What is the change that we are proposing and/or doing? ## Consequences What becomes easier or more difficult to do because of this change? + + +[^note1]: This template is based on a [template by Michael Nygard](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-michael-nygard). For more suggestions on writing good ADRs, see the [Architecture decision record (ADR)](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main?tab=readme-ov-file#suggestions-for-writing-good-adrs) public repository. diff --git a/docs/src/architecture/variants.md b/docs/src/architecture/variants.md index 3b9e50146..e3c44b0e6 100644 --- a/docs/src/architecture/variants.md +++ b/docs/src/architecture/variants.md @@ -8,10 +8,10 @@ The main scope of the Ghaf platform is edge virtualization. However, to support modular development and testing of the platform, variants are supported with the following definitions: * `Default` - A default variant. Supports [minimal host](./adr/minimal-host.md), GUI VM[^note] and [netvm](./adr/netvm.md). May host other VMs. For more information, see [Stack](./stack.md). + A default variant. Supports [minimal host](./adr/minimal-host.md), GUI VM[^note1] and [netvm](./adr/netvm.md). May host other VMs. For more information, see [Stack](./stack.md). * `Headless` - A variant with [minimal host](./adr/minimal-host.md) and [netvm](./adr/netvm.md). May host other VMs but does not have GUI VM or graphics stack on a host. + A variant with [minimal host](./adr/minimal-host.md) and [netvm](./adr/netvm.md). May host other VMs but does not have a GUI VM or graphics stack on a host. * `Host only` A variant with [minimal host](./adr/minimal-host.md) *only*. A user can manually install software to a host, including VMs (if supported by hardware). @@ -22,9 +22,9 @@ The main scope of the Ghaf platform is edge virtualization. However, to support | Variant Name | Headless | Graphics | VMs | Devices | |--- |--- |--- | --- | --- | -| `Default` | No | GUI VM [^note] | Supported | Jetson, generic x86 | +| `Default` | No | GUI VM | Supported | Jetson, generic x86 | | `Headless` | Yes | No | Supported | Jetson, generic x86 | | `Host Only` | Yes | No | May be supported but not included | Jetson, generic x86 | | `No Virtualization`| Yes or no | Native on host | Not supported | Raspberry Pi, RISC-V | -[^note] As of early 2023, the graphics stack is deployed on a host to support application development. Work is ongoing to define the GUI VM and isolate graphics with GPU passthrough. +[^note1]: As of early 2023, the graphics stack is deployed on a host to support application development. Work is ongoing to define the GUI VM and isolate graphics with GPU passthrough. diff --git a/docs/src/features/features.md b/docs/src/features/features.md index ebceaf059..1a01b645c 100644 --- a/docs/src/features/features.md +++ b/docs/src/features/features.md @@ -26,7 +26,7 @@ Ghaf demo desktop and applications are illustrated in the screen capture below: - `aarch64`—generic AArch64; tested on an ARM server, laptop (e.g. Apple MacBook's), or NVIDIA Jetson AGX Orin. - `All variants`—supported devices from [Architectural Variants](https://tiiuae.github.io/ghaf/architecture/variants.html). -The following tables show the status of Ghaf Platform features: +The following tables show the status of the Ghaf Platform features: ## Release Builds and Hardware Architecture Support @@ -53,25 +53,25 @@ The following tables show the status of Ghaf Platform features: | root filesystem flashing | ✅ | `x86, imx8mp` | `dd` image to bootable media - [see](https://tiiuae.github.io/ghaf/ref_impl/build_and_run.html#running-ghaf-image-for-x86-computer) | | Debug: SSH | ✅ | `Orin`, `x86` | Host access only in `-debug`-target, see [authentication.nix](https://github.com/tiiuae/ghaf/blob/main/modules/development/authentication.nix) | | Debug: Serial | ✅ | `all` | Host access only in `-debug`-target - e.g. `screen /dev/ttyACM0 115200` | -| Compartmentalized environment | 🚧 | `Lenovo X1` | NetVM, GUI VM (with GPU passthrough) plus some Application VMs | +| Compartmentalized environment | 🚧 | `Lenovo X1` | Net VM, GUI VM (with GPU passthrough) plus some App VMs | ## Target Architecture | Feature | Status | Reference Device | Details | |-------------------|-------------|------------------|----------------------------------------------| -| `minimal host` | 🚧 | [`all`](https://tiiuae.github.io/ghaf/architecture/variants.html) | See [Minimal Host](https://tiiuae.github.io/ghaf/architecture/adr/minimal-host.html) and [PR #140](https://github.com/tiiuae/ghaf/pull/140). | -| `netvm` | ✅ | `Orin` | See [netvm](https://tiiuae.github.io/ghaf/architecture/adr/netvm.html). Passthrough with Wifi works but requires SSID/password configuration | -| `idsvm` | ✅ | `Orin` | [Defensive security VM placeholder PR open](https://github.com/tiiuae/ghaf/pull/146) | -| `guivm` | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device, other devices have Wayland compositor running on the host.| -| `appvm` | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device: chromium, GALA and zathura VMs. Requires `guivm` in place | -| `adminvm` | ✅ | `All` | Not started | -| Inter VM comms - IP-based | 🚧 | `All` |`-debug`-targets have network bridges to access VMs from host | +| Minimal host | 🚧 | [`all`](https://tiiuae.github.io/ghaf/architecture/variants.html) | See [Minimal Host](https://tiiuae.github.io/ghaf/architecture/adr/minimal-host.html) and [PR #140](https://github.com/tiiuae/ghaf/pull/140). | +| Net VM | ✅ | `Orin` | See [Net VM](https://tiiuae.github.io/ghaf/architecture/adr/netvm.html). Passthrough with Wi-Fi works but requires SSID/password configuration. | +| IDS VM | ✅ | `Orin`, `Lenovo X1` | [Defensive networking mechanism](/docs/src/architecture/adr/idsvm.md). | +| GUI VM | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device, other devices have Wayland compositor running on the host.| +| App VM | 🚧 | `All`, `Lenovo X1`| Implemented for Lenovo X1 reference device: Chromium, GALA and Zathura VMs. Requires GUI VM in place. | +| Admin VM | ✅ | `All` | Not started | +| Inter VM comms - IP-based | 🚧 | `All` |`-debug`-targets have network bridges to access VMs from host. | | Inter VM comms - shared memory | 🚧 | `All` | | -| Inter VM Wayland | 🚧 | `All` | Currently it is `waypipe` over SSH, for test and demo purpose only | -| SW update | 🚧 | `All` | A/B update tooling being evaluated | -| USB passthrough | 🚧 | `Orin` | No reference implementation integrated yet | -| PCI passthrough | ✅ | `All` | Used for reference in `netvm` on `Orin` | +| Inter VM Wayland | 🚧 | `All` | Currently it is `waypipe` over SSH, for test and demo purpose only. | +| SW update | 🚧 | `All` | A/B update tooling being evaluated. | +| USB passthrough | 🚧 | `Orin` | No reference implementation integrated yet. | +| PCI passthrough | ✅ | `All` | Used for reference in Net VM on `Orin`. | | UART passthrough | 🚧 | `Orin` | See [NVIDIA Jetson AGX Orin: UART Passthrough](https://tiiuae.github.io/ghaf/build_config/passthrough/nvidia_agx_pt_uart.html). Not integrated to any VM. | | ARM platform bus devices passthrough | 🚧 | `Orin` | NVIDIA BPMP virtualization being developed | diff --git a/docs/src/ref_impl/creating_appvm.md b/docs/src/ref_impl/creating_appvm.md index e394a7fea..61e975219 100644 --- a/docs/src/ref_impl/creating_appvm.md +++ b/docs/src/ref_impl/creating_appvm.md @@ -5,23 +5,19 @@ # Creating Application VM -Application VM (AppVM) is a VM that improves trust in system components by isolating applications from the host OS and other applications. Virtualization with hardware-backed mechanisms provides better resource protection than traditional OS. This lets users use applications of different trust levels within the same system without compromising system security. While the VMs have overhead, it is acceptable as a result of improved security and usability that makes the application seem like it is running inside an ordinary OS. +Application VM (App VM) is a VM that improves trust in system components by isolating applications from the host OS and other applications. Virtualization with hardware-backed mechanisms provides better resource protection than traditional OS. This lets users use applications of different trust levels within the same system without compromising system security. While the VMs have overhead, it is acceptable as a result of improved security and usability that makes the application seem like it is running inside an ordinary OS. -As a result, both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own AppVMs. +As a result, both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own AppVM. -To create an AppVM: -1. Add AppVM description. -2. Add an app launcher in GUI VM. +To create an App VM: +1. Add the VM description. +2. Add an application launcher in GUI VM. -## Adding AppVM Description +## Adding App VM Description -Add the VM description in the target configuration. - -[lenovo-x1-carbon.nix](https://github.com/tiiuae/ghaf/blob/main/targets/lenovo-x1-carbon.nix) already has AppVMs inside for Chromium, Gala, and Zathura applications. - - -#### AppVMs Example +Add the VM description in the target configuration. +[lenovo-x1-carbon.nix](https://github.com/tiiuae/ghaf/blob/main/targets/lenovo-x1-carbon.nix) already has chromium-vm, gala-vm, and zathura-vm. ``` vms = with pkgs; [ @@ -51,10 +47,9 @@ vms = with pkgs; [ Each VM has the following properties: - | **Property** | **Type** | **Unique** | **Description** | **Example** | | -------------- | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------- | -| name | str | yes | This name is postfixed with `-vm` and will be shown in microvm list. The name - e.g. `chromium-vm` will be also the VM hostname. The lenght of the name must be 8 characters or less. | “chromium” | +| name | str | yes | This name is postfixed with `-vm` and will be shown in microvm list. The name, for example, `chromium-vm` will be also the VM hostname. The length of the name must be 8 characters or less. | “chromium” | | packages | list of types.package | no | Packages to include in a VM. It is possible to make it empty or add several packages. | [chromium top] | | macAddress | str | yes | Needed for network configuration. | "02:00:00:03:03:05" | | ramMb | int, [1, …, host memory] | no | Memory in MB. | 3072 | @@ -63,11 +58,11 @@ Each VM has the following properties: ## Adding Application Launcher in GUI VM -To add an application launcher, add an element in the [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/virtualization/microvm/guivm.nix) file to the **graphics.weston.launchers** list. +To add an application launcher, add an element in the [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/guivm.nix) file to the **graphics.weston.launchers** list. A launcher element has two properties: -* **path**–path to the executable you want to run, like a graphical application; -* **icon**–path to an icon to show. +* **path**: path to the executable you want to run, like a graphical application; +* **icon**: path to an icon to show. -Check the example launchers at [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/virtualization/microvm/guivm.nix). +Check the example launchers at [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/guivm.nix). diff --git a/docs/src/ref_impl/example_project.md b/docs/src/ref_impl/example_project.md index ab90a47e6..16ac28132 100644 --- a/docs/src/ref_impl/example_project.md +++ b/docs/src/ref_impl/example_project.md @@ -11,7 +11,7 @@ The best way to do the Ghaf customization is by using Ghaf templates: 1. Create a template project as described in the [Ghaf as Library](../ref_impl/ghaf-based-project.md) section. 2. Adjust your system configuration in accordance with your HW specification. Determine all VIDs and PIDs of the devices that are passed to the VMs. -3. Add GUIVM configuration, NetworkVM configuration, and optionally some AppVMs. +3. Add GUI VM configuration, NetworkVM configuration, and optionally some AppVMs. 4. Set up Weston panel shortcuts. You can refer to the existing [project example for Lenovo T14 and Lenovo X1 laptops](https://github.com/unbel13ver/ghaf-lib). @@ -49,10 +49,10 @@ If after booting you see a black screen, try the following to detect the issue: 3. Identify an IP address by a MAC address with the `arp` command. If a MAC address is unknown, you can boot into the NixOS image or any other OS to find it, or try the latest addresses that `arp` returns. 4. Connect using SSH (login/password ghaf/ghaf). Then connect from netvm to the host using `ssh 192.168.101.2` (login/password ghaf/ghaf). 5. Check running VMs with `microvm -l`. -6. Check a GUIVM log using `journalctl -u microvm@guivm`. -7. If GUIVM does not start, you can try to start it manually with `/var/lib/microvms/guivm/current/bin/microvm-run`. +6. Check a GUI VM log using `journalctl -u microvm@guivm`. +7. If GUI VM does not start, you can try to start it manually with `/var/lib/microvms/guivm/current/bin/microvm-run`. -In case when GUIVM did not start with the error message that the device /dev/mouse or /dev/touchpad was not found, it means that the model of the touchpad in the laptop is different since it was bought in another country and has a different SKU (stock keeping unit). To add support for a new touchpad, do the following: +In case when GUI VM did not start with the error message that the device /dev/mouse or /dev/touchpad was not found, it means that the model of the touchpad in the laptop is different since it was bought in another country and has a different SKU (stock keeping unit). To add support for a new touchpad, do the following: 1. On the ghaf host, check the devices in `/dev/input/by-path` that contain “-event-” in the name. Use the command like `udevadm info -q all -a /dev/input/by-path/pci-0000:00:15.0-platform-i2c_designware.0-event-mouse | grep name` for the name of each of these devices. diff --git a/docs/src/ref_impl/idsvm-development.md b/docs/src/ref_impl/idsvm-development.md index 27695d68a..786818d0c 100644 --- a/docs/src/ref_impl/idsvm-development.md +++ b/docs/src/ref_impl/idsvm-development.md @@ -3,32 +3,34 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> -# idsvm Further Development +# IDS VM Further Development + ## Implementation -The idsvm is implemented as a regular microVM with static IP. -The mitmproxy is included to demonstrative interactive proxy to enable analysis of TLS protected data on the fly. Also Snort network intrusion detection and prevention system package is included, but no dedicated UI nor proper utilization is provided. +The [IDS VM](/docs/src/architecture/adr/idsvm.md) is implemented as a regular Micro VM with static IP. + +The [mitmproxy](https://mitmproxy.org/) is included in the demonstrative interactive proxy to enable analysis of TLS-protected data on the fly. Also, [Snort](https://snort.org/) network intrusion detection and prevention system package is included but no dedicated UI nor proper utilization is provided. + +Enforcing network traffic to go through IDS VM is crucial to the IDS VM functionality. It is achieved by setting the IDS VM to be the gateway of other VMs in [dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html) configuration of Net VM. There is a risk that one could change the gateway settings of the VM to bypass the IDS VM. This however requires root (sudo) rights and it is assumed here that these rights are enabled only in the debug build. -Enforcing network traffic to go through idsvm is crucial part of the idsvm functionality. -It is achieved by setting the idsvm to be the gateway of other VMs in dnsmasq configuration -of netvm. There is a risk is that one could change gateway settings of the VM to bypass the idsvm. This however requires root (sudo) rights and it is assumed here that these rights are enabled only in debug build. ## mitmproxy -"The mitmproxy is a free and open source interactive HTTPS proxy. It is your swiss-army knife for debugging, testing, privacy measurements, and penetration testing. It can be used to intercept, inspect, modify and replay web traffic such as HTTP/1, HTTP/2, WebSockets, or any other SSL/TLS-protected protocols." -https://mitmproxy.org/ +[**mitmproxy**](https://mitmproxy.org/) is a free and open-source interactive HTTPS proxy. It is your Swiss Army Knife for debugging, testing, privacy measurements, and penetration testing. It can be used to intercept, inspect, modify and replay web traffic such as HTTP/1, HTTP/2, WebSockets, or any other SSL/TLS-protected protocols. -In idsvm we use mitmweb tool to demonstrate mitmproxy's capabilities. It provides web-based user interface that allows interactive examination and modification of HTTP(s) traffic. -Mitmproxy package also includes console tool that provides basically same functionalities in text-based interface and it also includes a command-line tool mitmdump to view, record, and programmatically transform HTTP(s) traffic. +In IDS VM, we use **mitmweb**[^note1] tool to demonstrate mitmproxy's capabilities. It provides a web-based user interface that allows interactive examination and modification of HTTP(s) traffic. The mtmproxy package also includes a console tool that provides the same functionalities in a text-based interface and a command-line tool **mitmdump** to view, record, and programmatically transform HTTP(s) traffic. + +The mitmweb tool is run in *ids-vm* as a systemd service. It starts automatically when *ids-vm* boots up. The UI it provides is accessible at , so it is available from *ids-vm* only. However, with SSH port forwarding it is possible to access the UI from other VMs. To that purpose, GUI VM has a script *mitmweb-ui* that creates an SSH tunnel between *ids-vm* and *chromium-vm*, launches Chromium, and connects to the UI address. -Mitmweb tool is run in idsvm as a systemd service. It starts automatically when idsvm boots up. -The UI it provides is accessible in the web address http://localhost:8081 so basically it is available from idsvm only. However using SSH portforwarfing it is possible to access the UI from other VMs. To that purpose the guivm has a script called mitmweb-ui. It creates a SSH tunnel between idsvm and chromium-vm, launches the Chromium and connects to the UI-address. ## Certificates -Mitmproxy can decrypt encrypted traffic on the fly, as long as the client trusts mitmproxy's built-in certificate authority (CA). CA certificates are in hardcoded to the idsvm implementation which means they are same for all idsvm instances. In release version these should be randomly generated and stored securely. +mitmproxy can decrypt encrypted traffic on the fly, as long as the client trusts mitmproxy's built-in certificate authority (CA). CA certificates are the same for all *ids-vm* instances, as they are hardcoded to the IDS VM implementation. In the release version, these should be randomly generated and stored securely. -By default any of the clients should not trust mitmproxy's CA. That is why these CA certicates should be installed to OS's CA storage. However many client applications (web browsers) use their own CA bundles and importing custom certificates to there can be very complicated or requires manual user interaction. In our case this difficulty is circumvented in chromium-vm by disabling certicate verification errors, if the certicate chain contains a certificate which SPKI fingerprint matches that of mitmproxy's CA certificate fingerprint. This does not degrade security of server verification since mitmproxy itself validates upstream certificates using certifi Python package, which provides Mozilla's CA Bundle. +By default, any of the clients should not trust mitmproxy's CA. These CA certificates should be installed in the OS's CA storage. However, many client applications (web browsers, for example) use their own CA bundles, and importing custom certificates there can be complicated or require manual user interaction. In our case, this difficulty is circumvented in *chromium-vm* by disabling certificate verification errors, if the certificate chain contains a certificate which SPKI fingerprint matches that of mitmproxy's CA certificate fingerprint. This does not degrade server verification security since mitmproxy validates upstream certificates using a certified Python package which provides Mozilla's CA Bundle. Some applications use certificate pinning to prevent man-in-the-middle attacks. As a consequence mitmproxy's certificates will not be accepted by these applications without patching applications manually. Other option is to set mitmproxy to use ignore_hosts option to prevent mitmproxy from intercepting traffic to these specific domains. + + +[^note1]: **mitmproxy** is an interactive, SSL/TLS-capable intercepting proxy with a console interface for HTTP/1, HTTP/2, and WebSockets. **mitmweb** is a web-based interface for mitmproxy. **mitmdump** is the command-line version of mitmproxy. Source: [mitmproxy docs](https://docs.mitmproxy.org/stable/#3-powerful-core-tools). diff --git a/docs/src/ref_impl/labwc.md b/docs/src/ref_impl/labwc.md index 117c0001c..ad55d6ce0 100644 --- a/docs/src/ref_impl/labwc.md +++ b/docs/src/ref_impl/labwc.md @@ -12,7 +12,7 @@ To use labwc as your default desktop environment, add it as a module to Ghaf: * change the configuration option `profiles.graphics.compositor = "labwc"` or -* uncomment the corresponding line in the [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/virtualization/microvm/guivm.nix) file. +* uncomment the corresponding line in the [guivm.nix](https://github.com/tiiuae/ghaf/blob/main/modules/microvm/virtualization/microvm/guivm.nix) file. The basis of the labwc configuration is the set of following files: `rc.xml`, `menu.xml`, `autostart`, and `environment`. These files can be edited by substituting in the labwc overlay `overlays/custom-packages/labwc/default.nix`. diff --git a/docs/src/ref_impl/systemd-service-config.md b/docs/src/ref_impl/systemd-service-config.md index a92b5c71c..bdc78dced 100644 --- a/docs/src/ref_impl/systemd-service-config.md +++ b/docs/src/ref_impl/systemd-service-config.md @@ -133,6 +133,7 @@ Enables packet filtering on all IPv4 and IPv6 sockets created by the service. Us * **Specific Address Families**: Specify one or more address families that the service is allowed to use, for example, `'AF_INET'`, `'AF_INET6'`, `'AF_UNIX'`. * **Inverted Restriction**: Prepend character '~' to an address family name to deny access to it while allowing all others, for example, `'~AF_INET'` would block IPv4 access. +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -228,6 +229,7 @@ Additionally, when enabled, all temporary files created by a service in these di * **`all`**: Allows the service access to all `/proc` entries. * **`pid`**: Restricts the service to only its own process information (`/proc/self`, `/proc/thread-self/`). +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -235,6 +237,7 @@ Additionally, when enabled, all temporary files created by a service in these di > **IMPORTANT:** Not applicable for the service runs as root. + ### 3.1. PrivateUsers [PrivateUsers=](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateUsers=) controls whether the service should run with a private set of UIDs and GIDs, isolating the user and group databases used by the unit from the rest of the system, and creating a secure sandbox environment. The isolation reduces the privilege escalation potential of services. @@ -256,6 +259,7 @@ Additionally, when enabled, all temporary files created by a service in these di * **`true`**: A UNIX user and group pair are dynamically allocated when the unit is started and released as soon as it is stopped. * **`false`**: The service uses a static UID/GID defined in the service unit file or defaults to `root`. +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -282,6 +286,7 @@ Additionally, when enabled, all temporary files created by a service in these di **Options**: * Specify device access rules in the format: ` ` where `` can be `r` (read), `w` (write), or `m` (mknod, allowing creation of devices). +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -320,7 +325,7 @@ Additionally, when enabled, all temporary files created by a service in these di * **`trues`**: Restricts the service from accessing kernel logs from `/proc/kmsg` and `/dev/kmsg`. Enabling this option removes `CAP_SYSLOG` from the capability bounding set for the unit and installs a system call filter to block the syslog(2) system call. * **`no`**: Allows the service to access kernel logs. - +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -494,6 +499,7 @@ Additionally, when enabled, all temporary files created by a service in these di * `exec`: Only service updates sent from any main or control processes originating from one of the `Exec*=` commands are accepted. * `all`: Allows sending signals using any process identifier (PID). +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -565,6 +571,7 @@ This option can be specified multiple times to merge capability sets: **CAP_SYS_TTY_CONFIG** | Allows processes to configure tty devices. **CAP_WAKE_ALARM** | Allows processes to use the RTC wakeup alarm. +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) --- @@ -599,4 +606,8 @@ This option can be specified multiple times to merge capability sets: **@swap** | Allows swap-related system calls, which are used for managing swap space. **@syslog** | Allows syslog-related system calls, which are used for system logging. **@system-service** | Allows system service-related system calls, which are used for managing system services. -**@timer** | Allows timer-related system calls, which are essential for setting and managing timers. \ No newline at end of file +**@timer** | Allows timer-related system calls, which are essential for setting and managing timers. + + +[Back to Top ⏫](./systemd-service-config.md#systemd-service-hardening) +--- \ No newline at end of file diff --git a/docs/src/release_notes/ghaf-23.09.md b/docs/src/release_notes/ghaf-23.09.md index 96fd18414..91edadf68 100644 --- a/docs/src/release_notes/ghaf-23.09.md +++ b/docs/src/release_notes/ghaf-23.09.md @@ -31,8 +31,8 @@ The following target hardware is supported by this release: * Modularization of the Ghaf framework: [Ghaf as Library: Templates](../ref_impl/ghaf-based-project.md). * NVIDIA Jetson Orin NX Ethernet passthrough. * Lenovo X1 Carbon Gen 11: - * Graphics passthrough to GUIVM. - * Launching Application VMs through GUIVM (Chromium, Gala, and Zathura). + * Graphics passthrough to GUI VM. + * Launching Application VMs through GUI VM (Chromium, Gala, and Zathura). * Paravirtualized audio. * Webcam passthrough. * Touchpad passthrough. @@ -52,7 +52,7 @@ Fixed bugs that were in the ghaf-23.06 release: | Issue | Status | Comments | |-----------------|-------------|--------------------------------------| -| Chromium AppVM does not boot up on X1 | In Progress | Intermittent timing issue, under investigation. | +| Chromium App VM does not boot up on X1 | In Progress | Intermittent timing issue, under investigation. | | The GALA app does not work | In Progress | Will be fixed in the next release. | | Shutdown or reboot of Lenovo X1 takes a lot of time (7 minutes) | In Progress | Advice: be patient or, if in hurry, press power key for 15 sec. | | Copy and paste text from or to Chromium AppVM does not work | In Progress | | diff --git a/docs/src/release_notes/ghaf-23.12.md b/docs/src/release_notes/ghaf-23.12.md index 46b375e3b..8cfdce420 100644 --- a/docs/src/release_notes/ghaf-23.12.md +++ b/docs/src/release_notes/ghaf-23.12.md @@ -29,7 +29,7 @@ The following target hardware is supported by this release: * CLI-based installer. * Lenovo X1 Carbon Gen 11: * Configurable PCI and USB devices passthrough. - * Network Manager: support from GUIVM to NETVM. + * Network Manager: support from GUI VM to Net VM. * Windows VM support. * Added Ghaf icons and the background image. * Secure Boot is disabled by default. @@ -66,7 +66,7 @@ Fixed bugs that were in the ghaf-23.09 release: | Time synchronization between host and VMs does not work in all scenarios | In Progress | Under investigation. | | The taskbar disappears after the external display is disconnected from Lenovo X1 | In Progress | Under investigation. | | Closing and re-opening a deck lid of a X1 laptop with running Ghaf causes instability | In Progress | Workaround: keep a deck lid of a laptop open while working with Ghaf. | -| Applications do not open from icons when netvm is restarted | In Progress | Workaround: Restart AppVMs. | +| Applications do not open from icons when net-vm is restarted | In Progress | Workaround: Restart App VMs. | ## Environment Requirements diff --git a/docs/style_guide.md b/docs/style_guide.md index 824a7a5bc..871db9767 100644 --- a/docs/style_guide.md +++ b/docs/style_guide.md @@ -108,10 +108,15 @@ To make our Markdown files maintainable over time and across teams, follow the r --- **IMPORTANT** - Very importamt information. + Very important information. --- ``` +* Footnotes + + For footnote references, use an identifier inside brackets. For example: + in a text: `... this template[^note1] ...` + at the end of the file: `[^note1]: This template is based on...` * Markdown shields (badges) @@ -119,7 +124,8 @@ To make our Markdown files maintainable over time and across teams, follow the r * Unicode characters - For GitHub .md files (not for GitHub Pages), emojis are welcome :octocat:. [Supported GitHub emojis](https://github-emoji-picker.vercel.app/). + For GitHub .md files (not for GitHub Pages), emojis are welcome :octocat:. + Check [Supported GitHub emojis](https://github-emoji-picker.vercel.app/) for more inspiration.