[Ubuntu] 使用USBGuard管理USB设备

title: [Ubuntu] 使用USBGuard管理USB设备

date: 2024-12-11T09:44:05Z
lastmod: 2024-12-12T10:04:30Z

[Ubuntu] 使用USBGuard管理USB设备

前言

USBGuard 软件框架通过根据设备属性实现基本的白名单和黑名单功能，帮助保护您的计算机免受恶意 USB 设备。经过尝试，如果设备被加入黑名单后相当于直接把USB口断电。

注意：该开源项目只可以在Linux中运行。

通过CLI管理USB设备

安装USBGuard
C++ 复制代码
```
sudo apt install -y usbguard
```

查看使用方法

C++ 复制代码

usbguard --help
 Usage: usbguard [OPTIONS] <command> [COMMAND OPTIONS] ...

 Options:

 Commands:
  get-parameter <name>           Get the value of a runtime parameter.
  set-parameter <name> <value>   Set the value of a runtime parameter.
  list-devices                   List all USB devices recognized by the USBGuard daemon.
  allow-device <id|rule|p-rule>  Authorize a device to interact with the system.
  block-device <id|rule|p-rule>  Deauthorize a device.
  reject-device <id|rule|p-rule> Deauthorize and remove a device from the system.

  list-rules                     List the rule set (policy) used by the USBGuard daemon.
  append-rule <rule>             Append a rule to the rule set.
  remove-rule <id>               Remove a rule from the rule set.

  generate-policy                Generate a rule set (policy) based on the connected USB devices.
  watch                          Watch for IPC interface events and print them to stdout.
  read-descriptor                Read a USB descriptor from a file and print it in human-readable form.

  add-user <name>                Add USBGuard IPC user/group (requires root privilges)
  remove-user <name>             Remove USBGuard IPC user/group (requires root privileges)

查看设备列表

C++ 复制代码

usbguard list-devices

C++ 复制代码

1: allow id 1d6b:0002 serial "0000:00:0d.0" name "xHCI Host Controller" hash "d3YN7OD60Ggqc9hClW0/al6tlFEshidDnQKzZRRk410=" parent-hash "Y1kBdG1uWQr5CjULQs7uh2F6pHgFb6VDHcWLk83v+tE=" via-port "usb1" with-interface 09:00:00 with-connect-type ""
2: allow id 1d6b:0003 serial "0000:00:0d.0" name "xHCI Host Controller" hash "4Q3Ski/Lqi8RbTFr10zFlIpagY9AKVMszyzBQJVKE+c=" parent-hash "Y1kBdG1uWQr5CjULQs7uh2F6pHgFb6VDHcWLk83v+tE=" via-port "usb2" with-interface 09:00:00 with-connect-type ""
3: allow id 1d6b:0002 serial "0000:00:14.0" name "xHCI Host Controller" hash "jEP/6WzviqdJ5VSeTUY8PatCNBKeaREvo2OqdplND/o=" parent-hash "rV9bfLq7c2eA4tYjVjwO4bxhm+y6GgZpl9J60L0fBkY=" via-port "usb3" with-interface 09:00:00 with-connect-type ""
4: allow id 1d6b:0003 serial "0000:00:14.0" name "xHCI Host Controller" hash "prM+Jby/bFHCn2lNjQdAMbgc6tse3xVx+hZwjOPHSdQ=" parent-hash "rV9bfLq7c2eA4tYjVjwO4bxhm+y6GgZpl9J60L0fBkY=" via-port "usb4" with-interface 09:00:00 with-connect-type ""
5: allow id 0781:55ae serial "32323438314B343034313136" name "Extreme 55AE" hash "2nLfiF9agZUnXwIuJL4rt6hivjahXMJwpBghNeFwH7U=" parent-hash "4Q3Ski/Lqi8RbTFr10zFlIpagY9AKVMszyzBQJVKE+c=" via-port "2-1" with-interface { 08:06:50 08:06:62 } with-connect-type "hotplug"
6: allow id 1a2c:7f49 serial "" name "USB Gaming Keyboard " hash "tU34AK2RCvuLxenpOahrruFoVHDT8hUAF50LjoFyoPM=" parent-hash "jEP/6WzviqdJ5VSeTUY8PatCNBKeaREvo2OqdplND/o=" via-port "3-1" with-interface { 03:01:01 03:01:02 } with-connect-type "hotplug"
7: allow id 046d:c52f serial "" name "USB Receiver" hash "/GZeFOM06z5ICkwVKKsCIbow9iKh+kA+RBIqlizNbhc=" parent-hash "jEP/6WzviqdJ5VSeTUY8PatCNBKeaREvo2OqdplND/o=" via-port "3-4" with-interface { 03:01:02 03:00:00 } with-connect-type "hotplug"
8: allow id 0c45:6739 serial "" name "Integrated_Webcam_FHD" hash "GYHJ+DvVIxhJxcoP0ZetpDXTXQD9bjL0uoz6qpC9MYI=" parent-hash "jEP/6WzviqdJ5VSeTUY8PatCNBKeaREvo2OqdplND/o=" via-port "3-6" with-interface { 0e:01:00 0e:02:00 0e:02:00 0e:02:00 0e:02:00 0e:02:00 0e:02:00 0e:02:00 } with-connect-type "not used"
9: allow id 8087:0033 serial "" name "" hash "ciwwGozaSw4maEXfs4NdvETeMt6bnFEK6f4vmCqfud0=" parent-hash "jEP/6WzviqdJ5VSeTUY8PatCNBKeaREvo2OqdplND/o=" via-port "3-10" with-interface { e0:01:01 e0:01:01 e0:01:01 e0:01:01 e0:01:01 e0:01:01 e0:01:01 e0:01:01 } with-connect-type "hardwired"

