USBGuard
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
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
-
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
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/.