usbguard - USBGuard command-line interface

NAME SYNOPSIS DESCRIPTION SUBCOMMANDS get−parameter [OPTIONS] name set−parameter [OPTIONS] name value list−devices [OPTIONS] allow−device [OPTIONS] < id | rule | partial−rule > block−device [OPTIONS] < id | rule | partial−rule > reject−device [OPTIONS] < id | rule | partial−rule > list−rules [OPTIONS] append−rule [OPTIONS] rule remove−rule [OPTIONS] id generate−policy [OPTIONS] watch [OPTIONS] read−descriptor [OPTIONS] file add−user name [OPTIONS] remove−user name [OPTIONS] EXAMPLES SEE ALSO BUGS AUTHOR RESOURCES COPYING

NAME

usbguard − USBGuard command−line interface

SYNOPSIS

usbguard [OPTIONS] <subcommand> [SUBCOMMAND−OPTIONS] ...

usbguard get−parameter name

usbguard set−parameter name value

usbguard list−devices

usbguard allow−device id | rule | partial−rule

usbguard block−device id | rule | partial−rule

usbguard reject−device id | rule | partial−rule

usbguard list−rules

usbguard append−rule rule

usbguard remove−rule id

usbguard generate−policy

usbguard watch

usbguard read−descriptor file

usbguard add−user name

usbguard remove−user name

The usbguard command provides a command−line interface (CLI) to a running usbguard−daemon(8) instance. It also provides a tool for generating initial USBGuard policies based on USB devices connected to the system.

SUBCOMMANDS

get−parameter [OPTIONS] name

Get the value of a runtime parameter. Parameter name is one of InsertedDevicePolicy and ImplicitPolicyTarget.

Available options:

−h, −−help

Show help.

set−parameter [OPTIONS] name value

Set the value of a runtime parameter. Parameter name is one of InsertedDevicePolicy and ImplicitPolicyTarget.

Available options:

−v, −−verbose

Print the previous and new attribute value.

−h, −−help

Show help.

list−devices [OPTIONS]

List all USB devices recognized by the USBGuard daemon.

Available options:

−a, −−allowed

List allowed devices.

−b, −−blocked

List blocked devices.

−t, −−tree

List devices in a tree format.

−h, −−help

Show help.

allow−device [OPTIONS] < id | rule | partial−rule >

Authorize a device to interact with the system. The device can be identified by either a device id, rule or partial−rule (rule without target). Both rule and partial−rule can be used to allow multiple devices at once. Note that id refers to the internal device−rule ID (the very first number of the list−devices command output) rather than the device’s ID attribute.

Available options:

−p, −−permanent

Make the decision permanent. A device specific allow rule will be appended to the current policy.

−h, −−help

Show help.

block−device [OPTIONS] < id | rule | partial−rule >

Deauthorize a device. The device can be identified by either a device id, rule or partial−rule (rule without target). Both rule and partial−rule can be used to block multiple devices at once. Note that id refers to the internal device−rule ID (the very first number of the list−devices command output) rather than the device’s ID attribute.

Available options:

−p, −−permanent

Make the decision permanent. A device specific block rule will be appended to the current policy.

−h, −−help

Show help.

reject−device [OPTIONS] < id | rule | partial−rule >

Deauthorize and remove a device. The device can be identified by either a device id, rule or partial−rule (rule without target). Both rule and partial−rule can be used to reject multiple devices at once. Note that id refers to the internal device−rule ID (the very first number of the list−devices command output) rather than the device’s ID attribute.

Available options:

−p, −−permanent

Make the decision permanent. A device specific reject rule will be appended to the current policy.

−h, −−help

Show help.

list−rules [OPTIONS]

List the rule set (policy) used by the USBGuard daemon.

Available options:

−d, −−show−devices

Show all devices which are affected by the specific rule.

−l, −−label label

Only show rules having a specific label.

−h, −−help

Show help.

append−rule [OPTIONS] rule

