[New Version]

.github/workflows/bandit.yml

@@ -12,10 +12,7 @@
 
 name: Bandit
 on:
-  push:
-    branches: [ "master", "dev" ]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [ "master" ]
 
 jobs:

.github/workflows/codeql.yml

@@ -12,10 +12,7 @@
 name: "CodeQL"
 
 on:
-  push:
-    branches: [ "master", "dev" ]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [ "master" ]
 
 jobs:

.github/workflows/license_scanner.yml

@@ -1,10 +1,7 @@
 name: License Scanner
 
 on:
-  push:
-    branches: [ "master", "dev" ]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [ "master" ]
 
 jobs:
@@ -22,7 +19,14 @@ jobs:
     - name: Install dependencies
       run: |
         sudo apt-get update -y
-        sudo apt-get install -y libgirepository1.0-dev
+        sudo apt-get install -y \
+          libgirepository1.0-dev \
+          libcairo2-dev \
+          pkg-config \
+          python3-dev \
+          libffi-dev \
+          gobject-introspection \
+          libglib2.0-dev
         python -m pip install --upgrade pip
         pip install license_scanner
         pip install -e tower-lib

.github/workflows/pylint.yml

@@ -1,10 +1,7 @@
 name: Pylint
 
 on:
-  push:
-    branches: [ "master", "dev" ]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [ "master" ]
 
 jobs:
@@ -22,7 +19,14 @@ jobs:
     - name: Install dependencies
       run: |
         sudo apt-get update -y
-        sudo apt-get install -y libgirepository1.0-dev
+        sudo apt-get install -y \
+          libgirepository1.0-dev \
+          libcairo2-dev \
+          pkg-config \
+          python3-dev \
+          libffi-dev \
+          gobject-introspection \
+          libglib2.0-dev
         python -m pip install --upgrade pip
         pip install pylint
         pip install pylint-sarif-unofficial

.gitignore

@@ -164,3 +164,5 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+docs/src/whitepaper/toweros-whitepaper.pdf

docs/mkdocs.yml

@@ -2,6 +2,7 @@ site_name: Documentation
 site_url: https://toweros.org
 repo_url: https://github.com/towercomputers/toweros/
 repo_name: TowerOS
+copyright: © Tower Computers 2023
 docs_dir: src
 markdown_extensions:
     - attr_list

docs/src/diagram-usage.d2

@@ -0,0 +1,42 @@
+internet: Internet {
+  style.stroke: transparent
+  style.fill: transparent
+  icon: https://icons.terrastruct.com/essentials%2F140-internet.svg
+}
+
+deskpi: DeskPi Super6C {
+  style.fill: transparent
+
+  cm4-router: router {
+    icon: https://icons.terrastruct.com/infra%2F021-hardware.svg
+  }
+  cm4-web: web {
+    icon: https://icons.terrastruct.com/infra%2F021-hardware.svg
+  }
+  cm4-email: email {
+    icon: https://icons.terrastruct.com/infra%2F021-hardware.svg
+  }
+}
+
+thinclient: Thin Client {
+  style.fill: transparent
+  window-web: Firefox {
+    icon: https://icons.terrastruct.com/essentials%2F006-window.svg
+  }
+  window-email: Thunderbird {
+    icon: https://icons.terrastruct.com/essentials%2F006-window.svg
+  }
+}
+
+
+deskpi.*.style.fill: transparent
+deskpi.*.style.stroke: transparent
+
+thinclient.*.style.fill: transparent
+thinclient.*.style.stroke: transparent
+
+
+
+deskpi.cm4-router <-> internet
+deskpi.cm4-web -> thinclient.window-web: NX over SSH
+deskpi.cm4-email -> thinclient.window-email: NX over SSH

docs/src/guides.md

@@ -60,7 +60,8 @@ Before installing a package with `pip`, check that there is no `apk` package ins
 
 1. Install `pip` package in offline host
 
-To install a package with `pip` you must create a virtual environment. Please refer to [the official documentation](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/).
+To install a package with `pip` you must create a virtual environment. Please refer to **[the official documentation](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)**.
+Make sure to install your environment in the `/home` folder if you want it to be preserved during an upgrade.
 
         [thinclient]$ ssh office
         [office]$ mkdir myproject

docs/src/whitepaper/toweros-whitepaper.typ → docs/src/whitepaper/main.typ

