SolverNA/usb-auth-guard
GitHub: SolverNA/usb-auth-guard
通过 polkit 密码认证机制在 Linux 桌面环境下默认拦截所有 USB 设备，有效防范 BadUSB、HID 注入和物理接触攻击的终端防护工具。
Stars: 0 | Forks: 0
# usb-auth-guard
默认拦截所有 USB 设备，并在允许任何新设备之前显示一个 **原生的 polkit 密码对话框** —— 就像 KDE/GNOME 中的 `sudo` 提示一样。
防范以下威胁：
- **BadUSB / Rubber Ducky / O.MG Cable** —— HID 注入键盘在您认证前会被拦截
- **USB 数据窃取** —— 驱动器在没有密码的情况下无法执行任何操作
- **物理接触攻击** —— 克隆您设备的 VID:PID 毫无用处，依然需要认证
```
Insert USB → USBGuard blocks at kernel level
↓
usb-auth-guard daemon detects event
↓
Native KDE/GNOME polkit dialog appears
↓
Correct password → device works
Cancel / wrong → device stays dead
```
## 安装
### 一键安装 (Debian / Kali / Ubuntu)
```
curl -fsSL https://raw.githubusercontent.com/SolVerNA/usb-auth-guard/main/install.sh | sudo bash
```
### .deb 软件包
```
wget https://github.com/SolVerNA/usb-auth-guard/releases/latest/download/usb-auth-guard_1.0.0.deb
sudo dpkg -i usb-auth-guard_1.0.0.deb
systemctl --user enable --now usb-auth-guard
```
### 从源码构建
```
git clone https://github.com/SolVerNA/usb-auth-guard
cd usb-auth-guard
sudo make install
sudo make setup-usbguard
systemctl --user enable --now usb-auth-guard
```
## 依赖要求
- `usbguard` + `usbguard-dbus`
- `python3-dbus`, `python3-gi`
- `policykit-1` (polkit)
- systemd + KDE Plasma 或 GNOME (任何 polkit 代理)
## 工作原理
| 组件 | 作用 |
|---|---|
| **USBGuard** | 通过 `/sys/.../authorized` 在内核层面拦截设备 |
| **usbguard-dbus** | 在 D-Bus 上暴露 USBGuard 事件 |
| **usb-auth-guard** | 监听 `DevicePresenceChanged` 事件的 Python 守护进程 |
| **polkit + pkexec** | 显示原生桌面密码对话框 |
| **helper** | 由 pkexec 调用以运行 `usbguard allow-device` 的 Root 级别助手程序 |
授权**仅限当前会话** —— 再次插入同一设备仍需重新认证。
## 日志
```
journalctl --user -u usb-auth-guard -f
```
## 卸载
```
git clone https://github.com/SolVerNA/usb-auth-guard
cd usb-auth-guard
sudo make uninstall
```
## 许可证
MIT
标签：BadUSB防护, DBus通信, GNOME, HID注入攻击防御, JSONLines, KDE, Linux桌面安全, Polkit认证, Python, Rubber Ducky防御, Systemd服务, USBGuard, USB安全, USB数据防泄露, 外设控制, 数据防泄密, 无后门, 物理安全, 物理接口防护, 白名单, 端点防护, 逆向工具, 零信任