Append the rule to the current rule set.

Available options:

−a, −−after id

Append the new rule after a rule with the specified rule id.

−t, −−temporary

Make the decision temporary. The rule policy file will not be updated.

−h, −−help

Show help.

remove−rule [OPTIONS] id

Remove a rule identified by the rule id from the rule set.

Available options:

−h, −−help

Show help.

generate−policy [OPTIONS]

Generate a rule set (policy) which authorizes the currently connected USB devices.

Available options:

−p, −−with−ports

Generate port specific rules for all devices. By default, port specific rules are generated only for devices which do not export an iSerial value.

−P, −−no−ports−sn

Don’t generate port specific rules for devices without an iSerial value. Without this option, the tool will add a via−port attribute to any device that doesn’t provide a serial number. This is a security measure to limit devices that cannot be uniquely identified to connect only via a specific port. This makes it harder to bypass the policy since the real device will occupy the allowed USB port most of the time.

−d, −−devpath devpath

Only generate a rule for the device at the specified sub path of /sys.

−t, −−target target

Generate an explicit "catch all" rule with the specified target. The target can be one of the following values: allow, block, reject

−X, −−no−hashes

Don’t generate a hash attribute for each device.

−H, −−hash−only

Generate a hash−only policy.

−L, −−ldif

Generate a ldif policy for LDAP.

−b, −−usbguardbase base

Generate a ldif policy for LDAP with this base. This option is required when −−ldif was specified.

−o, −−objectclass objectclass

Generate a ldif policy for LDAP with this objectClass.

−n, −−name−prefix prefix

Generate a ldif policy for LDAP with this name prefix.

−h, −−help

Show help.

watch [OPTIONS]

Watch the IPC interface events and print them to stdout.

Available options:

−w, −−wait

Wait for IPC connection to become available.

−o, −−once

Wait only when starting, if needed. Exit when the connection is lost.

−e, −−exec path

Run an executable file located at path for every event. Pass event data to the process via environment variables.

−h, −−help

Show help.

read−descriptor [OPTIONS] file

Read a USB descriptor from a file and print it in human−readable form.

Available options:

−h, −−help

Show help.

add−user name [OPTIONS]

Create an IPC access control file allowing the user/group identified by name to use the USBGuard IPC bus. The change takes effect only after restarting the usbguard−daemon(8) instance.

Available options:

−u, −−user

The specified name represents a username or UID (default).

−g, −−group

The specified name represents a groupname or GID.

−p, −−policy privileges

Policy related privileges.

−d, −−devices privileges

Device related privileges.

−e, −−exceptions privileges

Exceptions related privileges.

−P, −−parameters privileges

Run−time parameter related privileges.

−h, −−help

Show help.

Privileges:

The privileges are expected to be in the form of a list separated by a colon:

$ sudo usbguard add−user joe −−devices=listen,modify

Consult the usbguard−daemon.conf(5) man−page for a detailed list of available privileges in each section. You can also use ALL instead of privileges to automatically assign all relevant privileges to a given section.

remove−user name [OPTIONS]

Remove an IPC access control file associated with the user/group identified by name. The change takes effect only after restarting the usbguard−daemon(8) instance.

Available options:

−u, −−user

The specified name represents a username or UID (default).

−g, −−group

The specified name represents a groupname or GID.

−h, −−help

Show help.

EXAMPLES

Generating an initial policy:

$ sudo usbguard generate−policy > rules.conf
$ vi rules.conf
(review/modify the rule set)
$ sudo install −m 0600 −o root −g root rules.conf /etc/usbguard/rules.conf
$ sudo systemctl restart usbguard

Allow device(s):

# Allow a device by ID(it is the very first number from the list−devices command output)
$ sudo usbguard allow−device 10
# Allow all devices named "Dell Wired Multimedia Keyboard"
$ sudo usbguard allow−device name \"Dell Wired Multimedia Keyboard\"