Difference between revisions of "USBGuard"

From ArchWiki
Jump to navigation Jump to search
(further explanations)
(→‎Rules: all rules explained)
Line 20: Line 20:
 
To configure usbguard to your needs, you can edit {{ic|/etc/usbguard/rules.conf}}. The rules syntax is formally explained [https://github.com/dkopecek/usbguard#rule-language here].
 
To configure usbguard to your needs, you can edit {{ic|/etc/usbguard/rules.conf}}. The rules syntax is formally explained [https://github.com/dkopecek/usbguard#rule-language here].
 
An example for a hp printer connected via USB can look like this:
 
An example for a hp printer connected via USB can look like this:
 +
 
{{ic|<nowiki>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 }</nowiki>}}
 
{{ic|<nowiki>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 }</nowiki>}}
 +
 +
A rule begins with a policy. {{ic|allow}} whitelists a device, {{ic|block}} stops the device from being processed now and {{ic|reject}} removes the device from the system.
 +
Then follows a set of attributes with their options, as detailed below.
 +
 +
{| class="wikitable"
 +
! 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.
 +
 +
|}
  
 
== Weblinks ==
 
== Weblinks ==

Revision as of 13:21, 18 August 2016

This software allows one to implement a white/black-listing mechanism for usb-devices. Inspiration for this is drawn from exploits like BadUSB. It consists of

Installation

Install usbguardAUR or usbguard-gitAUR.

Configuration

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

Start the deamon usbguard.service.

Usage

USBGuard has a core deamon, a CLI, a QT GUI, a DBUS interface and an API via libusbguard.

Rules

To configure usbguard to your needs, you can edit /etc/usbguard/rules.conf. 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.

Weblinks