Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 14. 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.

14.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.

Important

The system service provides the USBGuard public IPC interface. In Red Hat Enterprise Linux, the access to this interface is limited to the root user only 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 as 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.

14.2. Installing USBGuard

Use this procedure to install and initiate the USBGuard framework.

Procedure

  1. Install the usbguard package:

    # yum install usbguard
  2. Create an initial rule set:

    # usbguard generate-policy > /etc/usbguard/rules.conf
  3. Start the usbguard daemon and ensure that it starts automatically on boot:

    # systemctl enable --now usbguard

Verification

  1. 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.
  2. 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) and usbguard-daemon.conf(5) man pages.

14.3. Blocking and authorizing a USB device by using CLI

You can set USBGuard to authorize and block a USB device by using the usbguard command in your terminal.

Prerequisites

  • The usbguard service is installed and running.

Procedure

  1. List USB devices recognized by USBGuard, for example:

    # 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
  2. Authorize the device <6> to interact with the system:

    # usbguard allow-device <6>
  3. Deauthorize and remove the device <6>:

    # usbguard reject-device <6>
  4. Deauthorize and retain the device <6>:

    # usbguard block-device <6>
Note

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.

Additional resources

  • usbguard(1) man page
  • usbguard --help command

14.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.

Prerequisites

  • The usbguard service is installed and running.

Procedure

  1. Configure SELinux to allow the usbguard daemon to write rules.

    1. Display the semanage Booleans relevant to usbguard.

      # 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
    2. Optional: If the usbguard_daemon_write_rules Boolean is turned off, turn it on.

      # semanage boolean -m --on usbguard_daemon_write_rules
  2. List USB 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
  3. Permanently authorize device 6 to interact with the system:

    # usbguard allow-device 6 -p
  4. Permanently deauthorize and remove device 6:

    # usbguard reject-device 6 -p
  5. Permanently deauthorize and retain device 6:

    # usbguard block-device 6 -p
Note

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.

Verification

  1. Check that USBGuard rules include the changes you made.

    # usbguard list-rules

Additional resources

  • usbguard(1) man page.
  • Built-in help listed by using the usbguard --help command.

14.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 the usbguard generate-policy command.

Procedure

  1. 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.

  2. Edit the rules.conf file with a text editor of your choice, for example:

    # vi ./rules.conf
  3. Add, remove, or edit the rules as required. 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.

  4. Install the updated policy:

    # install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
  5. Restart the usbguard daemon to apply your changes:

    # systemctl restart usbguard

Verification

  1. 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.

14.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

  1. 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.

  2. Display the policy.conf file with a text editor of your choice, for example:

    # vi ./policy.conf
    ...
    allow id 04f2:0833 serial "" name "USB Keyboard" via-port "7-2" with-interface { 03:01:01 03:00:00 } with-connect-type "unknown"
    ...
  3. Move selected lines into a separate .conf file.

    Note

    The two digits at the beginning of the file name specify the order in which the daemon reads the configuration files.

    For example, copy the rules for your keyboards into a new .conf file.

    # grep "USB Keyboard" ./policy.conf > ./10keyboards.conf
  4. 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
  5. Move the rest of the lines to a main rules.conf file.

    # grep -v "USB Keyboard" ./policy.conf > ./rules.conf
  6. Install the remaining rules.

    # install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
  7. Restart the usbguard daemon to apply your changes.

    # systemctl restart usbguard

Verification

  1. 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"
    ...
  2. 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
  3. 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.

14.7. Authorizing users and groups to use the USBGuard IPC interface

Use this procedure to authorize a specific user or a group to use the USBGuard public IPC interface. By default, only the root user can use this interface.

Prerequisites

  • The usbguard service is installed and running.
  • The /etc/usbguard/rules.conf file contains an initial rule set generated by the usbguard generate-policy command.

Procedure

  1. Edit the /etc/usbguard/usbguard-daemon.conf file with a text editor of your choice:

    # vi /etc/usbguard/usbguard-daemon.conf
  2. For example, add a line with a rule that allows all users in the wheel group to use the IPC interface, and save the file:

    IPCAllowGroups=wheel
  3. You can add users or groups also with the usbguard command. For example, the following command enables the joesec user to have full access to the Devices and Exceptions sections. Furthermore, joesec can list and modify the current policy:

    # usbguard add-user joesec --devices ALL --policy modify,list --exceptions ALL

    To remove the granted permissions for the joesec user, use the usbguard remove-user joesec command.

  4. Restart the usbguard daemon to apply your changes:

    # systemctl restart usbguard

Additional resources

  • usbguard(1) and usbguard-rules.conf(5) man pages.

14.8. Logging USBguard authorization events to the Linux Audit log

Use the following steps to integrate logging of USBguard authorization events to the standard Linux Audit log. By default, the usbguard daemon logs events to the /var/log/usbguard/usbguard-audit.log file.

Prerequisites

  • The usbguard service is installed and running.
  • The auditd service is running.

Procedure

  1. Edit the usbguard-daemon.conf file with a text editor of your choice:

    # vi /etc/usbguard/usbguard-daemon.conf
  2. Change the AuditBackend option from FileAudit to LinuxAudit:

    AuditBackend=LinuxAudit
  3. Restart the usbguard daemon to apply the configuration change:

    # systemctl restart usbguard

Verification

  1. 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.

14.9. Additional resources

  • usbguard(1), usbguard-rules.conf(5), usbguard-daemon(8), and usbguard-daemon.conf(5) man pages.
  • USBGuard Homepage.