Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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

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

11.2. Installing USBGuard

Use this procedure to install and initiate the USBGuard framework.

Procedure

  1. Install the usbguard package: 

    # dnf install usbguard
    Copy to Clipboard

  2. Create an initial rule set: 

    # usbguard generate-policy > /etc/usbguard/rules.conf
    Copy to Clipboard

  3. Start the usbguard daemon and ensure that it starts automatically on boot: 

    # systemctl enable --now usbguard
    Copy to Clipboard

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.
    Copy to Clipboard

  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...
    Copy to Clipboard

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

  1. 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
    Copy to Clipboard

  2. Authorize a device to interact with the system: 

    # usbguard allow-device <ID>
    Copy to Clipboard

  3. Deauthorize and remove a device: 

    # usbguard reject-device <ID>
    Copy to Clipboard

  4. Deauthorize and retain a device: 

    # usbguard block-device <ID>
    Copy to Clipboard

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

  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
      Copy to Clipboard

    2. If the usbguard_daemon_write_rules Boolean is turned off, turn it on. 

      # semanage boolean -m --on usbguard_daemon_write_rules
      Copy to Clipboard

  2. 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
    Copy to Clipboard

  3. Permanently authorize a device to interact with the system: 

    # usbguard allow-device <ID> -p
    Copy to Clipboard

  4. Permanently deauthorize and remove a device: 

    # usbguard reject-device <ID> -p
    Copy to Clipboard

  5. Permanently deauthorize and retain a device: 

    # usbguard block-device <ID> -p
    Copy to Clipboard

Verification

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

    # usbguard list-rules
    Copy to Clipboard

11.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
    Copy to Clipboard

    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. 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:*:* }
    Copy to Clipboard

    See the usbguard-rules.conf(5) man page for a detailed rule-language description and more examples.

  3. Install the updated policy: 

    # install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
    Copy to Clipboard

  4. Restart the usbguard daemon to apply your changes: 

    # systemctl restart usbguard
    Copy to Clipboard

Verification

  1. Check that your custom rules are in the active policy, for example: 

    # usbguard list-rules
...
4: allow with-interface 08:*:*
...
    Copy to Clipboard

11.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>
    Copy to Clipboard

    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. 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 to Clipboard

  3. Copy the 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, to copy the rules for your keyboards into a new .conf file: 

    # grep "USB Keyboard" ./<policy.conf> > ./<10keyboards.conf>
    Copy to Clipboard

  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>
    Copy to Clipboard

  5. Move the rest of the lines to the main rules.conf file. 

    # grep -v "USB Keyboard" ./policy.conf > ./rules.conf
    Copy to Clipboard

  6. Install the remaining rules. 

    # install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
    Copy to Clipboard

  7. Restart the usbguard daemon to apply your changes. 

    # systemctl restart usbguard
    Copy to Clipboard

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"
...
    Copy to Clipboard

  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
    Copy to Clipboard
  3. Verify that the active rules contain all the rules from the files and are in the correct order.

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

Procedure

  1. Edit the /etc/usbguard/usbguard-daemon.conf file with the rules you want to add. For example, to allow all users in the wheel group to use the IPC interface, add this line: 

    IPCAllowGroups=wheel
    Copy to Clipboard

  2. You can add users or groups also with the usbguard command. For example, the following command enables a user to have full access to the Devices and Exceptions sections and to list and modify the current policy: 

    # usbguard add-user <user_name> --devices ALL --policy modify,list --exceptions ALL
    Copy to Clipboard

    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.

  3. Restart the usbguard daemon to apply your changes: 

    # systemctl restart usbguard
    Copy to Clipboard

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

  1. In the /etc/usbguard/usbguard-daemon.conf file, change the AuditBackend option from FileAudit to LinuxAudit: 

    AuditBackend=LinuxAudit
    Copy to Clipboard

  2. Restart the usbguard daemon to apply the configuration change: 

    # systemctl restart usbguard
    Copy to Clipboard

Verification

  1. Query the audit daemon log for a USB authorization event, for example: 

    # ausearch -ts recent -m USER_DEVICE
    Copy to Clipboard
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat