How to whitelist specific USB keyboard (USBGuard)?


is it possible to whitelist the main used USB keyboard according to its inherent device identifiers, to prevent other malicious USB devices impersonate as keyboards?

In current setup I am using a disposable USB qube for all devices with an USB keyboard needed to be shared on a single USB controller. I’ve noticed, all USB keyboards get accepted without any confirmation. Being aware, that at least one “main” keyboard is needed to unlock LUKS/Full-disk encryption, said whitelist might be created 1. manually 2. via an option at Qubes OS installation time 3. at early boot time for current boot to remember the accepted keyboard.

Of course device identifiers might be spoofed - but a malicious USB device at least would need to discover which ones have been whitelisted, and need to take additional effort. For me that sounds good enough in most cases.

Is there already a solution in Qubes OS to whitelist USB keyboards in some way via USBGuard (IIRC Qubes already has it installed)? Otherwise: How might I do this with USBGuard in general, if possible at all? Also please tell me, if the whole idea is non-sense and based on wrong assumptions security-wise.


– I am not an expert, I have some experience with usbguard –

Make sure that you understand usbguard before moving on to not make it more insecure than it is. Further, I am sadly also not sure if there are other possibilities of infecting sys-usb, even with usbguard.

Seems like you have to install usbguard on the main template (fedora or debian-12-xfce, depends on your choice during install) to use it. You then have two installations of it (in dom0 and main template)

As far as I know (haven’t tried), you could generate an “allow” rule for usbguard on the sys-usb for all currently plugged in devices. This rule, you could then copy to the corresponding folder in the template of its disposable template (e.g. fedora or debian-12-xfce), depends on your choice during installation. Make sure that you have a trusted version of sys-usb as you copy from untrusted to template…

Now every Qube that is based on the changed template should have the “allow”-rule for usbguard for this keyboard with it’s hardware properties, of course test this instead of trusting me, I didn’t do this with Qubes so far. Also don’t forget to shutdown the Template and restart sys-usb for the changes to take effect.

As far as I understand it, this should now not allow a malicious usb / keyboard to connect to sys-usb and therefore the allowance rule for keyboards to connect automatically from sys-usb to dom0 isn’t used, as the device isn’t even really connected.

In case you get locked out: in the GRUB startup press “e” and replace usbcore.authorized_default=0 with qubes.skip_autostart.
I don’t know if that’s the recommended way to do it. But it already saved me from a reinstall. Afaik, it skips the startup of sys-usb, connects the devices directly to dom0 and therefore enables you to further use your keyboard. Don’t use this normally. After this, I would fix the config, shutdown and on boot up make sure that the GRUB is back to normal again.

Good luck!
Please tell us about your progress, I would be very interested in this config as well!

The config files are in /etc/usbguard in dom0

You can use usbguard list-devices and add the id of your keyboard 02-qubes.conf with allow permissions.

When you have added your keyboard id, edited /etc/usbguard/rules.d/02-qubes.conf and edit/remove the HID access rule.

The HID rule includes both mouse and keyboard, if you remove it you need the add the id for your mouse as well.

Doing this might have some negative impact, some devices have legit reasons to act like a keyboard.

Just to make sure: I am simply not experienced enough to say, if your statements about security are correct. Just trying to explain my proposal for a “selfmade” solution.

@boreas Thanks for these instructions! Guess I need to elaborate a bit more on USBGuard beforehand. I was hoping for a maintenance-friendly version integrated into Qubes.

Maybe targeted morge at Qubes developers:
As USBGuard is already installed in dom0, I am certain you have thought about hardening cases to make USB keyboards safer. E.g. has there been a reason to not provide an additional option in Global Settings for whitelisting keyboard devices?

I have an old PS/2 keyboard for these PITA cases at hand :slight_smile: .

Hm executing usbguard list-devices in dom0 doesn’t show me any entry. I think this might be due to USB controllers assigned to the USB qube?

Yes, it needs to be the VM with the USB controller attached. I don’t think sys-usb has usbguard enabled, which is why I thought you were using a controller attached to dom0.

1 Like

Maybe take a look at these links:

(At the end of the presentation he makes a small showcase of usbguard)

Afaik for the USB controller:
During boot, it’s attached to dom0 for LUKS decryption if you chose usb-keyboard for unlocking. (Maybe also in general, idk. I think it’s a strong suggestion that you don’t have untrusted / unnecessary devices plugged in during boot and shutdown.)
As soon as sys-usb is started, the controller get transferred there.

Also be sure to know that even if you proxy things from sys-usb to dom0 (you probably get asked for this if you plug in a mouse and it’s not allowed by default), sys-usb is still perfectly able to eavesdrop on what you type!

Even though, it is hopefully not able to do anything with it (as long as no data is transferred to other VMs and the network connection (its net-qube) is down).
Things probably get darker, if the USB-device itself can phone home or it’s unplugged by the attacker with logged keys afterwards. Afaik, also at least all other devices that are connected to this VM are of course at risk for whatever the attacker has planned.


Yes, this totally makes sense.

Yeah, but this would be a slightly different case. If sys-usb gets infected, it potentially has control over all connected USB controllers. In theory sys-usb might even be able to corrupt controller’s firmware, but let’s neglect the fact here. This is is where separate USB controllers can help: controller-1 for keyboard/mouse input, assigned to sys-usb-1; controller-2 for other devices, assigned to sys-usb-2. Also enforce ask action for qubes.InputKeyboard policy of USB devices within sys-usb-2.

For OP case let’s assume one USB controller connected to sys-usb and a malicious USB device just wanting to act like a keyboard and not corrupting sys-usb for complete control over the VM.

(Of course it would be best to combine both USB controller separation + USB device whitelist for max. security, if possible.)

1 Like

Alright, sorry! Didn’t want to get Off-Topic there, just clarifying things.