Qubes Core Customization Study

Unofficial Qubes OS core-agent Linux customization fork focused on VM-level persistence behavior, firewall integration, systemd drop-ins, networking scripts, packaging targets, and safe review practices.

This repository is a public portfolio-oriented fork/study around Qubes OS core-agent Linux internals. It is not an official Qubes OS repository and should not be treated as production-ready Qubes infrastructure without upstream review and isolated testing.

The current default branch is arch-custom-persist, which highlights a customization-oriented workflow around Qubes VM agent behavior and persistence-sensitive runtime paths.

Why This Repository Exists

Qubes OS internals are security-sensitive. Small changes in VM agent scripts, firewall behavior, systemd units, networking hooks, or packaging targets can affect isolation, update flow, DNS handling, NetVM behavior, and user persistence expectations.

This repository is organized to show how such a low-level fork can be reviewed like an engineering project rather than a random patch dump:

• Document the branch intent clearly.
• Explain runtime boundaries.
• Treat firewall/networking changes as security-sensitive.
• Keep build/install targets visible.
• Provide review and test checklists.
• Avoid presenting experimental changes as official Qubes behavior.

Scope

The repository includes Qubes agent-side components such as:

• Python package metadata for qubesagent
• VM-level console scripts such as qubes-firewall and qubes-vmexec
• systemd drop-in installation targets
• SysV init compatibility targets
• networking and NetVM installation targets
• SELinux policy installation hooks
• Qubes firewall agent logic
• packaging-oriented build files

The version file currently reports 4.3.24.

Architecture Snapshot

Qubes VM runtime
  -> qubesagent Python components
  -> firewall / vmexec entrypoints
  -> systemd or SysV init integration
  -> networking and NetVM scripts
  -> QubesDB-driven runtime configuration
  -> packaging/install targets

Important files and directories:

Area	Purpose
setup.py	Python package metadata and generated console scripts
Makefile	Build, clean, install, systemd, networking, NetVM and SELinux targets
qubesagent/	Agent-side Python modules
qubesagent/firewall.py	Qubes firewall worker logic and runtime hooks
network/	Networking, NetVM, DNS/update proxy and firewall assets
vm-systemd/	systemd service and drop-in integration
vm-init.d/	SysV init compatibility scripts
selinux/	SELinux policy build/install area
doc/	Project documentation source from the base tree

More detail is available in docs/ARCHITECTURE.md.

Safety Notice

This repository touches security-sensitive operating system behavior. Do not test changes directly on personal, production, or high-value Qubes environments.

Recommended safety baseline:

1. Use disposable lab VMs.
2. Snapshot before testing.
3. Review firewall and networking changes line by line.
4. Test with non-sensitive data.
5. Keep a recovery path available.
6. Never claim unofficial behavior as upstream Qubes behavior.

See docs/SAFETY_AND_REVIEW.md.

Development and Review Workflow

Recommended workflow for this fork:

git checkout arch-custom-persist
git status
make clean
make all

For packaging or install-target review, inspect targets before running them:

make -n install-systemd
make -n install-networking
make -n install-netvm

Use dry-run style inspection first because install targets can write into system paths when DESTDIR is not set correctly.

Safer staged install pattern:

mkdir -p /tmp/qubes-core-staging
make DESTDIR=/tmp/qubes-core-staging install-common
make DESTDIR=/tmp/qubes-core-staging install-systemd
make DESTDIR=/tmp/qubes-core-staging install-networking

Quality Gates for Changes

Before considering a change ready:

• Build targets are reviewed.
• Generated files are not committed accidentally.
• Python changes are linted or at least syntax-checked.
• Shell scripts are reviewed for quoting/path assumptions.
• systemd unit/drop-in changes are reviewed for boot impact.
• firewall/networking behavior is tested in an isolated VM.
• packaging/install paths are tested with DESTDIR staging.
• GPLv2 licensing and upstream attribution are preserved.

Documentation

• Architecture
• Safety and review guide
• Custom persist branch notes
• Maintainer checklist

Non-Goals

This repository does not claim to be:

• an official Qubes OS upstream repository
• a hardened production release
• a replacement for upstream Qubes review
• a general-purpose Linux hardening toolkit
• a guide for bypassing Qubes isolation boundaries

License

The upstream code is licensed under the GNU General Public License v2. See LICENSE.

Attribution

Qubes OS is developed by the Qubes OS Project. This repository is an unofficial fork/study and should preserve upstream attribution and license notices.