输出的结果格式如下：

C++ 复制代码

[id]: [target] device_id serial name hash parent-hash via-port with-interface with-connect-type
id-> 设备在usbguard下的编号
target-> 当前设备的授权状态
device_id-> [供应商ID：产品ID] 的组合，会出现重复
serial-> 序列号，一般用在存储设备上
name-> USB设备名称
hash-> 哈希值是基于设备的一些属性（如厂商ID、产品ID、序列号等）生成的唯一标识，这个值会发生变化，不是永久不变的
parent-hash-> 父设备的哈希值。如果该设备是通过USB集线器连接的，parent-hash 表示集线器的哈希值。，这个值会发生变化，不是永久不变的
via-port-> [busnum-devpath],设备总线和端口的组合，可以通过lsusb -tv查看
with-interface-> 设备的接口信息，09:00:00 表示设备使用的接口类、子类和协议代码。
with-connect-type-> 设备的连接类型。这个字段为空字符串，表示没有指定连接类型

授权设备接入(临时操作，重新接入设备又会恢复)
C++ 复制代码
```
usbguard allow-device [id]
```
授权设备接入(永久操作，将会写入规则文件)
C++ 复制代码
```
usbguard allow-device [id] -p
```
取消授权设备接入，但是不删除设备(临时操作，重新接入设备又会恢复)
C++ 复制代码
```
usbguard block-device [id]
```
取消授权设备接入，但是不删除设备(永久操作，将会写入规则文件)
C++ 复制代码
```
usbguard block-device [id] -p
```
取消授权设备接入并且删除设备(临时操作，重新接入设备又会恢复)
C++ 复制代码
```
usbguard reject-device [id]
```
取消授权设备接入并且删除设备(永久操作，将会写入规则文件)
C++ 复制代码
```
usbguard reject-device [id] -p
```

USBGuard 守护进程配置文件

https://usbguard.github.io/documentation/configuration.html

USBGuard通过加载usbguard-daemon.conf来配置守护程序的运行参数。其配置路径在

/etc/usbguard/usbguard-daemon.conf。

参数列表

