USBGuard

Table of Contents

• About
• Documentation
• Compilation & Installation
• Before the First Start
• License

About

USBGuard is a software framework for implementing USB device authorization policies (what kind of USB devices are authorized) as well as method of use policies (how a USB device may interact with the system). Simply put, it is a USB device allowlisting tool.

Documentation

• User Guide (TBA)

• Manual Pages

  • usbguard-daemon(8)

  • usbguard-daemon.conf(5)

  • usbguard-rules.conf(5)

  • usbguard(1)

  • usbguard-dbus(8)

Compilation & Installation

Warning

Prior to starting the USBGuard daemon (or service) for the first time (but after installation) we need to generate a rules file for USBGuard so that the currently attached USB devices (in particular mouse and keyboard) keep working so that you will not get locked out of your system. More on that below at Before the First Start.

To compile the source code, you will require at least C++17.
If you are compiling sources from a release tarball, you’ll need the development files for:

• libqb - used for local UNIX socket based IPC

• protobuf - used for IPC message (de)serialization

• libsodium or libgcrypt - used for hashing

• asciidoc (a2x) - needed to generate documentation

Optionally, you may want to install:

• libseccomp - used to implement a syscall allowlist

• libcap-ng - used to drop process capabilities

If you are on a Debian based GNU/Linux distribution like Ubuntu 21.10, installation of all build dependencies would be something like this:

$ sudo apt update && \
  sudo apt install --no-install-recommends -V \
    asciidoc autoconf automake bash-completion build-essential catch2 \
    docbook-xml docbook-xsl git ldap-utils libaudit-dev libcap-ng-dev \
    libdbus-glib-1-dev libldap-dev libpolkit-gobject-1-dev libprotobuf-dev \
    libqb-dev libseccomp-dev libsodium-dev libtool libxml2-utils \
    libumockdev-dev pkg-config protobuf-compiler sudo tao-pegtl-dev xsltproc

And then do:

$ ./configure        # for arguments of interest see below
$ make
$ make check         # if you would like to run the test suite
$ sudo make install

Configure arguments that deserve explicit mentioning (quoting ./configure --help output):

--enable-systemd        install the systemd service unit file (default=no)

--with-crypto-library   Select crypto backend library. Supported values:
                        sodium, gcrypt, openssl.

--with-bundled-catch    Build using the bundled Catch library

--with-bundled-pegtl    Build using the bundled PEGTL library

--with-ldap             Build USBGuard with ldap support

If you want to compile the sources in a cloned repository, you’ll have to run the ./autogen.sh script. It will fetch the sources (via git submodules) of PEGTL and Catch. The script will then initialize the autotools based build system, e.g. generate the ./configure script.

Before the First Start

Prior to starting the USBGuard daemon (or service) for the first time (but after installation) we need to generate a rules file for USBGuard so that the currently attached USB devices (in particular mouse and keyboard) keep working so that you will not get locked out of your system.

A rules file can be generated like this:

$ sudo sh -c 'usbguard generate-policy > /etc/usbguard/rules.conf'

After that, you can safely start service usbguard:

$ sudo systemctl start usbguard.service

And you can make systemd start the service every time your boot your machine:

$ sudo systemctl enable usbguard.service

License

Copyright © 2015-2019 Red Hat, Inc.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.