USBGuard

From ArchWiki
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

USBGuard offers a white/black-listing mechanism for USB-devices. Inspiration for this is drawn from exploits like BadUSB. It makes use of a device blocking infrastructure included in the Linux kernel and consists of a daemon and some front-ends.

Installation

Install the usbguard package, or usbguard-gitAUR for the development version.

The official Qt applet was removed from USBGuard and substituted with usbguard-notifierAUR. An unofficial, forked version of the Qt applet is available as usbguard-applet-qtAUR.

Configuration

The main configuration file is found in /etc/usbguard/usbguard-daemon.conf.

If you want to control the daemon via IPC, be sure to add your username to IPCAllowedUsers or your group to IPCAllowedGroups to make rules persistent. In most cases, you want this.

By default, the PresentDevicePolicy is set to apply-policy so that USBGuard evaluates the ruleset for every connected device. This is the most secure setting, which ensures security even when the daemon hits a restart. Alternatively, the key may be set to allow in order to block all newly connected devices but leave devices connected before daemon as is.

With the key ImplicitPolicyTarget you can configure the default treatment of devices, if no rules match. The most secure option here is block.

For an in-depth documentation of configuration see the very well commented configuration file.

Usage

USBGuard has a core daemon, a CLI, a DBUS interface and an API via libusbguard.

Warning: Make sure to actually configure the daemon before starting/enabling it or all USB devices will immediately be blocked!

If you want to use the Qt GUI or another program communicating via DBUS, enable and start usbguard-dbus.service.

If you only want to communicate via API (with the CLI tool or another software using libusbguard) enable and start usbguard.service.

The CLI is available via usbguard.

See the according man pages for more info.

Rules

To configure USBGuard to your needs, you can edit /etc/usbguard/rules.conf. However manual editing of the rules is normally not necessary. You can generate a ruleset based on your currently attached USB devices by executing usbguard generate-policy > /etc/usbguard/rules.conf as root.

The rules syntax is formally explained here. An example for a hp printer connected via USB can look like this: 

allow id 03f0:0c17 serial "00CNFD234631" name "hp LaserJet 2020" hash "a0ef07fceb6fb77698f79a44a450121m" parent-hash "69d19c1a5733a31e7e6d9530e6k434a6" with-interface { 07:01:03 07:01:02 07:01:01 }

A rule begins with a policy. allow whitelists a device, block stops the device from being processed now and reject removes the device from the system. Then follows a set of attributes with their options, as detailed below.

Attribute Description
id usb-device-id Match a USB device ID.
id [operator] { usb-device-id ... } Match a set of USB device IDs.
hash "value" Match a hash computed from the device attribute values and the USB descriptor data. The hash is computed for every device by USBGuard.
hash [operator] { "value" ... } Match a set of device hashes.
parent-hash "value" Match a hash of the parent device.
parent-hash [operator] { "value" ... } Match a set of parent device hashes.
name "device-name" Match the USB device name attribute.
name [operator] { "device-name" ... } Match a set of USB device names.
serial "serial-number" Match the USB iSerial device attribute.
serial [operator] { "serial-number" ... } Match a set of USB iSerial device attributes.
via-port "port-id" Match the USB port through which the device is connected. Note that some systems have unstable port numbering which change after the system reboots or certain kernel modules are reloaded (and maybe in other cases). Use the parent-hash attribute if you want to ensure that a device is connected via a specific parent device.
via-port [operator] { "port-id" ... } Match a set of USB ports.
with-interface interface-type Match an interface type that the USB device provides.
with-interface [operator] { interface-type interface-type ... } Match a set of interface types against the set of interfaces that the USB device provides.

See also