RuleFile=<path> USBGuard 守护程序将使用此文件从中加载策略规则集并写入通过 IPC 接口收到的新规则。默认：%sysconfdir%/usbguard/rules.conf
ImplicitPolicyTarget=<target> 如何处理不符合策略中任何规则的设备。
- allow-授权设备
- block - 取消对设备的授权
- reject-从系统中逻辑地删除设备节点 默认值: block
PresentDevicePolicy=<policy> 守护进程启动时如何处理已经连接的设备：
- allow - 授权每个现有设备
- block - 取消对每个现有设备的授权
- reject - 删除所有现有设备
- keep - 仅同步内部状态并保留它
- apply-policy - 评估每个现有设备的规则集 默认值: apply-policy
PresentControllerPolicy=<policy> 守护进程启动时如何处理已连接的 USB 控制器：
- allow - 授权每个现有设备
- block - 取消对每个现有设备的授权
- reject - 删除所有现有设备
- keep - 仅同步内部状态并保留它
- apply-policy - 评估每个现有设备的规则集默认值: keep
InsertedDevicePolicy=<policy> 守护进程启动后如何处理已连接的 USB 设备。block、reject、apply-policy。默认值: apply-policy
RestoreControllerDeviceState=<boolean> USBGuard 守护程序会修改控制器设备的某些属性，例如新子设备实例的默认授权状态。使用此设置，您可以控制守护程序是否在关机时尝试将属性值恢复到修改前的状态。
DeviceManagerBackend=<backend> 使用哪种设备管理器后端实现。后端应该是 uevent（默认）或 umockdev。
IPCAllowedUsers=<username> [<username> ...] 守护进程将接受 IPC 连接的用户名的空格分隔列表。默认值：root
IPCAllowedGroups=<groupname> [<groupname> ...] 守护进程将接受 IPC 连接的组名空格分隔列表。
IPCAccessControlFiles=<path> 守护进程会将此位置的文件解释为 IPC 访问控制定义文件。<<ipc-access-control,IPC ACCESS CONTROL>>有关详细信息，请参阅部分。
DeviceRulesWithPort=<boolean> 生成包含"via-port"属性的设备特定规则。默认：false
AuditBackend=<backend> USBGuard 审计事件日志后端。后端值应为 FileAudit 或 LinuxAudit 之一。默认值：FileAudit
AuditFilePath=<filepath> USBGuard 审计事件日志文件路径。如果 AuditBackend 设置为 FileAudit，则必填。默认值：%localstatedir%/log/usbguard/usbguard-audit.log
HidePII=<boolean> 隐藏个人身份信息，例如设备序列号和描述符的哈希值（包括序列号），不受审计条目的限制。默认值：false

安全注意事项

工业控制计算机

守护程序提供 USBGuard 公共 IPC 接口。根据您的发行版默认设置，此接口的访问权限仅限于某个组或特定用户。请设置 IPCAllowedUsers 、 IPCAllowedGroups或 IPCAccessControlFiles选项以限制对 IPC 接口的访问。请勿将 ACL 保持未配置状态，因为这会将 IPC 接口暴露给所有本地用户，并允许他们操纵 USB 设备的授权状态并修改 USBGuard 策略。

RestoreControllerDeviceState 配置选项

如果设置为 true，则可以通过对守护进程执行某种攻击（通过本地漏洞或通过 USB 设备）来绕过 USB 授权策略，使其关闭并恢复到操作系统默认状态（已知是允许的）。

IPC 访问控制

可以限制每个用户或组对 USBGuard IPC 接口的访问。此外，通过使用 IPC 访问控制文件，可以将访问限制到以下部分和权限级别。

Python3 DBUS操作 USBGuard案例

https://pypi.org/project/usbguard-simple-gui-py-qt/#files

python 复制代码

class UsbGuard():
    def __init__(self) -> None:
        bus_name = 'org.usbguard1'
        policy_path = '/org/usbguard1/Policy'
        policy_iface_name = 'org.usbguard.Policy1'
        devices_path = '/org/usbguard1/Devices'
        devices_iface_name = 'org.usbguard.Devices1'
        system_bus = dbus.SystemBus()
        device_obj = system_bus.get_object(bus_name, devices_path)
        self.device = dbus.Interface(device_obj, devices_iface_name)
        policy_obj = system_bus.get_object(bus_name, policy_path)
        self.policy = dbus.Interface(policy_obj, policy_iface_name)

    def list_devices(self, query="match"):
        devices = self.device.listDevices(query)   
        return devices

    def apply_device_policy(self, id, target, permanent=False):
        rule_id = self.device.applyDevicePolicy(id, target, permanent)
        return rule_id


guard = UsbGuard()
guard.list_devices()
guard.apply_device_policy(1, "allow", False)

Reference

usbguard

https://github.com/USBGuard/usbguard/

保护系统免受入侵 USB 设备的攻击

python dbus代码：https://pypi.org/project/usbguard-simple-gui-py-qt/#files

‍