2023-11-13 09:33:28 -05:00
|
|
|
# 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](#description)
|
|
|
|
|
* [Installation](#installation)
|
|
|
|
|
* [Usage](#usage)
|
|
|
|
|
* [Contribute](#contribute)
|
|
|
|
|
* [Donate](#donate)
|
|
|
|
|
* [Support](#support)
|
|
|
|
|
* [Free Support](#free-support)
|
|
|
|
|
* [Paid Support](#paid-support)
|
|
|
|
|
* [Contact](#contact)
|
|
|
|
|
* [Credits](#credits)
|
|
|
|
|
* [Legal](#legal)
|
|
|
|
|
|
|
|
|
|
## Description
|
|
|
|
|
|
2024-01-22 12:38:04 -05:00
|
|
|
Qusal is a Free and Open Source security-focused project that provides
|
2024-06-21 08:24:31 -04:00
|
|
|
SaltStack Formulas for [Qubes OS](https://www.qubes-os.org) 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.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-01-22 12:38:04 -05:00
|
|
|
We not only provide a single solution for each project, but also provides
|
2024-06-21 08:24:31 -04:00
|
|
|
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.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-01-22 12:38:04 -05:00
|
|
|
Here are some of the Global Preferences we can manage:
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
- **clockvm**: disp-sys-net, sys-net
|
2024-05-14 12:43:07 -04:00
|
|
|
- **default_audiovm**: disp-sys-audio
|
doc: how to update the repository
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.
2024-01-18 09:22:35 -05:00
|
|
|
- **default_dispvm**: dvm-reader
|
2023-11-13 09:33:28 -05:00
|
|
|
- **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall
|
|
|
|
|
- **management_dispvm**: dvm-mgmt
|
|
|
|
|
- **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall
|
|
|
|
|
|
2024-01-22 12:38:04 -05:00
|
|
|
## Installation
|
|
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
See the [installation instructions](docs/INSTALL.md).
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
After installing Qusal, please read the README.md of each project in the
|
|
|
|
|
[salt](salt/) directory you desire install. If you are unsure how to start,
|
|
|
|
|
get some ideas from our [bootstrap guide](docs/BOOTSTRAP.md).
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
The intended behavior is to enforce the state of qubes and their services. If
|
2024-06-21 08:24:31 -04:00
|
|
|
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.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-01-22 12:38:04 -05:00
|
|
|
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.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
Please note that when you allow more Qrexec calls than the default shipped by
|
2024-06-21 08:24:31 -04:00
|
|
|
Qubes OS, you are increasing the attack surface of the target, normally 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.
|
2024-01-04 16:05:35 -05:00
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
To troubleshoot issues, read our
|
|
|
|
|
[troubleshooting document](docs/TROUBLESHOOT.md).
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
## Contribute
|
2023-11-13 09:33:28 -05:00
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
See the [contribution instructions](docs/CONTRIBUTE.md).
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
## Donate
|
|
|
|
|
|
|
|
|
|
This project can only survive through donations. If you like what we have
|
|
|
|
|
done, please consider donating. [Contact us](#contact) for donation address.
|
2024-06-21 08:24:31 -04:00
|
|
|
Please note that donations are gratuitous, there is not obligation from the
|
|
|
|
|
maintainers to provide the donor with support, help with bugs, features or
|
|
|
|
|
answering questions, if there was, it would not be a donation, but a payment.
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
This project depends on Qubes OS, consider donating to
|
|
|
|
|
[upstream](https://qubes-os.org/donate/).
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
Paid consultation services can be provided. Request a quote
|
|
|
|
|
[from us](#contact).
|
2023-11-13 09:33:28 -05:00
|
|
|
|
|
|
|
|
## Contact
|
|
|
|
|
|
|
|
|
|
You must not contact for [free support](#free-support).
|
|
|
|
|
|
|
|
|
|
- [E-mail](https://github.com/ben-grande/ben-grande)
|
|
|
|
|
|
|
|
|
|
## 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](https://github.com/unman).
|
|
|
|
|
|
|
|
|
|
## Legal
|
|
|
|
|
|
|
|
|
|
This project is [REUSE-compliant](https://reuse.software). It is difficult to
|
|
|
|
|
list all licenses and copyrights and keep them up-to-date here.
|
|
|
|
|
|
2024-06-21 08:24:31 -04:00
|
|
|
The easiest way to get the copyright and license of the project is with the
|
|
|
|
|
reuse tool:
|
2023-11-13 09:33:28 -05:00
|
|
|
```sh
|
|
|
|
|
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.
|