Objective: Be able to visualize your configuration using qvm-ls-mermaid like this: https://github.com/3hhh/qvm-ls-mermaid/blob/master/examples/1.png
, but without trusting it in dom0 🙂
qvm-ls-mermaid is written by 3hhh/tripleh and can be installed in dom0. And while we don't specifically distrust tripleh, we don't necessarily trust him either. (Sorry @tripleh ! :) ).
The idea is that instead of doing a security review of each line of code in qvm-ls-mermaid, and blib and installing it in dom0, we isolate it by putting it in its own qube with read only access to the qubes configuration information, and no network access. (If you disagree with being able to skip the security review for a code, please add your comments below)
Steps for creating the sys-admin-mermaid qube: 1. Install these in your template: * qubes-core-admin-client * qubes-manager * python3-qrexec * python3-networkx 2. Then create a new vm based on that template, with internet access enabled.
A CLI example could be (depending on your setup):
qvm-run debian-12 'sudo apt update'
qvm-run debian-12 'sudo apt install qubes-core-admin-client qubes-manager python3-qrexec'
qvm-run debian-12 'sudo apt install python3-networkx'
qvm-shutdown debian-12
qvm-create --template debian-12 --property netvm=sys-firewall-internet --label gray sys-admin-mermaid
Part 2: Install qvm-ls-mermaid open a terminal in the new vm and run:
git clone --recurse-submodules https://github.com/3hhh/qvm-ls-mermaid.git git clone --recurse-submodules https://github.com/3hhh/blib.git
Part 3: disable the networking.
A CLI example would be:
qvm-prefs sys-admin-mermaid netvm none
Part 4: Fix dependancy checks:
Still in the VMs terminal, add losetup to the users parth. One way is:
sudo ln -s /usr/sbin/losetup /usr/local/bin/
Next, create a "qvm-block" command.
sudo ln -s /usr/bin/qvm-device /usr/local/bin/qvm-block
Note: The need to do this (I.E. that /usr/bin/qvm-block link to /usr/bin/qvm-device is not automatically created) has been reported as a possible qubes-core-admin-client bug: https://github.com/QubesOS/qubes-issues/issues/8786 . If it is a bug, it's possible it's been solved by the time you read this and that this step is unnecessary)
Part 5: setup blib
(This currently needs to be run every time you start sys-admin-mermaid since it installs in /usr/lib)
cd ~/blib/; sudo ./installer install /usr/local/lib
Part 6 actually running it Part 6a set up permissions for getting it in a automated way You can set it up for a more automated version, by adding policies for the admin API in dom0. By putting
sys-admin-mermaid $adminvm allow,target=$adminvm
sys-admin-mermaid $anyvm allow,target=$adminvm
In the following files:
/etc/qubes-rpc/policy/admin.vm.List
/etc/qubes-rpc/policy/admin.vm.property.Get
/etc/qubes-rpc/policy/admin.vm.property.GetAll
/etc/qubes-rpc/policy/admin.property.List
/etc/qubes-rpc/policy/admin.property.Get
/etc/qubes-rpc/policy/admin.property.GetAll
/etc/qubes-rpc/policy/policy.List
Discussion points: Feel free to comment on this Here are some possible points people may want to argue about at this point :)
/etc/qubes-rpc/policy/ and not in /etc/qubes/policy.d/ ( related: https://github.com/QubesOS/qubes-issues/issues/8000 )Part 6a: continued Finally, inside the sys-admin-mermaid qube terminal, do:
cd ~/qvm-ls-mermaid
./qvm-ls-mermaid dom0 > mermaid/qvm-ls-mermaid.js
cd mermaid
./run
Part 6b: If that worked, then make it do more If the previous command worked, then try to add more features (like "show details of the VM" or "show what templates are used for what VMs"), via command line options to qvm-ls-mermaid
cd ~/qvm-ls-mermaid
./qvm-ls-mermaid dom0 -t -T -v -D > mermaid/qvm-ls-mermaid.js
cd mermaid
./run
You may notice that the qubes and arrows are being displayed like in the example, but things like "Policy Group 5" are missing.
Well in theory, we could set up permissions for it to show the policies too, then use the "-R" option for qvm-ls-mermaid, like:
cd ~/qvm-ls-mermaid
./qvm-ls-mermaid -R dom0 > mermaid/qvm-ls-mermaid.js
cd mermaid
./run
qrexec-policy-graph --include-ask
returning:
Traceback (most recent call last):
File "/usr/bin/qrexec-policy-graph", line 5, in <module>
sys.exit(main())
File "/usr/lib/python3/dist-packages/qrexec/tools/qrexec_policy_graph.py", line 125, in main
system_info = utils.get_system_info()
File "/usr/lib/python3/dist-packages/qrexec/utils.py", line 119, in get_system_info
system_info = qubesd_call("dom0", "internal.GetSystemInfo")
File "/usr/lib/python3/dist-packages/qrexec/utils.py", line 80, in qubesd_call
client_socket.connect(socket_path)
FileNotFoundError: [Errno 2] No such file or directory )
Anyway, this is what the manual procedure is for. You can log into dom0 terminal and type:
qvm-ls --raw-data -O name,CLASS,label,netvm,provides_network,template,template_for_dispvms,virt_mode > qvmls.txt && qrexec-policy-graph --include-ask > qpol.txt
qvm-copy-to-vm sys-admin-mermaid qvmls.txt qpol.txt
Then go to the sys-admin-mermaid shell and run:
cd ~/qvm-ls-mermaid
( cat ~/QubesIncoming/dom0/qvmls.txt ; ./prune-policy-graph < ~/QubesIncoming/dom0/qpol.txt ) | ./qvm-ls-mermaid -R --vm > mermaid/qvm-ls-mermaid.js
cd mermaid ; ./run
Issues Left Layout Issues: The layout looks fine with a reasonable number of qubes, but if you have too many qubes the layout can start looking strange. (for a example of "too many" qubes, it looks quite strange with 110 qubes) (and by "strange" I mean that when zoomed in enough to read the name of the 110 qubes, most qubes are in one big horizontal line going way beyond the edge of the screen)
If you have many qubes and need it to look better, one option might be to upgrade the mermaid library to a newer version that supports the new "elk" rendering engine, then edit your qvm-ls-mermaid.js file to use the new elk engine as described here: https://mermaid.js.org/syntax/flowchart.html#renderer
Syntax Error Issues:
If you don't see a graph, and instead it just says "syntax error" in the browser, the problem might be that you have "--" (I.E. double-hyphens) in your qube names. editing the qube names in the qvm-ls-mermaid.js file is one option to get rid of them)
Making it look prettier!:
If you want to change how it looks, you can edit the qvm-ls-mermaid.js flowchart description file using the syntax specified here: https://mermaid.js.org/syntax/flowchart.html#renderer .
Tip: If you edit qvm-ls-mermaid.js, make sure you keep a original copy of your file so you can do a diff later when you need to remember what you changed.
Looking for comments on:
qrexec-policy-graph --include-ask to run from inside a qube!