@@ -1,4 +1,4 @@
-#import "template.typ": *
+#import "style/ieee.typ": *
 #show: ieee.with(
   title: "TowerOS: An Operating System for Network-Boundary
   Converged Multi-Level Secure Computing",
@@ -9,16 +9,15 @@
       url: "https://github.com/towercomputers/toweros"
     ),
   ),
+  abstract: [We describe TowerOS, a system architecture for converged multi-level secure (MLS) computing in which isolation between security domains is enforced at a network boundary rather than within a single shared-kernel or hypervisor-based platform. Each security domain runs on an independent headless host, while a thin client provides a unified user interface by compositing remote application displays over standard, widely-deployed cryptographic protocols. This design aims to reduce the cross-domain trusted computing base relative to software-boundary approaches while retaining the usability benefits of a single, integrated desktop.],
 )
 
-#set text(font: "Palatino")
 #set quote(block: true)
-#set enum(spacing: 500%)
+#set enum(spacing: 1em)
 #show quote: it => [
   #set block(width: 100%)
   #emph[#it]
 ]
-#set quote(block: true)
 
 = Background
 A converged multi-level secure (MLS) computing system is one that allows the user to operate across distinct security domains through a single user interface (UI). Traditional MLS systems rely on hardware-level isolation using a keyboard-video-mouse (KVM) switch and no UI compositing@soffer or more recently with software-level isolation and software-based UI compositing (e.g. using a hypervisor).@issa While hardware-level isolation is theoretically much more secure than software-level isolation, the overall usability of any MLS system without user-interface compositing is necessarily poor in comparison, because there is no single, unified interface provided for the user.
@@ -29,28 +28,21 @@ Recently, a system for hardware-level isolation with hardware-based UI compositi
 
 
 = Architecture
-TowerOS implements a new, hybrid design which performs _software-based user-interface compositing_ with _hardware-level isolation_ using standard network interfaces. TowerOS relegates each security domain to an independent headless computer, each with its own application state and security policies. These *Hosts* are networked together over a LAN and accessible by the user through a *Thin Client* device that is connected to the same network. The applications running on the various hosts are composited within a single user interface running on the thin client using a combination of multi-function network protocols (such as SSH) and desktop-sharing software (such as VNC over SSL).
-
-Instead of having to trust an operating system to be able properly to isolate different security domains all running on shared hardware, our design relies on cryptographically secure networking protocols to connect multiple independent computers together to form a single, virtual device that from the user's perspective functions very much like a normal desktop computer. Instead of running multiple virtual machines on a single computer (whether to save costs or to isolate different security domains at the level of a hypervisor) we instead merge together multiple computers into a single virtual machine, where the actual hardware that any given application runs on (for security, or, for that matter, for performance) is abstracted away. This provides for the best of both words: the security guarantees of hardware isolation plus the usability and flexibility of interfaces implemented in software.
+TowerOS implements a new, hybrid design, which performs _software-based user-interface compositing_ with _hardware-level isolation_ using standard network interfaces. Each security domain runs on an independent headless computer (a *host*), with its own application state and security policies. Hosts are connected over a LAN and accessed by the user through a *thin client* connected to the same network. Applications running on different hosts are presented within a single user interface on the thin client using a combination of multi-function network protocols (such as SSH) and remote-display software (such as VNC over an authenticated and encrypted transport).
 
-Such a system may be built exclusively with commercial off-the-shelf (COTS) hardware, and its trusted computing base (TCB) of the system is limited to the codebase for the networking protocols (SSH, etc.), which may be both widely used and easily audited. For example, each host would run whichever user applications are allowed within the security domain associated with the device in question. So one host might be running an e-mail client, another a word processor, another a password manager, and another a web browser. One host might be left stateless and reserved for hotloading with fresh copies of an operating system. The user would be able to access each of these applications from the laptop thin client using SSH and VNC, with application windows composited into a single graphical user interface (GUI) using the desktop compositor. Clipboard management could be performed on the laptop using the thin client, and file transfers could be handled easily with `scp` or with a local file browser and `sshfs`.
+Instead of having to trust an operating system to be able properly to isolate different security domains all running on shared hardware, our design relies on cryptographically secure networking protocols to connect multiple independent computers together to form a single, virtual device that from the user's perspective functions very much like a normal desktop computer. Instead of running multiple virtual machines on a single computer (whether to save costs or to isolate different security domains at the level of a hypervisor) we instead merge together multiple computers into a single virtual machine, where the actual hardware that any given application runs on (for security, or, for that matter, for performance) is abstracted away. This provides for the best of both worlds: the security guarantees of hardware isolation plus the usability and flexibility of interfaces implemented in software.
 
