qusal/CONTRIBUTING.md

Contributing

Table of Contents

• Respect
• Environment
  • Requirements
  • Lint
• Format
  • File naming
  • State ID
  • Readme
  • Qube preferences
  • Qrexec

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

For linting:

• pre-commit
• gitlint
• salt-lint
• shellcheck
• reuse

For building RPMs:

• dnf
• rpm
• rpmlint

Lint

Lint before you commit, please... else you will have to fix after the PR has already been sent.

Install the local hooks:

pre-commit install
gitlint install-hook

To run pre-commit linters:

pre-commit run

Format

File naming

1. Every State file .sls must have a Top file .top. This ensures that every state can be applied with top.
2. Every project must have a init.top, it facilitates applying every state by enabling a single top file.
3. State file naming must be common between the projects, it helps understand the project as if it was any other.
4. File name must use - as separator, not _.

State ID

1. State IDs must use - as separator, not _. The underline is allowed in case the features it is changing has underline, such as default_netvm.
2. State IDs must always have the project ID, thus allowing to target multiple states to the same minion from different projects without having conflicting IDs.

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.

Qube preferences

1. Qube name format:

• TemplateVM: tpl-NAME
• StandaloneVM: NAME
• AppVM: NAME
• DispVM: disp-NAME
• DispVM Template (AppVM): dvm-NAME
• Service qubes (not a class): sys-NAME

2. Label/Color:

• Black (Ultimately trusted): You must trust Dom0, Templates, Vaults, Management qubes, these qubes control your system and hold valuable information. Examples: dom0, tpl-ssh, vault, default-mgmt-dvm.
• Gray (Fully trusted): Trusted storage with extra RPC services that allow certain operations to be made by the client and executed on the server or may build components for other qubes. Examples: sys-cacher, sys-git, sys-pgp, sys-ssh-agent, qubes-builder.
• Purple (Much trust): Has the ability to manager remote servers via encrypted connections and depend on authorization provided by another qube. Examples: ansible, dev, ssh, terraform.
• Blue (Very trusted): TODO
• Green (Trusted): TODO
• Yellow (Relatively trusted): TODO
• Orange (Slightly trusted): Controls the network flow of data to the client, normally a firewall. Examples: sys-firewall, sys-vpn, sys-pihole.
• Red (Untrusted): Holds untrusted data (PCI devices, untrusted programs, disposables for opening untrusted files or web pages). Examples: sys-net, sys-usb, dvm-browser.

Qrexec

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 to be set by Dom0 via the target= redirection parameter, instead of having to modify the client to target a different server via qrexec-client-vm.
3. Target qube for client script must default to @default, but other targets must be allowed via parameters.