USBGuard USB Device Allowlisting for Linux

USBGuard's Device and Method-of-Use Policies

USBGuard solves a specific host-security problem: deciding which USB hardware should be trusted on a Linux system. The README describes two related policy categories. Device authorization policies determine what kind of USB devices are authorized. Method-of-use policies determine how an authorized device may interact with the host. The project describes itself as a USB device allowlisting tool, so its default policy direction is restrictive rather than inventory-only.

The intended operator is a system administrator or Linux security engineer who wants policy enforcement outside an individual application. This matters on systems where accepting an unfamiliar keyboard, storage device, or other peripheral could weaken control over the machine. USBGuard is not documented as a general endpoint management suite. Its scope is USB authorization, with optional process controls supplied by libraries such as `libseccomp` and `libcap-ng`.

The repository supports that scope through a daemon, a command-line interface, D-Bus documentation, configuration files, rules files, and manual pages. The named references include `usbguard-daemon(8)`, `usbguard-daemon.conf(5)`, `usbguard-rules.conf(5)`, `usbguard(1)`, and `usbguard-dbus(8)`. That documentation split suggests a system service with separate operational and policy configuration, although the cleaned README does not reproduce the full rule grammar or D-Bus workflow.

USBGuard Daemon Architecture and Dependencies

USBGuard separates policy enforcement from client interaction through a daemon and local IPC. According to the README, `libqb` provides UNIX socket based IPC, while `protobuf` handles IPC message serialization and deserialization. This means the daemon can exchange structured messages with client software rather than operating only as an in-process library.

The repository layout includes `src/`, `doc/`, `scripts/`, `usbguard-daemon.conf.in`, `usbguard.service.in`, and build files such as `configure.ac` and `Makefile.am`. The source tree therefore contains both runtime components and generated integration inputs. The `.in` suffix on the daemon configuration and service unit indicates that installation can substitute build-specific values into those files, although the README does not enumerate those substitutions.

Cryptographic support is selectable through `--with-crypto-library`, whose documented values are `sodium`, `gcrypt`, and `openssl`. The release-tarball dependency list identifies `libsodium` or `libgcrypt` as libraries used for hashing. Optional `libseccomp` implements a syscall allowlist, and optional `libcap-ng` is used to drop process capabilities. These features deepen enforcement, but they also introduce build-time choices that administrators must evaluate against the target distribution.

LDAP support is available through the documented `--with-ldap` configure argument. The README does not state that LDAP is required for a local deployment or explain the schema and remote failure behavior. It is a separate build option, not part of the minimal policy mechanism described in the overview.

Installing USBGuard from a Release Tarball

Compiling USBGuard requires at least C++17. The README says that a release tarball also requires development files for `libqb`, `protobuf`, and either `libsodium` or `libgcrypt`. Documentation generation requires `asciidoc` through `a2x`. The optional security libraries add further build requirements rather than changing the basic compilation steps.

For Debian-based GNU/Linux distributions such as Ubuntu 21.10, the README provides one complete command for installing build dependencies. The line breaks and continuation backslashes below match the documented command.

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

After dependencies are installed, `./configure` generates the build configuration, `make` builds the project, and `sudo make install` installs it. The README also offers `make check` when the test suite should be run. These are separate commands so the operator can inspect a failed build or test run before changing the machine.

./configure

The command accepts options for a systemd unit, the crypto backend, bundled test or parser libraries, and LDAP support. The README specifically lists `--enable-systemd`, `--with-crypto-library`, `--with-bundled-catch`, `--with-bundled-pegtl`, and `--with-ldap`. Operators should consult `./configure --help` for the full argument list rather than assuming defaults not stated in the README.

Preparing Rules Before the First USBGuard Start

The most important operational constraint appears before installation instructions end: administrators must generate a rules file before starting the daemon or service for the first time. The README warns that an unsuitable initial policy can stop a currently attached mouse or keyboard from working, which may lock the user out of the system.

The documented policy-generation command writes to `/etc/usbguard/rules.conf`. Running it through `sh -c` provides the redirection needed by the command form published in the README.

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

This is a starting point, not a finished security policy. The README does not describe a safe editing procedure for removing unwanted devices or confirm how recovery should work after a policy blocks required hardware. Local console access or another tested recovery path is therefore a practical necessity during evaluation, although the project documentation does not prescribe a particular recovery tool.

Once the generated rules file exists and has been reviewed, the README says the service can be started. Enabling it makes systemd start the service during boot.

sudo systemctl start usbguard.service

sudo systemctl enable usbguard.service