+Such a system may be built exclusively with commercial off-the-shelf (COTS) hardware. In contrast to software-boundary approaches, the core isolation boundary is not an in-kernel or in-hypervisor mechanism, but a network interface between physically independent machines. The cross-domain TCB is therefore dominated by the thin client's networking and remote-display stacks, plus the cryptographic protocol implementations used to connect to each host. For example, each host would run whichever user applications are allowed within the security domain associated with the device in question. So one host might be running an e-mail client, another a word processor, another a password manager, and another a web browser. One host might be left stateless and reserved for hotloading with fresh copies of an operating system. The user would access these applications from the thin client using SSH and VNC, with application windows presented within a single graphical user interface (GUI). Clipboard management can be performed on the thin client, and file transfers can be handled with `scp` or with a local file browser and `sshfs`.
 
 = Threat Model
-The security properties of this design compare very favorably to those of software-boundary multi-level secure systems. First and foremost, such solutions rely on a large trusted computing base, including not only the (very complex) hypervisor, but also much of the underlying hardware (also very complex!) The network boundary is an ideal security boundary because it was historically designed explicitly for the interconnection of independent devices, often with different security policies. Both the hardware interface and the software compositing layer
-are small and well understood.
-
-The only data being _pushed_ to the thin client are pixels, clipboard data and audio streams from the hosts (and data are never communicated directly from host to host.) As a consequence, so long as the user of the thin client doesn't explicitly _pull_ malware onto the device, say with SSH, the risk of compromising the thin client (and by extension, the other hosts) is practically-speaking limited to the risk of critical input validation errors in the screen-sharing software itself or at the level of the network drivers. That is, even if the UI compositor on the thin-client machine does not enforce any security boundaries between application windows, the primary attack surface is limited to the only application running _in_ those windows, e.g. VNC.
+The security properties of this design compare favorably to those of software-boundary multi-level secure systems. Such solutions rely on a large trusted computing base, including not only a complex hypervisor, but also large driver stacks and substantial portions of the underlying hardware. By contrast, TowerOS moves the isolation boundary to the network interface between independent machines and relies on widely deployed, cryptographically protected network protocols for access to each domain. The cross-domain attack surface is therefore concentrated in the thin client's networking and remote-display stacks rather than in a hypervisor and its hardware-facing substrate.
 
-/* TODO
-Side-Channel Attacks
-- Traffic Analysis
-- Electromagnetic and Acoustic
-*/
+The primary untrusted inputs that a compromised host can push to the thin client are pixels, clipboard data, and audio streams. Direct host-to-host communication is forbidden (for example, by physical network topology, managed-switch isolation features, and OS-level firewall rules). As a consequence, so long as the user of the thin client does not explicitly pull untrusted executables onto the thin client, the main risk of compromising the thin client (and by extension, other domains) is limited to exploitable bugs in the thin client's protocol implementations, parsing, and rendering code (for example in remote-display software and the network stack).
 
+Crucially, TowerOS does not rely on compositor-level isolation between windows on the thin client as an enforcement boundary between security domains. Applications execute on hosts; the thin client primarily renders remote-display content and forwards user input over authenticated and encrypted channels. Even if the thin-client compositor treats all windows as peers, cross-domain compromise still requires an exploit in the thin client's networking / remote-display / clipboard / audio handling code, rather than a bypass of a compositor-enforced sandbox between local applications.
 
 = Comparison with Qubes OS
-The state-of-the-art in secure computing systems@snowden is #link("http://qubes-os.org")[Qubes OS] is an open-source converged multi-level secure operating system that uses hardware virtualization (with Xen) to isolate security domains. As the former lead developer of GrapheneOS put it:
+The state-of-the-art in secure computing systems@snowden is #link("http://qubes-os.org")[Qubes OS], an open-source converged multi-level secure operating system that uses hardware virtualization (with Xen) to isolate security domains. As the former lead developer of GrapheneOS put it:
 
 #quote(attribution: "D. Micay")[You can think of QubesOS as a way of approximating having 20 laptops with their own purposes, but all on 1 laptop. The security of each compartment still matters, and beyond isolating some drivers it doesn't do much to address that, but it does successfully approximate air gapped machines to a large extent. It's still significantly more secure to have separate machines but it's very impractical / unrealistic especially at that scale. There is no better option for approximating the security of using separate computers for different sets of tasks / identities.@graphene]
 
