mirror of
https://github.com/ben-grande/qusal.git
synced 2025-03-01 11:21:15 -05:00
doc: separate documents per use case
The main README is very large, by placing the documents in a separate directory, we allow the user to choose explicitly what they read, giving a better reading experience and allows a deeper understanding of the project.
This commit is contained in:
Ben Grande
parent
adba858477
commit
d23a6da9fc
@ -3,8 +3,7 @@ Upstream-Name: qusal
|
|||||||
Upstream-Contact: Benjamin Grande M. S. <ben.grande.b@gmail.com>
|
Upstream-Contact: Benjamin Grande M. S. <ben.grande.b@gmail.com>
|
||||||
Source: https://github.com/ben-grande/qusal
|
Source: https://github.com/ben-grande/qusal
|
||||||
|
|
||||||
Files: BOOTSTRAP.md CONTRIBUTING.md README.md */README.md
|
Files: README.md */README.md docs/* .github/ISSUE_TEMPLATE/*
|
||||||
.github/ISSUE_TEMPLATE/*
|
|
||||||
Copyright: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
|
Copyright: 2023 - 2024 Benjamin Grande M. S. <ben.grande.b@gmail.com>
|
||||||
License: CC-BY-SA-4.0
|
License: CC-BY-SA-4.0
|
||||||
|
|
||||||
|
|||||||
88
BOOTSTRAP.md
88
BOOTSTRAP.md
@ -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)
|
|
||||||
100
README.md
100
README.md
@ -10,7 +10,6 @@ and will be introduced in the meantime. You've been warned.
|
|||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
* [Description](#description)
|
* [Description](#description)
|
||||||
* [Design](#design)
|
|
||||||
* [Prerequisites](#prerequisites)
|
* [Prerequisites](#prerequisites)
|
||||||
* [Installation](#installation)
|
* [Installation](#installation)
|
||||||
* [DomU Installation](#domu-installation)
|
* [DomU Installation](#domu-installation)
|
||||||
@ -30,27 +29,18 @@ and will be introduced in the meantime. You've been warned.
|
|||||||
|
|
||||||
## Description
|
## Description
|
||||||
|
|
||||||
Qusal providers a Free and Open Source solution to customizing various tasks
|
Qusal is a Free and Open Source security-focused project that provides
|
||||||
in Qubes OS, from switching PCI handlers to be disposables or app qubes,
|
SaltStack Formulas for Qubes OS users to complete various daily tasks, such
|
||||||
installing different pieces of software on dedicated minimal templates for
|
as web browsing, video-calls, remote administration, coding, network tunnels
|
||||||
split agent operations for separating the key store from the client.
|
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
|
We not only provide a single solution for each project, but also provides
|
||||||
projects.
|
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
|
Here are some of the Global Preferences we can manage:
|
||||||
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
|
- **clockvm**: disp-sys-net, sys-net
|
||||||
- **default_dispvm**: dvm-reader
|
- **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
|
- **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall
|
||||||
- **default_audiovm**: disp-sys-audio
|
- **default_audiovm**: disp-sys-audio
|
||||||
|
|
||||||
To be implemented:
|
If you want to learn more about how we make decisions, take a look at our
|
||||||
- **default_guivm**: sys-gui
|
[design document](docs/DESIGN.md).
|
||||||
|
|
||||||
## Prerequisites
|
## Installation
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
You current setup needs to fulfill the following requisites:
|
You current setup needs to fulfill the following requisites:
|
||||||
|
|
||||||
- Qubes OS R4.2
|
- Qubes OS R4.2
|
||||||
- Internet connection
|
- Internet connection
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### DomU Installation
|
### DomU Installation
|
||||||
|
|
||||||
1. Install `git` in the downloader qube, if it is an AppVM, install it it's
|
1. Install `git` in the downloader qube, if it is an AppVM, install it it's
|
||||||
@ -95,12 +85,14 @@ You current setup needs to fulfill the following requisites:
|
|||||||
Before copying anything to Dom0, read [Qubes OS warning about consequences of
|
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).
|
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:
|
1. Copy this repository `$file` from the DomU `$qube` to Dom0:
|
||||||
```sh
|
```sh
|
||||||
mkdir -p ~/QubesIncoming/<QUBE>
|
qube="CHANGEME" # qube name where you downloaded the repository
|
||||||
qvm-run -p <QUBE> tar -cC </PATH/TO> qusal | tar -xvC ~/QubesIncoming/<QUBE> qusal
|
file="CHANGEME" # path to the repository in the qube
|
||||||
## Example: mkdir -p ~/QubesIncoming/dev
|
qvm-run --pass-io --localcmd="UPDATES_MAX_FILES=10000
|
||||||
## Example: qvm-run -p dev tar -cC /home/user qusal | tar -xvC ~/QubesIncoming/dev qusal
|
/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:
|
2. Copy the project to the Salt directories:
|
||||||
@ -128,12 +120,11 @@ git -C ~/src/qusal fetch --recurse-submodules
|
|||||||
```sh
|
```sh
|
||||||
mkdir -p ~/src
|
mkdir -p ~/src
|
||||||
sudo qubesctl state.apply sys-git.install-client
|
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
|
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
|
2. Fetch from the app qube and place the files in the salt tree (git merge
|
||||||
pull will verify the HEAD signature automatically)
|
and pull will verify the HEAD signature automatically)
|
||||||
```sh
|
```sh
|
||||||
git -C ~/src/qusal fetch --recurse-submodules
|
git -C ~/src/qusal fetch --recurse-submodules
|
||||||
~/src/qusal/scripts/setup.sh
|
~/src/qusal/scripts/setup.sh
|
||||||
@ -141,40 +132,37 @@ git -C ~/src/qusal fetch --recurse-submodules
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Qusal is now installed. Please read the README.md of each project for further
|
Qusal is now installed. Please read the README.md of each project in the
|
||||||
information on how to install the desired package.
|
[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
|
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
|
you modify the qubes and their services and apply the state again,
|
||||||
good chance your choices will be overwritten. To enforce your state, write a
|
conflicting configurations will be overwritten. To enforce your state, write
|
||||||
SaltFile to specify the desired state, do not do it manually, we are past
|
a SaltFile to specify the desired state and call it after the ones provided
|
||||||
that.
|
by this project.
|
||||||
|
|
||||||
The only Qrexec policy file you should change is
|
If you want to edit the access control of any service, you
|
||||||
`/etc/qubes/policy.d/30-user.policy` as this file will take precedence over
|
should always use the Qrexec policy at `/etc/qubes/policy.d/30-user.policy`,
|
||||||
the ones provided by this project. If you modify the policies provided by
|
as this file will take precedence over the packaged policies.
|
||||||
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
|
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
|
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
|
to a valuable qube that can hold secrets or pristine data. A compromise of
|
||||||
client qube can extend to the server, therefore configure the installation
|
the client qube can extend to the server, therefore configure the
|
||||||
according to your threat model.
|
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.
|
|
||||||
|
|
||||||
## Contribute
|
## Contribute
|
||||||
|
|
||||||
There are several ways to contribute to this project. Spread the word, help on
|
There are several ways to contribute to this project. Spread the word, help
|
||||||
user support, review opened issues, fix typos, implement new features,
|
on user support, review opened issues, fix typos, implement new features,
|
||||||
donations.
|
donations.
|
||||||
|
|
||||||
Please take a look at [contribution guidelines](CONTRIBUTING.md) before
|
Please take a look at our [contribution guidelines](docs/CONTRIBUTING.md)
|
||||||
contributing code or to the documentation, it holds important information on
|
before contributing code or to the documentation, it holds important
|
||||||
how the project is structured, why some design decisions were made and what
|
information on how the project is structured, why some design decisions were
|
||||||
can be improved.
|
made and what can be improved.
|
||||||
|
|
||||||
## Donate
|
## Donate
|
||||||
|
|
||||||
|
|||||||
88
docs/BOOTSTRAP.md
Normal file
88
docs/BOOTSTRAP.md
Normal file
@ -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)
|
||||||
79
docs/CONTRIBUTING.md
Normal file
79
docs/CONTRIBUTING.md
Normal file
@ -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.
|
||||||
@ -1,12 +1,10 @@
|
|||||||
# Contributing
|
# Design
|
||||||
|
|
||||||
|
Qusal design document.
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
* [Respect](#respect)
|
* [Goal](#goal)
|
||||||
* [Environment](#environment)
|
|
||||||
* [Requirements](#requirements)
|
|
||||||
* [RPM Spec](#rpm-spec)
|
|
||||||
* [Lint](#lint)
|
|
||||||
* [Format](#format)
|
* [Format](#format)
|
||||||
* [File naming](#file-naming)
|
* [File naming](#file-naming)
|
||||||
* [State ID](#state-id)
|
* [State ID](#state-id)
|
||||||
@ -14,71 +12,32 @@
|
|||||||
* [Qube preferences](#qube-preferences)
|
* [Qube preferences](#qube-preferences)
|
||||||
* [Qube naming](#qube-naming)
|
* [Qube naming](#qube-naming)
|
||||||
* [Qube label](#qube-label)
|
* [Qube label](#qube-label)
|
||||||
* [Qrexec](#qrexec)
|
* [Qube connections](#qube-connections)
|
||||||
* [Where to start](#where-to-start)
|
* [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
|
In order to achieve this goal, the formulas must always create qubes based on
|
||||||
contributing. You will need Qubes OS R4 or higher.
|
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
|
No extraneous features should be included by default besides the basic for
|
||||||
|
functionality. Extra functionalities that could weak the system can be
|
||||||
The following are the packages you need to install:
|
provided via extra states that needs to be installed per the user discretion.
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Format
|
## Format
|
||||||
|
|
||||||
@ -102,9 +61,14 @@ pre-commit run
|
|||||||
|
|
||||||
### Readme
|
### Readme
|
||||||
|
|
||||||
1. Every project should have a README.md with at least the following sections:
|
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.
|
- Table of Contents;
|
||||||
|
- Description;
|
||||||
|
- Installation;
|
||||||
|
- Access Control (if Qrexec policy changed);
|
||||||
|
- Usage; and
|
||||||
|
- Credits (if sourced).
|
||||||
|
|
||||||
### Qube preferences
|
### Qube preferences
|
||||||
|
|
||||||
@ -122,18 +86,18 @@ part of its name and no exceptions.
|
|||||||
- **Service qubes (not a class)**: `sys-NAME`
|
- **Service qubes (not a class)**: `sys-NAME`
|
||||||
|
|
||||||
We recommend that for user created qubes, use the domain in the prefix of the
|
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
|
qube. An AppVM for personal banking will be named `personal-banking`, an
|
||||||
for personal e-mail will be named `personal-email`.
|
AppVM for personal e-mail will be named `personal-email`.
|
||||||
|
|
||||||
#### Qube label
|
#### Qube label
|
||||||
|
|
||||||
We differ from upstream in many senses. We are not labeling qubes based on
|
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
|
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
|
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
|
don't (or shouldn't) trust your networked browsing qube for personal usage
|
||||||
same as you trust your vault. The following method tries to fix this problem,
|
the same as you trust your vault. The following method tries to fix this
|
||||||
domain name is in the prefix of the qube, the label is solely related to
|
problem, domain name is in the prefix of the qube, the label is solely
|
||||||
trustworthiness of the data it is dealing with.
|
related to trustworthiness of the data it is dealing with.
|
||||||
|
|
||||||
- **Black**:
|
- **Black**:
|
||||||
- **Trust**: Ultimate.
|
- **Trust**: Ultimate.
|
||||||
@ -174,7 +138,33 @@ trustworthiness of the data it is dealing with.
|
|||||||
disposables for opening untrusted files or web pages).
|
disposables for opening untrusted files or web pages).
|
||||||
- **Examples**: sys-net, sys-usb, dvm-browser.
|
- **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
|
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
|
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`.
|
`qrexec-client-vm`.
|
||||||
3. Target qube for client script must default to `@default`, but other targets
|
3. Target qube for client script must default to `@default`, but other targets
|
||||||
must be allowed via parameters.
|
must be allowed via parameters.
|
||||||
|
|
||||||
## Where to start
|
|
||||||
|
|
||||||
See open issues and search for the word `TODO` in the repository files.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user