diff --git a/.reuse/dep5 b/.reuse/dep5 index 1a5dd99..90dcad8 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -3,8 +3,7 @@ Upstream-Name: qusal Upstream-Contact: Benjamin Grande M. S. Source: https://github.com/ben-grande/qusal -Files: BOOTSTRAP.md CONTRIBUTING.md README.md */README.md - .github/ISSUE_TEMPLATE/* +Files: README.md */README.md docs/* .github/ISSUE_TEMPLATE/* Copyright: 2023 - 2024 Benjamin Grande M. S. License: CC-BY-SA-4.0 diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md deleted file mode 100644 index 2e38740..0000000 --- a/BOOTSTRAP.md +++ /dev/null @@ -1,88 +0,0 @@ -# Bootstrap - -Qusal bootstrap strategy. - -## Table of Contents - -* [Description](#description) -* [Essential](#essential) -* [Optional](#optional) - * [Internet communication](#internet-communication) - * [Files](#files) - * [Admin](#admin) - -## Description - -With so many packages, you are wondering, how to bootstrap a new system? Which -order should the packages be applied? Well, the answer depends on your goal. - -Bellow you will find a list sorted by task, which have projects that can help -you accomplish your mission. - -## Essential - -- Base (in order): - - [dom0](salt/dom0/README.md) - - [debian-minimal](salt/debian-minimal/README.md) - - [fedora-minimal](salt/fedora-minimal/README.md) - - [sys-cacher](salt/sys-cacher/README.md) - - [mgmt](salt/mgmt/README.md) - -- Networking: - - [sys-net](salt/sys-net/README.md) - - [sys-firewall](salt/sys-firewall/README.md) - -- Miscellaneous: - - [vault](salt/vault/README.md) - - [sys-gui](salt/sys-gui/README.md) - - [sys-audio](salt/sys-audio/README.md) - -## Optional - -### Internet communication - -- Firewall, DNS Sinkhole and VPN Tunnel: - - [sys-mirage-firewall](salt/sys-mirage-firewall/README.md) - - [sys-pihole](salt/sys-pihole/README.md) - - [sys-wireguard](salt/sys-wireguard/README.md) - -- Web browser and file retriever: - - [browser](salt/browser/README.md) - - [fetcher](salt/fetcher/README.md) - -- Instant messaging and E-Mail: - - [mutt](salt/mutt/README.md) - - [signal](salt/signal/README.md) - -### Files - -- USB: - - [usb](salt/usb/README.md) - - [sys-usb](salt/sys-usb/README.md) - -- Multimedia: - - [reader](salt/reader/README.md) - - [media](salt/media/README.md) - -- File sharing: - - [sys-ssh](salt/sys-ssh/README.md) - - [sys-syncthing](salt/sys-syncthing/README.md) - - [sys-rsync](salt/sys-rsync/README.md) - -### Admin - -- Remote administration: - - [remmina](salt/remmina/README.md) - - [ssh](salt/ssh/README.md) - - [sys-ssh-agent](salt/sys-ssh-agent/README.md) - -- Remote task execution and configuration management: - - [ansible](salt/ansible/README.md) - - [docker](salt/docker/README.md) - - [terraform](salt/terraform/README.md) - -- Coding: - - [dev](salt/dev/README.md) - - [sys-pgp](salt/sys-pgp/README.md) - - [sys-git](salt/sys-git/README.md) - - [sys-ssh-agent](salt/sys-ssh-agent/README.md) diff --git a/README.md b/README.md index 17bb83b..a15f685 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ and will be introduced in the meantime. You've been warned. ## Table of Contents * [Description](#description) -* [Design](#design) * [Prerequisites](#prerequisites) * [Installation](#installation) * [DomU Installation](#domu-installation) @@ -30,27 +29,18 @@ and will be introduced in the meantime. You've been warned. ## Description -Qusal providers a Free and Open Source solution to customizing various tasks -in Qubes OS, from switching PCI handlers to be disposables or app qubes, -installing different pieces of software on dedicated minimal templates for -split agent operations for separating the key store from the client. +Qusal is a Free and Open Source security-focused project that provides +SaltStack Formulas for Qubes OS users to complete various daily tasks, such +as web browsing, video-calls, remote administration, coding, network tunnels +and much more, which are easy to install and maintains low attack surface. -Each project is in a separate directory, but they may interact with other -projects. +We not only provide a single solution for each project, but also provides +alternative when they differ, such as for networking, you could use a VPN, +DNS Sink-hole, Mirage Unikernel or the standard Qubes Firewall for managing +the network chain and the connections the clients connected to these NetVMs +are allowed to make. -If you want to edit the access control for any service, such as resolution to -allow, ask, deny or the intended target, you should always use the Qrexec -policy at `/etc/qubes/policy.d/30-user.policy`, as this file will take -precedence over the packaged policy. - -## Design - -Every project creates its own template, client and server (when necessary) -with only the required packages and configuration. You don't need to use a -separate template for everything, but if you want to do that, you will have -adjust the target of the qubesctl call or write Salt Top files. - -Qubes global settings (qubes-prefs) that will be managed: +Here are some of the Global Preferences we can manage: - **clockvm**: disp-sys-net, sys-net - **default_dispvm**: dvm-reader @@ -59,18 +49,18 @@ Qubes global settings (qubes-prefs) that will be managed: - **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall - **default_audiovm**: disp-sys-audio -To be implemented: -- **default_guivm**: sys-gui +If you want to learn more about how we make decisions, take a look at our +[design document](docs/DESIGN.md). -## Prerequisites +## Installation + +### Prerequisites You current setup needs to fulfill the following requisites: - Qubes OS R4.2 - Internet connection -## Installation - ### DomU Installation 1. Install `git` in the downloader qube, if it is an AppVM, install it it's @@ -95,18 +85,20 @@ You current setup needs to fulfill the following requisites: Before copying anything to Dom0, read [Qubes OS warning about consequences of this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0). -1. Copy this repository from some qube to Dom0 from Dom0: -```sh -mkdir -p ~/QubesIncoming/ -qvm-run -p tar -cC qusal | tar -xvC ~/QubesIncoming/ qusal -## Example: mkdir -p ~/QubesIncoming/dev -## Example: qvm-run -p dev tar -cC /home/user qusal | tar -xvC ~/QubesIncoming/dev qusal -``` +1. Copy this repository `$file` from the DomU `$qube` to Dom0: + ```sh + qube="CHANGEME" # qube name where you downloaded the repository + file="CHANGEME" # path to the repository in the qube + qvm-run --pass-io --localcmd="UPDATES_MAX_FILES=10000 + /usr/libexec/qubes/qfile-dom0-unpacker user + ~/QubesIncoming/${qube}/qusal" \ + "${qube}" /usr/lib/qubes/qfile-agent "${file}" + ``` 2. Copy the project to the Salt directories: -```sh -~/QubesIncoming//qusal/scripts/setup.sh -``` + ```sh + ~/QubesIncoming//qusal/scripts/setup.sh + ``` ## Update @@ -125,56 +117,52 @@ git -C ~/src/qusal fetch --recurse-submodules 1. Install git on Dom0, allow the Qrexec protocol to work in submodules and clone the repository to `~/src/qusal` (only has to be run once): -```sh -mkdir -p ~/src -sudo qubesctl state.apply sys-git.install-client -git config --file ~/.gitconfig.local protocol.qrexec.allow always -git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal -``` + ```sh + mkdir -p ~/src + sudo qubesctl state.apply sys-git.install-client + git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal + ``` -2. Fetch from the app qube and place the files in the salt tree (git merge and - pull will verify the HEAD signature automatically) -```sh -git -C ~/src/qusal fetch --recurse-submodules -~/src/qusal/scripts/setup.sh -``` +2. Fetch from the app qube and place the files in the salt tree (git merge + and pull will verify the HEAD signature automatically) + ```sh + git -C ~/src/qusal fetch --recurse-submodules + ~/src/qusal/scripts/setup.sh + ``` ## Usage -Qusal is now installed. Please read the README.md of each project for further -information on how to install the desired package. +Qusal is now installed. Please read the README.md of each project in the +[salt](salt/) directory for further information on how to install the desired +package. If you are unsure how to start, get some ideas from our +[bootstrap guide](docs/BOOTSTRAP.md). The intended behavior is to enforce the state of qubes and their services. If -you modify the qubes and their services and apply the state again, there is a -good chance your choices will be overwritten. To enforce your state, write a -SaltFile to specify the desired state, do not do it manually, we are past -that. +you modify the qubes and their services and apply the state again, +conflicting configurations will be overwritten. To enforce your state, write +a SaltFile to specify the desired state and call it after the ones provided +by this project. -The only Qrexec policy file you should change is -`/etc/qubes/policy.d/30-user.policy` as this file will take precedence over -the ones provided by this project. If you modify the policies provided by -Qusal, your changes will be overwritten next time you install/upgrade the -packages. +If you want to edit the access control of any service, you +should always use the Qrexec policy at `/etc/qubes/policy.d/30-user.policy`, +as this file will take precedence over the packaged policies. Please note that when you allow more Qrexec calls than the default shipped by Qubes OS, you are increasing the attack surface of the target, normally -valuable qube that can hold secrets or pristine data. A compromise of the -client qube can extend to the server, therefore configure the installation -according to your threat model. - -If you are unsure how to start, follow the [bootstrap guide](BOOTSTRAP.md) for -some ideas on how to customize your system. +to a valuable qube that can hold secrets or pristine data. A compromise of +the client qube can extend to the server, therefore configure the +installation according to your threat model. ## Contribute -There are several ways to contribute to this project. Spread the word, help on -user support, review opened issues, fix typos, implement new features, +There are several ways to contribute to this project. Spread the word, help +on user support, review opened issues, fix typos, implement new features, donations. -Please take a look at [contribution guidelines](CONTRIBUTING.md) before -contributing code or to the documentation, it holds important information on -how the project is structured, why some design decisions were made and what -can be improved. +Please take a look at our [contribution guidelines](docs/CONTRIBUTING.md) +before contributing code or to the documentation, it holds important +information on how the project is structured, why some design decisions were +made and what can be improved. ## Donate diff --git a/docs/BOOTSTRAP.md b/docs/BOOTSTRAP.md new file mode 100644 index 0000000..aa5433c --- /dev/null +++ b/docs/BOOTSTRAP.md @@ -0,0 +1,88 @@ +# Bootstrap + +Qusal bootstrap strategy. + +## Table of Contents + +* [Description](#description) +* [Essential](#essential) +* [Optional](#optional) + * [Internet communication](#internet-communication) + * [Files](#files) + * [Admin](#admin) + +## Description + +With so many packages, you are wondering, how to bootstrap a new system? Which +order should the packages be applied? Well, the answer depends on your goal. + +Bellow you will find a list sorted by task, which have projects that can help +you accomplish your mission. + +## Essential + +- Base (in order): + - [dom0](../salt/dom0/README.md) + - [debian-minimal](../salt/debian-minimal/README.md) + - [fedora-minimal](../salt/fedora-minimal/README.md) + - [sys-cacher](../salt/sys-cacher/README.md) + - [mgmt](../salt/mgmt/README.md) + +- Networking: + - [sys-net](../salt/sys-net/README.md) + - [sys-firewall](../salt/sys-firewall/README.md) + +- Miscellaneous: + - [vault](../salt/vault/README.md) + - [sys-gui](../salt/sys-gui/README.md) + - [sys-audio](../salt/sys-audio/README.md) + +## Optional + +### Internet communication + +- Firewall, DNS Sinkhole and VPN Tunnel: + - [sys-mirage-firewall](../salt/sys-mirage-firewall/README.md) + - [sys-pihole](../salt/sys-pihole/README.md) + - [sys-wireguard](../salt/sys-wireguard/README.md) + +- Web browser and file retriever: + - [browser](../salt/browser/README.md) + - [fetcher](../salt/fetcher/README.md) + +- Instant messaging and E-Mail: + - [mutt](../salt/mutt/README.md) + - [signal](../salt/signal/README.md) + +### Files + +- USB: + - [usb](../salt/usb/README.md) + - [sys-usb](../salt/sys-usb/README.md) + +- Multimedia: + - [reader](../salt/reader/README.md) + - [media](../salt/media/README.md) + +- File sharing: + - [sys-ssh](../salt/sys-ssh/README.md) + - [sys-syncthing](../salt/sys-syncthing/README.md) + - [sys-rsync](../salt/sys-rsync/README.md) + +### Admin + +- Remote administration: + - [remmina](../salt/remmina/README.md) + - [ssh](../salt/ssh/README.md) + - [sys-ssh-agent](../salt/sys-ssh-agent/README.md) + +- Remote task execution and configuration management: + - [ansible](../salt/ansible/README.md) + - [docker](../salt/docker/README.md) + - [terraform](../salt/terraform/README.md) + +- Coding: + - [dev](../salt/dev/README.md) + - [sys-pgp](../salt/sys-pgp/README.md) + - [sys-git](../salt/sys-git/README.md) + - [sys-ssh-agent](../salt/sys-ssh-agent/README.md) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..8023d7d --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing + +Qusal contribution guidelines. + +## Table of Contents + +* [Respect](#respect) +* [Environment](#environment) + * [Requirements](#requirements) + * [RPM Spec](#rpm-spec) + * [Lint](#lint) +* [Where to start](#where-to-start) + +## Respect + +Be respectful towards peers. + +## Environment + +You will need to setup you development environment before you start +contributing. You will need Qubes OS R4 or higher. + +### Requirements + +The following are the packages you need to install: + +General: +- git + +For writing: +- editorconfig +- editorconfig plugin for your editor +- vim, [vim-jinja](https://github.com/ben-grande/vim-jinja), + [vim-salt](https://github.com/ben-grande/vim-salt) (recommended) + +For linting: +- pre-commit +- gitlint +- salt-lint +- shellcheck +- reuse + +For building RPMs: +- sed (GNU sed) +- dnf +- dnf-plugins-core (dnf builddep) +- rpm +- rpmlint +- rpmautospec (only available in Fedora) + +### RPM Spec + +Reference material: + +- [docs.fedoraproject.org/en-US/packaging-guidelines/](https://docs.fedoraproject.org/en-US/packaging-guidelines/) +- [rpm-software-management.github.io](https://rpm-software-management.github.io/rpm/manual/spec.html) +- [rpm-packaging-guide.github.io](https://rpm-packaging-guide.github.io/) +- [rpm-guide.readthedocs.io](https://rpm-guide.readthedocs.io/en/latest/rpm-guide.html) +- [ftp.rpm.org/max-rpm/s1-rpm-build-creating-spec-file.html](http://ftp.rpm.org/max-rpm/s1-rpm-build-creating-spec-file.html) + +### Lint + +Lint before you commit, please... else you will have to fix after the PR has +already been sent. + +Install the local hooks: +```sh +pre-commit install +gitlint install-hook +``` + +To run pre-commit linters: +```sh +pre-commit run +``` + +## Where to start + +See open issues and search for the word `TODO` in the repository files. diff --git a/CONTRIBUTING.md b/docs/DESIGN.md similarity index 53% rename from CONTRIBUTING.md rename to docs/DESIGN.md index 5d6ea83..7d5a458 100644 --- a/CONTRIBUTING.md +++ b/docs/DESIGN.md @@ -1,12 +1,10 @@ -# Contributing +# Design + +Qusal design document. ## Table of Contents -* [Respect](#respect) -* [Environment](#environment) - * [Requirements](#requirements) - * [RPM Spec](#rpm-spec) - * [Lint](#lint) +* [Goal](#goal) * [Format](#format) * [File naming](#file-naming) * [State ID](#state-id) @@ -14,71 +12,32 @@ * [Qube preferences](#qube-preferences) * [Qube naming](#qube-naming) * [Qube label](#qube-label) - * [Qrexec](#qrexec) -* [Where to start](#where-to-start) + * [Qube connections](#qube-connections) + * [Qrexec call and policy](#qrexec-call-and-policy) -## Respect +## Goal -Be respectful towards peers. +Provide a minimal modular isolated environment for users to complete daily +tasks in a secure manner. We should not focus on a specific Qubes OS user base +as it would narrow our reach. We scope to have a diverse user base, with +different needs and use case that could shape our project for the better. -## Environment +We must not aim to be a one solution fits all by adding every new project +someone asks for, if the number of projects grows too large, it would be +impossible to keep track of everything, especially with major distribution +updates from templates and Qubes OS releases. -You will need to setup you development environment before you start -contributing. You will need Qubes OS R4 or higher. +In order to achieve this goal, the formulas must always create qubes based on +minimal templates, with only the strictly necessary packages and features it +needs. If audio is not required, it is never installed and the qube preference +`audiovm` is set to None, the same applies to networking, thus avoiding +unexpected calls to the network or to the audio qube. If the memory +requirements are low, it is capped to a low limit, thus avoiding exacerbated +memory consumption on systems with low specs. -### Requirements - -The following are the packages you need to install: - -General: -- git - -For writing: -- editorconfig -- editorconfig plugin for your editor -- vim, [vim-jinja](https://github.com/ben-grande/vim-jinja), - [vim-salt](https://github.com/ben-grande/vim-salt) (recommended) - -For linting: -- pre-commit -- gitlint -- salt-lint -- shellcheck -- reuse - -For building RPMs: -- sed (GNU sed) -- dnf -- dnf-plugins-core (dnf builddep) -- rpm -- rpmlint -- rpmautospec (only available in Fedora) - -### RPM Spec - -Reference material: - -- [docs.fedoraproject.org/en-US/packaging-guidelines/](https://docs.fedoraproject.org/en-US/packaging-guidelines/) -- [rpm-software-management.github.io](https://rpm-software-management.github.io/rpm/manual/spec.html) -- [rpm-packaging-guide.github.io](https://rpm-packaging-guide.github.io/) -- [rpm-guide.readthedocs.io](https://rpm-guide.readthedocs.io/en/latest/rpm-guide.html) -- [ftp.rpm.org/max-rpm/s1-rpm-build-creating-spec-file.html](http://ftp.rpm.org/max-rpm/s1-rpm-build-creating-spec-file.html) - -### Lint - -Lint before you commit, please... else you will have to fix after the PR has -already been sent. - -Install the local hooks: -```sh -pre-commit install -gitlint install-hook -``` - -To run pre-commit linters: -```sh -pre-commit run -``` +No extraneous features should be included by default besides the basic for +functionality. Extra functionalities that could weak the system can be +provided via extra states that needs to be installed per the user discretion. ## Format @@ -102,9 +61,14 @@ pre-commit run ### Readme -1. Every project should have a README.md with at least the following sections: - Table of Contents, Description, Installation, Access Control (if changed - Qrexec policy), Usage. +Every project should have a README.md with at least the following sections: + +- Table of Contents; +- Description; +- Installation; +- Access Control (if Qrexec policy changed); +- Usage; and +- Credits (if sourced). ### Qube preferences @@ -122,18 +86,18 @@ part of its name and no exceptions. - **Service qubes (not a class)**: `sys-NAME` We recommend that for user created qubes, use the domain in the prefix of the -qube. An AppVM for personal banking will be named `personal-banking`, an AppVM -for personal e-mail will be named `personal-email`. +qube. An AppVM for personal banking will be named `personal-banking`, an +AppVM for personal e-mail will be named `personal-email`. #### Qube label We differ from upstream in many senses. We are not labeling qubes based on them sharing a common security domain, this is very limited if you have many security domains in use and they do not share the same level of trust. You -don't (or shouldn't) trust your networked browsing qube for personal usage the -same as you trust your vault. The following method tries to fix this problem, -domain name is in the prefix of the qube, the label is solely related to -trustworthiness of the data it is dealing with. +don't (or shouldn't) trust your networked browsing qube for personal usage +the same as you trust your vault. The following method tries to fix this +problem, domain name is in the prefix of the qube, the label is solely +related to trustworthiness of the data it is dealing with. - **Black**: - **Trust**: Ultimate. @@ -174,7 +138,33 @@ trustworthiness of the data it is dealing with. disposables for opening untrusted files or web pages). - **Examples**: sys-net, sys-usb, dvm-browser. -### Qrexec +### Qube connections + +There are several ways a qube can connect to another, either directly with +Xen or with Qrexec. If something is not required, we remove it. + +- `template` is always required: + - When required, must be set to the custom-made template; + - When not possible to use, prefer StandaloneVMs instead. +- `audiovm` is rarely required on the majority of the projects: + - When required, set it to `"*default*"` to honor the global preferences. + - When not required, must be set to None; +- `netvm` is required on a lot of projects. + - When required, must not be managed to honor the global preferences. If it + requires a custom networking scheme, the state must make sure that the + netvm exists; + - When not required, must be set to None. +- `default_dispvm` is nice to have: + - When required, must guarantee that the network follows the same chain as + the calling qube in the default configuration; + - When not required, must be set to None. +- `management_dispvm` is always required: + - When required, should not be managed to honor the global preferences, + but it can make sense to set a custom management qube for debugging. + - When not required, such as on qubes that don't work through Salt, don't + touch it, it doesn't increase attack surface. + +### Qrexec call and policy 1. Don't use `*` for source and destination, use `@anyvm` instead 2. Target qube for policies must be `@default`. It allows for the real target @@ -183,7 +173,3 @@ trustworthiness of the data it is dealing with. `qrexec-client-vm`. 3. Target qube for client script must default to `@default`, but other targets must be allowed via parameters. - -## Where to start - -See open issues and search for the word `TODO` in the repository files.