Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/usbguard/usbguard

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)
https://github.com/usbguard/usbguard

blacklist c-plus-plus hacktoberfest linux rule-language security security-hardening usb usb-devices whitelist

Last synced: 14 days ago
JSON representation

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)

Awesome Lists containing this project

README 

        
USBGuard

========

:toc:



[.clearfix]

--

[.left]

image::https://travis-ci.com/USBGuard/usbguard.svg?branch=master[Travis CI, link=https://travis-ci.com/USBGuard/usbguard]

[.left]

image::https://coveralls.io/repos/github/USBGuard/usbguard/badge.svg[Coverage, link=https://coveralls.io/github/USBGuard/usbguard]

[.left]

image::https://img.shields.io/github/license/USBGuard/usbguard.svg[License, link=https://github.com/USBGuard/usbguard/#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

 ** <>

 ** <>

 ** <>

 ** <>

 ** <>



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



To compile the source code, you will require at least C{plus}{plus}17. +

If you are compiling sources from a release tarball, you'll need the development files for:



 * https://github.com/ClusterLabs/libqb[libqb] - used for local UNIX socket based IPC

 * https://github.com/google/protobuf[protobuf] - used for IPC message (de)serialization

 * https://download.libsodium.org[libsodium] or https://www.gnupg.org/software/libgcrypt[libgcrypt] - used for hashing

 * https://asciidoc.org[asciidoc (a2x)] - needed to generate documentation



Optionally, you may want to install:



 * https://github.com/seccomp/libseccomp[libseccomp] - used to implement a syscall allowlist

 * https://people.redhat.com/sgrubb/libcap-ng/[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 https://github.com/taocpp/PEGTL/[PEGTL] and https://github.com/philsquared/Catch[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 (C) 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 .