These commands should not be treated as a rollback procedure. The README provides no command for disabling USBGuard through `usbguard` itself or explain how to recover remotely after a bad policy.

Separate Rule and Daemon Configuration

USBGuard keeps device policy separate from daemon configuration. The repository contains `usbguard-daemon.conf.in` for service settings and documents `usbguard-rules.conf(5)` for the authorization rules. The separate files matter because accepting an individual USB device and configuring the daemon's operating behavior are different administrative tasks.

The cleaned README does not include sample rule syntax, matching attributes, method-of-use declarations, or a complete daemon configuration example. It would be unsafe to invent those forms. Engineers who need the exact policy language must consult the named manual pages, particularly `usbguard-rules.conf(5)` and `usbguard-daemon.conf(5)`, rather than treating repository topic labels such as `blacklist` and `whitelist` as executable syntax.

The project also documents `usbguard-dbus(8)`, indicating a D-Bus interface alongside the local UNIX socket IPC used by `libqb`. The README does not show how D-Bus clients authorize requests or what happens if the daemon is unavailable. It also does not claim that D-Bus exposes every policy operation. Those boundaries matter when integrating USBGuard with desktop management software.

Where USBGuard Falls Short

USBGuard is the wrong tool when the requirement is broad application confinement rather than USB authorization. A process-control policy may govern files, capabilities, and system calls, while USBGuard begins with device identity and permitted interaction. Installing USBGuard does not make an otherwise unsecured Linux workstation into a fully managed endpoint.

It also introduces an administrative dependency. The documented deployment writes a rules file under `/etc/usbguard`, starts a privileged service, and may integrate with systemd. A system without a documented GNU/Linux installation path or without an administrator who can review service policies is a poor candidate. The repository is not archived and records a last push on 2026-09-07, but repository activity does not remove the need to validate a policy against the actual hardware.

The clearest failure mode is blocking essential input devices before the first daemon start. The README directly warns about this lockout risk. It does not document rollback, an emergency policy recovery mode, or a tested remote recovery sequence. That omission should shape the evaluation, especially for headless servers accessed through USB networking or systems controlled through USB input devices.

USBGuard Versus Broad Linux Policy Systems

A broad Linux security policy system is the relevant alternative when the main requirement is controlling processes, files, and privilege boundaries across the host. USBGuard instead centers its policy model on authorized USB hardware and allowed interaction with that hardware. The approaches can coexist, but neither should be described as a substitute for the other.

The repository exposes one limited point of overlap through optional `libseccomp` integration, which implements a syscall allowlist. Even with that library enabled, USBGuard's documented purpose remains USB policy enforcement. A process isolation framework selected for application sandboxing would generally address a different policy surface, while USBGuard requires administrators to focus on attached device identities and their permitted use.

Build complexity also differs. USBGuard can use optional `libseccomp` and `libcap-ng` support, but its documented core concerns include USB authorization, UNIX socket IPC, protobuf messages, hashing, rules, and a daemon. A broad security system would be chosen for host-wide policy coverage rather than for generating `/etc/usbguard/rules.conf`.

USBGuard Releases, Upgrades, and License Terms

The release history lists `usbguard-1.1.4` from 2025-07-15, `usbguard-1.1.3` from 2024-06-06, and `usbguard-1.1.2` from 2022-09-02. The repository is not archived, and its last push was on 2026-09-07. These facts establish publication and repository activity, but the README does not provide a compatibility matrix or an upgrade procedure for existing rules and daemon configurations.

Upgrade planning must account for the build itself. A source installation requires C++17 and external development libraries, while optional systemd, crypto backend, LDAP, seccomp, and capability-dropping configurations can affect packaging decisions. The README also notes that cloned sources need `./autogen.sh`, which fetches PEGTL and Catch through git submodules and initializes the autotools build system. That repository path is different from the release-tarball path and should not be substituted without confirmation.

USBGuard uses GPL-2.0. The README states that the software may be redistributed or modified under version 2 of the GNU General Public License or, at the user's option, under a later version. It also carries the standard warranty disclaimer and points readers to the GNU GPL text. This identifies the declared terms, but it does not replace reviewing the repository's `LICENSE` file or obtaining advice for a particular distribution arrangement.

Editorial conclusion

USBGuard fits GNU/Linux administrators who need a persistent policy for authorizing USB devices, particularly on shared or exposed systems. It is a poor fit for projects requiring a full endpoint security suite or environments where privileged daemon management is impractical. Before adoption, inspect `/etc/usbguard/rules.conf` to confirm that the mouse, keyboard, and any required USB network adapter are authorized.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. USBGuard/usbguard on GitHub