mirror of
https://github.com/ben-grande/qusal.git
synced 2024-10-01 02:35:49 -04: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>
|
||||
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. <ben.grande.b@gmail.com>
|
||||
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)
|
||||
128
README.md
128
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/<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
|
||||
```
|
||||
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/<QUBE>/qusal/scripts/setup.sh
|
||||
```
|
||||
```sh
|
||||
~/QubesIncoming/<QUBE>/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
|
||||
|
||||
|
||||
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
|
||||
|
||||
* [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.
|
||||
Loading…
Reference in New Issue
Block a user