Chapter 10. Protecting systems against intrusive USB devices
USB devices can be loaded with spyware, malware, or trojans, which can steal your data or damage your system. As a Red Hat Enterprise Linux administrator, you can prevent such USB attacks with USBGuard.
10.1. USBGuard
With the USBGuard software framework, you can protect your systems against intrusive USB devices by using basic lists of permitted and forbidden devices based on the USB device authorization feature in the kernel.
The USBGuard framework provides the following components:
- The system service component with an inter-process communication (IPC) interface for dynamic interaction and policy enforcement
-
The command-line interface to interact with a running
usbguard
system service - The rule language for writing USB device authorization policies
- The C++ API for interacting with the system service component implemented in a shared library
The usbguard
system service configuration file (/etc/usbguard/usbguard-daemon.conf
) includes the options to authorize the users and groups to use the IPC interface.
The system service provides the USBGuard public IPC interface. In Red Hat Enterprise Linux, the access to this interface is limited to only the root user by default.
Consider setting either the IPCAccessControlFiles
option (recommended) or the IPCAllowedUsers
and IPCAllowedGroups
options to limit access to the IPC interface.
Ensure that you do not leave the Access Control List (ACL) unconfigured because this exposes the IPC interface to all local users and allows them to manipulate the authorization state of USB devices and modify the USBGuard policy.
10.2. Installing USBGuard
Use this procedure to install and initiate the USBGuard framework.
Procedure
Install the
usbguard
package:# dnf install usbguard
Create an initial rule set:
# usbguard generate-policy > /etc/usbguard/rules.conf
Start the
usbguard
daemon and ensure that it starts automatically on boot:# systemctl enable --now usbguard
Verification
Verify that the
usbguard
service is running:# systemctl status usbguard ● usbguard.service - USBGuard daemon Loaded: loaded (/usr/lib/systemd/system/usbguard.service; enabled; vendor preset: disabled) Active: active (running) since Thu 2019-11-07 09:44:07 CET; 3min 16s ago Docs: man:usbguard-daemon(8) Main PID: 6122 (usbguard-daemon) Tasks: 3 (limit: 11493) Memory: 1.2M CGroup: /system.slice/usbguard.service └─6122 /usr/sbin/usbguard-daemon -f -s -c /etc/usbguard/usbguard-daemon.conf Nov 07 09:44:06 localhost.localdomain systemd[1]: Starting USBGuard daemon... Nov 07 09:44:07 localhost.localdomain systemd[1]: Started USBGuard daemon.
List USB devices recognized by USBGuard:
# usbguard list-devices 4: allow id 1d6b:0002 serial "0000:02:00.0" name "xHCI Host Controller" hash...
Additional resources
-
usbguard(1)
andusbguard-daemon.conf(5)
man pages on your system
10.3. Blocking and authorizing a USB device by using the CLI
You can set USBGuard to allow, block, or reject a specific USB device by using the usbguard
command in your terminal. This setting persists as long as USBGuard is running. USBGuard uses the terms block
and reject
with the following meanings:
block
- Do not interact with this device for now.
reject
- Ignore this device as if it does not exist.
Prerequisites
-
The
usbguard
service is installed and running.
Procedure
Determine the ID of the USB device by listing the devices recognized by USBGuard:
# usbguard list-devices 1: allow id 1d6b:0002 serial "0000:00:06.7" name "EHCI Host Controller" hash "JDOb0BiktYs2ct3mSQKopnOOV2h9MGYADwhT+oUtF2s=" parent-hash "4PHGcaDKWtPjKDwYpIRG722cB9SlGz9l9Iea93+Gt9c=" via-port "usb1" with-interface 09:00:00 ... 6: block id 1b1c:1ab1 serial "000024937962" name "Voyager" hash "CrXgiaWIf2bZAU+5WkzOE7y0rdSO82XMzubn7HDb95Q=" parent-hash "JDOb0BiktYs2ct3mSQKopnOOV2h9MGYADwhT+oUtF2s=" via-port "1-3" with-interface 08:06:50
Authorize a device to interact with the system:
# usbguard allow-device <ID>
Deauthorize and remove a device:
# usbguard reject-device <ID>
Deauthorize and retain a device:
# usbguard block-device <ID>
Additional resources
-
usbguard(1)
man page on your system -
Built-in help listed by using the
usbguard --help
command
10.4. Permanently blocking and authorizing a USB device
You can permanently block and authorize a USB device by using the -p
option. This adds a device-specific rule to the current policy and persists across restarts and reboots. USBGuard uses the terms block
and reject
with the following meanings:
block
- Do not interact with this device for now.
reject
- Ignore this device as if it does not exist.
Prerequisites
-
The
usbguard
service is installed and running.
Procedure
Configure SELinux to allow the
usbguard
daemon to write rules.Display the
semanage
Booleans relevant tousbguard
.# semanage boolean -l | grep usbguard usbguard_daemon_write_conf (off , off) Allow usbguard to daemon write conf usbguard_daemon_write_rules (on , on) Allow usbguard to daemon write rules
If the
usbguard_daemon_write_rules
Boolean is turned off, turn it on.# semanage boolean -m --on usbguard_daemon_write_rules
Determine the ID of the USB device by listing the devices recognized by USBGuard:
# usbguard list-devices 1: allow id 1d6b:0002 serial "0000:00:06.7" name "EHCI Host Controller" hash "JDOb0BiktYs2ct3mSQKopnOOV2h9MGYADwhT+oUtF2s=" parent-hash "4PHGcaDKWtPjKDwYpIRG722cB9SlGz9l9Iea93+Gt9c=" via-port "usb1" with-interface 09:00:00 ... 6: block id 1b1c:1ab1 serial "000024937962" name "Voyager" hash "CrXgiaWIf2bZAU+5WkzOE7y0rdSO82XMzubn7HDb95Q=" parent-hash "JDOb0BiktYs2ct3mSQKopnOOV2h9MGYADwhT+oUtF2s=" via-port "1-3" with-interface 08:06:50
Permanently authorize a device to interact with the system:
# usbguard allow-device <ID> -p
Permanently deauthorize and remove a device:
# usbguard reject-device <ID> -p
Permanently deauthorize and retain a device:
# usbguard block-device <ID> -p
Verification
Check that the USBGuard rules include the changes you made.
# usbguard list-rules
Additional resources
-
usbguard(1)
man page on your system -
Built-in help listed by using the
usbguard --help
command
10.5. Creating a custom policy for USB devices
The following procedure contains steps for creating a rule set for USB devices that reflects the requirements of your scenario.
Prerequisites
-
The
usbguard
service is installed and running. -
The
/etc/usbguard/rules.conf
file contains an initial rule set generated by theusbguard generate-policy
command.
Procedure
Create a policy which authorizes the currently connected USB devices, and store the generated rules to the
rules.conf
file:# usbguard generate-policy --no-hashes > ./rules.conf
The
--no-hashes
option does not generate hash attributes for devices. Avoid hash attributes in your configuration settings because they might not be persistent.In the
rules.conf
file, add, remove, or edit the rules as required by using a text editor. For example, the following rule allows only devices with a single mass storage interface to interact with the system:allow with-interface equals { 08:*:* }
See the
usbguard-rules.conf(5)
man page for a detailed rule-language description and more examples.Install the updated policy:
# install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
Restart the
usbguard
daemon to apply your changes:# systemctl restart usbguard
Verification
Check that your custom rules are in the active policy, for example:
# usbguard list-rules ... 4: allow with-interface 08:*:* ...
Additional resources
-
usbguard-rules.conf(5)
man page on your system
10.6. Creating a structured custom policy for USB devices
You can organize your custom USBGuard policy in several .conf
files within the /etc/usbguard/rules.d/
directory. The usbguard-daemon
then combines the main rules.conf
file with the .conf
files within the directory in alphabetical order.
Prerequisites
-
The
usbguard
service is installed and running.
Procedure
Create a policy which authorizes the currently connected USB devices, and store the generated rules to a new
.conf
file, for example,<policy.conf>
.# usbguard generate-policy --no-hashes > ./<policy.conf>
The
--no-hashes
option does not generate hash attributes for devices. Avoid hash attributes in your configuration settings because they might not be persistent.Open the
<policy.conf>
file with a text editor of your choice, and select the lines with the rules that you want to record, for example:... allow id 04f2:0833 serial "" name "USB Keyboard" via-port "7-2" with-interface { 03:01:01 03:00:00 } with-connect-type "unknown" ...
Copy the selected lines into a separate
.conf
file.NoteThe two digits at the beginning of the file name specify the order in which the daemon reads the configuration files.
For example, to copy the rules for your keyboards into a new
.conf
file:# grep "USB Keyboard" ./<policy.conf> > ./<10keyboards.conf>
Install the new policy to the
/etc/usbguard/rules.d/
directory.# install -m 0600 -o root -g root <10keyboards.conf> /etc/usbguard/rules.d/<10keyboards.conf>
Move the rest of the lines to the main
rules.conf
file.# grep -v "USB Keyboard" ./policy.conf > ./rules.conf
Install the remaining rules.
# install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
Restart the
usbguard
daemon to apply your changes.# systemctl restart usbguard
Verification
Display all active USBGuard rules.
# usbguard list-rules ... 15: allow id 04f2:0833 serial "" name "USB Keyboard" hash "kxM/iddRe/WSCocgiuQlVs6Dn0VEza7KiHoDeTz0fyg=" parent-hash "2i6ZBJfTl5BakXF7Gba84/Cp1gslnNc1DM6vWQpie3s=" via-port "7-2" with-interface { 03:01:01 03:00:00 } with-connect-type "unknown" ...
Display the contents of the
rules.conf
file and all the.conf
files in the/etc/usbguard/rules.d/
directory.# cat /etc/usbguard/rules.conf /etc/usbguard/rules.d/*.conf
- Verify that the active rules contain all the rules from the files and are in the correct order.
Additional resources
-
usbguard-rules.conf(5)
man page.
10.7. Authorizing users and groups to use the USBGuard IPC interface
By default, only the root user can use the USBGuard public IPC interface interface. You can authorize a specific user or a group to use this interface in addition to root. You can do that either by editing the /etc/usbguard/usbguard-daemon.conf
file or by using the usbguard add-user
subcommand.
Prerequisites
-
The
usbguard
service is installed and running. -
The
/etc/usbguard/rules.conf
file contains an initial rule set generated by theusbguard generate-policy
command.
Procedure
Edit the
/etc/usbguard/usbguard-daemon.conf
file with the rules you want to add. For example, to allow all users in thewheel
group to use the IPC interface, add this line:IPCAllowGroups=wheel
You can add users or groups also with the
usbguard
command. For example, the following command enables a user to have full access to theDevices
andExceptions
sections and to list and modify the current policy:# usbguard add-user <user_name> --devices ALL --policy modify,list --exceptions ALL
Replace
<user_name>
with the user name that should receive these permissions.You can remove the granted permissions for a user by using the
usbguard remove-user <user_name>
command.Restart the
usbguard
daemon to apply your changes:# systemctl restart usbguard
Additional resources
-
usbguard(1)
andusbguard-rules.conf(5)
man pages
10.8. Logging USBguard authorization events to the Linux Audit log
By default, the usbguard
daemon logs events to the /var/log/usbguard/usbguard-audit.log
file. You can integrate logging of USBguard authorization events to the standard Linux Audit log.
Prerequisites
-
The
usbguard
service is installed and running. -
The
auditd
service is running.
Procedure
In the
/etc/usbguard/usbguard-daemon.conf
file, change theAuditBackend
option fromFileAudit
toLinuxAudit
:AuditBackend=LinuxAudit
Restart the
usbguard
daemon to apply the configuration change:# systemctl restart usbguard
Verification
Query the
audit
daemon log for a USB authorization event, for example:# ausearch -ts recent -m USER_DEVICE
Additional resources
-
usbguard-daemon.conf(5)
man page on your system.
10.9. Additional resources
-
usbguard(1)
,usbguard-rules.conf(5)
,usbguard-daemon(8)
, andusbguard-daemon.conf(5)
man pages on your system. - USBGuard Homepage.