f8ea066b2b
As it is not easy to get files to dom0 and we don't want to reimplement a package manager, crude Git is the solution as of know. With Git we have the following advantages: native fetch format for source controlled files, cleaner command-line, automatic signature verification during merge, the disadvantage is that it is not included by default in Dom0 and filtering it's stdout chars are not possible. Note that the remote can report messages to the client via stderr, which is filtered already, and if it tries to send an escape sequence to stdout, the operation will fail with 'bad line length character: CHAR' printed to stderr on the client, unfiltered by qrexec, but filtered to some extent by the git client. If it is an escape character, the char is transformed to "?", but UTF-8 multibyte characters are not filtered. Up to 4 bytes can be displayed. Tar on the other hand is already installed, but it is much ancient and it's file parsing caused CVEs in the past relatively more drastic than Git, it also doesn't only include committed files, it can include any file that is present in the directory, which by far, increases a lot of the attack surface unless you reset the state to HEAD, clean .git directory manually and there are possibly other avenues of attack. |
||
|---|---|---|
| .github | ||
| .reuse | ||
| LICENSES | ||
| minion.d | ||
| rpm_spec/template | ||
| salt | ||
| scripts | ||
| .editorconfig | ||
| .gitignore | ||
| .gitlint | ||
| .gitmodules | ||
| .pre-commit-config.yaml | ||
| .salt-lint | ||
| .yamllint | ||
| BOOTSTRAP.md | ||
| CONTRIBUTING.md | ||
| README.md | ||
qusal
Salt Formulas for Qubes OS.
Warning
Warning: Not ready for production, development only. Breaking changes can and will be introduced in the meantime. You've been warned.
Table of Contents
- Description
- Design
- Prerequisites
- Installation
- Update
- Usage
- Contribute
- Donate
- Support
- Contact
- Credits
- Legal
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.
Each project is in a separate directory, but they may interact with other projects.
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:
- clockvm: disp-sys-net, sys-net
- default_dispvm: dvm-reader
- default_netvm: sys-pihole, sys-firewall or disp-sys-firewall
- management_dispvm: dvm-mgmt
- updatevm: sys-pihole, sys-firewall or disp-sys-firewall
- default_audiovm: disp-sys-audio
To be implemented:
- default_guivm: sys-gui
Prerequisites
You current setup needs to fulfill the following requisites:
- Qubes OS R4.2
- Internet connection
Installation
DomU Installation
-
Install
gitin the downloader qube, if it is an AppVM, install it it's the TemplateVM. -
Clone this repository:
git clone --recurse-submodules https://github.com/ben-grande/qusal.git
If you made a fork, fork the submodule(s) before clone and use your remote repository instead, the submodules will also be from your fork.
-
Acquire the maintainer signing key by other means and import it.
-
Verify the commit or tag signature and expect a good signature, be surprised otherwise:
git verify-commit HEAD
Dom0 Installation
Before copying anything to Dom0, read Qubes OS warning about consequences of this procedure.
- Copy this repository from some qube to Dom0 from Dom0:
mkdir -p ~/QubesIncoming/<QUBE>
qvm-run -p <QUBE> tar -cC </PATH/TO> qusal | tar -xvC ~/QubesIncoming/<QUBE> qusal
## Example: mkdir -p ~/QubesIncoming/dev
## Example: qvm-run -p dev tar -cC /home/user qusal | tar -xvC ~/QubesIncoming/dev qusal
- Copy the project to the Salt directories:
~/QubesIncoming/<QUBE>/qusal/scripts/setup.sh
Update
To update, you can copy the repository again to dom0 as instructed in the installation instructions above or you can fetch it with Git, as will be demonstrated below.
DomU Update
Update the repository state in your trusted DomU:
git -C ~/src/qusal fetch --recurse-submodules
Dom0 Update
- 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):
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
- Fetch from the app qube and place the files in the salt tree (git merge and pull will verify the HEAD signature automatically)
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.
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.
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.
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 for some ideas on how to customize your system.
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, donations.
Please take a look at contribution guidelines 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
This project can only survive through donations. If you like what we have done, please consider donating. Contact us for donation address.
This project depends on Qubes OS, consider donating to upstream.
Support
Free Support
Free support will be provided on a best effort basis. If you want something, open an issue and patiently wait for a reply, the project is best developed in the open so anyone can search for past issues.
Paid Support
Paid consultation services can be provided. Request a quote from us.
Contact
You must not contact for free support.
Credits
I stand on the shoulders of giants. This would not be possible without people contributing to Qubes OS SaltStack formulas. Honorable mention(s): unman.
Legal
This project is REUSE-compliant. It is difficult to list all licenses and copyrights and keep them up-to-date here.
The easiest way to get the copyright and license of the project with the reuse tool:
reuse spdx
You can also check these information manually by looking in the file header,
a companion .license file or in .reuse/dep5.
All licenses are present in the LICENSES directory.
Note that submodules have their own licenses and copyrights statements, please check each one individually using the same methods described above for a full statement.