Dev/Qubes
Donate
Kicksecure Qubes OS related development documentation.
Kicksecure Template[edit]
Building the Template[edit]
Kicksecure has a Qubes OS template available that can be built and installed using qubes-builderv2. This allows Kicksecure to be installed into Qubes OS without the need for distribution morphing.
WARNING: The Kicksecure Qubes OS template is still in development and may be unstable or prone to issues. Use at your own risk.
Setting up qubes-builderv2[edit]
It is recommended to use a Fedora-based App Qube for building the Kicksecure template. This is because upstream Qubes uses Fedora-based App Qubes to build Qubes Templates.
Determine which Fedora template is used for the default-dvm DVM template. For the purposes of this document, we will assume it is fedora-40-xfce.
Installing dependencies[edit]
1. Launch a terminal in the fedora-40-xfce template.
2. Install all dependencies for qubes-builderv2 into the template. The dependencies are listed at:
- https://github.com/QubesOS/qubes-builderv2/blob/main/dependencies-fedora.txt
- https://github.com/QubesOS/qubes-builderv2/blob/main/dependencies-fedora-qubes-executor.txt
All packages from both lists must be installed.
3. Ensure git is installed by running the following command:
sudo dnf install git
4. Shut down the template once you have completed installing all dependencies.
Prepare App Qube[edit]
WARNING: It is not recommended to reuse an existing App Qube for running the template build. You will be transferring the built template to dom0 and installing it when you are complete. If the App Qube used for running the builder is compromised, the template may become compromised as well. Templates are simply RPM packages, meaning they can run arbitrary code as root during installation. This means that a compromised template can, and probably will, compromise dom0. To reduce the risk of this happening, you should use a fresh App Qube for the build process.
1. Create a new App Qube for running qubes-builderv2. You can name this qube anything you want; we will call it work-qubesos in this document. Ensure the Template is set to fedora-40-xfce. Using Qube Manager, set the private disk space for work-qubesos to something reasonably large. 32 GB should work.
2. Clone the default-dvm Template and name it qubes-builder-dvm. This DVM Template will be used for fetching and building code. Once the Template is cloned, adjust its settings with Qubes Manager and increase the private storage space to at least 30 GB (more is preferable).
3. Once that's done, start a terminal in the qubes-builder-dvm Template, then set it aside for use later.
4. Open a dom0 terminal and run:
sudo nano /etc/qubes/policy.d/50-qubesbuilder.policy
Type the contents of https://github.com/QubesOS/qubes-builderv2/blob/main/rpc/policy/50-qubesbuilder.policy into this file. (Note: If you have chosen names other than work-qubesos or qubes-builder-dvm for your qubes, you must adjust this configuration file to specify the correct VM names.) Save your changes with Ctrl+S and exit with Ctrl+X.
5. In the still-running qubes-builder-dvm Template, run:
sudo mkdir -p /rw/bind-dirs/builder /rw/config/qubes-bind-dirs.d
Then run:
sudo nano /rw/config/qubes-bind-dirs.d/builder.conf
and type:
binds+=('/builder')
into this file. Save and close the file when this is done.
6. Next, run:
sudo nano /rw/config/rc.local
and add the command:
mount /builder -o dev,suid,remount
to the file. Once this is done, shut down the Template.
7. In a dom0 terminal, run:
qvm-prefs work-qubesos default_dispvm qubes-builder-dvm
Once this is done, all configuration should be complete, and you are now ready to install and use qubes-builderv2.
Installing qubes-builderv2[edit]
1. Ensure that fedora-40-xfce, qubes-builder-dvm, and work-qubesos are all shut down. This ensures that all changes made to the templates apply to any new AppVMs and DispVMs launched during the build process.
2. Start work-qubesos and open a terminal in it. Install and verify the authenticity of the Qubes Security Pack by following the instructions at https://www.qubes-os.org/security/pack/. This is necessary to verify the authenticity of the qubes-builderv2 source code.
3. Clone the qubes-builderv2 repository using:
git clone https://github.com/QubesOS/qubes-builderv2.git
4. Enter the cloned repository:
cd qubes-builderv2
5. Verify the authenticity of the head commit's tag:
git tag -v $(git describe)
The output of this command should indicate that the tag's signature is good and should NOT display any warnings. If warnings are displayed, you may have installed the Qubes Security Pack improperly (for example, by forgetting to install the Qubes Master Signing Key or failing to mark it as trusted). If you are told that a tag does not exist, the head commit hasn't been tagged by a Qubes OS developer, and you should use:
6. Back up one commit if a tag does not exist:
git checkout HEAD^
Then try to verify the repository's authenticity again. If the signature comes back bad, the repository is corrupted (or compromised) and should be discarded immediately.
7. Create a new file named builder.yml under the qubes-builderv2 directory, and fill it with the following contents:
include: - example-configs/kicksecure.yml qubes-release: r4.2 use-qubes-repo: version: 4.2
8. To build the template, run:
sudo ./qb package fetch prep build && sudo ./qb -t kicksecure-17 template fetch prep build
This will download the code needed to build the template and then build the template. If all goes well, the built template will be placed in folder:
qubes-builderv2/artifacts/templates/rpm
9. Copy the template RPM file to dom0:
Note: Substitute the real name of the RPM file (this name includes a timestamp and will thus be different for each build).
qvm-run --pass-io work-qubesos 'cat /home/user/qubes-builderv2/artifacts/templates/rpm/qubes-template-kicksecure...rpm' > qubes-template-kicksecure...rpm
10. Install the template with:
sudo qvm-template install --nogpgcheck ./qubes-template-kicksecure...rpm
WARNING: This action can execute arbitrary code as root on dom0! Only do this if you fully trust the App Qube used to build this template!
11. You should now see a kicksecure-17 template available in the application menu, under the "Templates" section.
Known Issues[edit]
Currently, the user account does not have sudo rights, not in the template and not in AppVMs based on the template. If you need to run commands as root, you should open a Qubes Root Console using qvm-run.
Icons seem to be missing from Thunar's context menu. This appears to be because of a configuration issue or missing package, but it is still not known why this is happening. Discussion thread at https://forum.xfce.org/viewtopic.php?pid=78113#p78113
There seem to be some missing fonts - view the Wikipedia home page in Firefox ESR and you'll see some characters fail to render properly. Similar things happen with desktop Kicksecure, so this isn't a blocker and can probably be fixed in both places at once if it's considered necessary to fix.
Resolved Issues[edit]
The Kicksecure repository used to not be enabled by default. The bug that was behind this has been resolved.
qubes-core-agent-networking is not pre-installed. As a result, AppVMs based on Kicksecure will have no Internet access. apt will still work inside of the template though. To resolve this, get a root shell within the template, and run apt install qubes-core-agent-networking.
qubes-core-agent-thunar is also not pre-installed, thus copying files from the Kicksecure AppVMs to other VMs will not work easily. This can be solved by installing it in the template. If Thunar's context menu still doesn't show inter-VM copying features after installing this, shut down the template and all AppVMs based on it, then boot a Kicksecure AppVM and run sudo rm -rf ~/.config/Thunar. Thunar should now show the correct buttons in this AppVM.
See Also[edit]
- Kicksecure for Qubes - User Documentation
- Qubes feature request: build Kicksecure Qubes Template #9573
- qubes-builder-v2 pull request: Add Kicksecure template support #170
Root Privilege Isolation and libxenvchan[edit]
Context: Qubes issue: Harden insecure permissions inside /dev/xen folder / research security impact of the Qubes /dev/xen folder permissions
Qubes OS currently uses an in-qube security model that essentially assumes that gaining root within an individual qube is not a risk. This makes sense, since Qubes OS is designed to enforce isolation with AppVMs, not user accounts. However, as a form of defense-in-depth, it is worthwhile to prevent software from being able to get passwordless root access within a qube even though this isn't directly useful for isolating data from an attacker. The main reason for this is that most attacks that would allow breaking out of a VM into dom0 require that an attacker be able to get root in a VM first. Making this a hurdle could at least significantly increase the difficulty of an attack and potentially save users from becoming compromised when they otherwise would have been.
In order to allow Qubes OS's qrexec functionality to work, Qubes OS currently allows all devices under /dev/xen inside of a qube to be accessed by any user in the group qubes. This group includes the default user account, user. The reason this is necessary is because qrexec uses Xen's libxenvchan to allow data transfer between VMs. libxenvchan uses Xen grants in the background, which are a mechanism for sharing memory pages between VMs. Sharing memory to other VMs and gaining access to memory shared by other VMs requires the ability to use the /dev/xen devices (specifically gntdev, gntalloc, and privcmd), so they have to be accessible by everything that works with qrexec, including things that don't or shouldn't run as root. Each grant has a grant reference, which is basically an ID number used to refer to that grant.
The issue with Xen grants is that they only secure inasmuch as a block of memory shared with a particular VM will only be able to be accessed by the specified VM. Xen's grants are guest-agnostic, and so while they do prevent a malicious guest from gaining access to another guest's shared memory, they do not prevent processes from interfering with each other's grants. There is no concept of processes in Xen grants; the guest has to "do the right thing" with the memory it gives and receives, whatever "the right thing" is in each context.
This can potentially be used to corrupt data. A malicious process in a VM can very likely guess the grant ID used by a privileged component of the system (such as blkfront, Xen's virtual disk driver), and use it in unexpected ways. For instance, blkfront uses grants to communicate with dom0 for allowing disk contents to be sent back and forth. If a malicious process can guess a grant used by blkfront, it can attempt to tell other things in dom0 to use that same grant for other purposes (for instance, providing it to dom0 for use with qrexec). This should usually result in an error since two things will be trying to use the same area of memory at the same time, but it can potentially result in data corruption, which could potentially be used to gain kernel-level privileges within a qube.
Preventing this within the Linux kernel will probably require a driver that can provide functionality similar to libxenvchan but without requiring grant functionality to be exposed directly. This would allow qrexec to function without requiring the grant management devices to be directly accessible to almost everything in a qube. The kernel would still use grants in the background, but they would be abstracted away from the end user, and channel IDs would be managed separately from grant references.
A secure by default operating system with the latest security research in place.
At
Kicksecure we value freedom and trust, supporting Open Source and Freedom Software
2012-
2025 ENCRYPTED SUPPORT LLC
We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!