@@ -59,16 +51,19 @@ With TowerOS, we hope to address this deficiency in the software ecosystem. In t
 == Advantages
 #enum(
 enum.item(1)[Most importantly, Qubes OS relies heavily on the security guarantees of Xen, which is large, complicated, and has a history of serious security vulnerabilities.@deraadt
-#v(-15pt)
+
 #quote(attribution: "J. Rutkowska")[“In recent years, as more and more top notch researchers have begun scrutinizing Xen, a number of #link("https://xenbits.xen.org/xsa/")[security bugs] have been discovered. While #link("https://www.qubes-os.org/security/xsa/")[many] of them did not affect the security of Qubes OS, there were still too many that did.”@rutkowska]#v(5pt)],
 
 enum.item(2)[Qubes OS relies on the security properties of the hardware it runs on.
-#v(-15pt)
+
 #quote(attribution: "J. Rutkowska")[“Other problems arise from the underlying architecture of the x86 platform, where various inter-VM side- and covert-channels are made possible thanks to the aggressively optimized multi-core CPU architecture, most spectacularly demonstrated by the recently published #link("https://meltdownattack.com")[Meltdown and Spectre attacks]. Fundamental problems in other areas of the underlying hardware have also been discovered, such as the #link("https://googleprojectzero.blogspot.com/2015/03/exploiting-dram-rowhammer-bug-to-gain.html")[Row Hammer Attack].”@rutkowska]#v(5pt)],
 
-enum.item(3)[The complexity inherent in the design of Qubes OS makes the operating system difficult both to maintain and to use. Accordingly, Qubes OS development has slowed significantly in recent years: as of December 2022, the last release (v4.1.x, in February 2022) came almost four years after the previous one (v4.0.x in March 2018).@download],
+  // TODO
+  // https://comsec.ethz.ch/research/dram/zenhammer/
+
+enum.item(3)[The complexity inherent in the design of Qubes OS makes the operating system difficult both to maintain and to use. Accordingly, Qubes OS releases have historically been relatively infrequent, with multi-year gaps between major versions.@download],
 
-enum.item(4)[Qubes OS has support only for extremely few hardware configurations. As of December 2022, are only three laptops that are known to be fully compatible with Qubes OS.@certified With only moderate effort, TowerOS may be hybridized with any modern operating system so long as that operating system supports the standard network interfaces required for SSH, etc. This flexibility can enable the system to run a wide variety of software and hardware.]
+enum.item(4)[Qubes OS has support only for comparatively few hardware configurations, with an explicit certified hardware list.@certified With only moderate effort, TowerOS may be hybridized with any modern operating system so long as that operating system supports the standard network interfaces required for SSH, etc. This flexibility can enable the system to run a wide variety of software and hardware.]
 )
 
 == Disadvantages
@@ -84,4 +79,11 @@ enum.item(3)[In some cases, the security domain isolation within Qubes OS may be
 = Conclusion 
 Using “physically separate qubes” was proposed in the Qubes OS blog post cited above (in a hybrid design similar to what is being described here);@rutkowska but the suggested architecture would leave hardware-boundary isolation as a second-class citizen and, by continuing to rely on a derivative of today's Qubes OS, preserve all of the hardware-support, maintainability and usability issues that the OS suffers from today. An operating system desired specifically for pure network-boundary converged multi-level secure computing, as described in this document, is simultaneously much simpler, more secure and more user-friendly than Qubes OS. Indeed, this design addresses all of the major problems with QubesOS completely, and with a qualitatively smaller codebase.
 
+/* TODO
+Future Work
+- Side-Channel Attacks
+  - Traffic Analysis
+  - Electromagnetic and Acoustic
+*/
+
 #bibliography("refs.yml")

docs/src/whitepaper/style/ieee.typ

@@ -0,0 +1 @@
+/Users/adam/Documents/work/writing/auxiliary/templates/ieee.typ