USBGUARD(1)

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

DESCRIPTION

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\"

SEE ALSO

usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)

BUGS

If you find a bug in this software or if you’d like to request a feature to be implemented, please file a ticket at https://github.com/USBGuard/usbguard/issues/new.

AUTHOR

USBGuard was originally written by Daniel Kopeček. Many people have contributed to it.

RESOURCES

Main web site: https://usbguard.github.io/

COPYING

License GPLv2+: GNU GPL version 2 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.