USB Manager (USB 设备管控工具)

📖 项目信息

USB Manager 是一个基于 Python 的 Windows USB 设备管控辅助工具。它通过轮询监控系统中的 USB 设备拓扑树，自动识别并拦截未授权的 USB 设备接入。该工具允许用户通过 config.json 文件配置“受信任的 USB Hub（集线器）”，仅允许连接在这些授权 Hub 上的设备正常工作，其他直接连接到电脑面板或未经授权 Hub 的设备将被自动禁用。

✨ 主要功能

• 拓扑树检测：调用 Windows 底层 cfgmgr32.dll 自动遍历设备拓扑树，精准识别任何 USB 设备所挂载的父节点 Hub。
• 白名单机制：基于 config.json 中配置的 USB Hub VID（供应商 ID）和 PID（产品 ID）实现白名单放行。
• 自动拦截与放行：实时后台监控（默认每 3 秒一次轮询），发现连接在非授权接口上的 USB 设备时自动将其禁用；若设备被移至授权接口，则自动恢复启用。
• 系统安全保护：内置安全规则，自动识别并放行系统级 Root Hub (ROOT_HUB) 及级联的通用 Hub，防止误禁用导致整个系统 USB 控制器瘫痪。
• 一键恢复：提供命令行参数，支持一键扫描并启用所有被禁用的 USB 设备。

🛠️ 环境依赖

• 操作系统：Windows 10 / 11
• Python 版本：Python 3.6+
• 权限要求：必须以管理员权限运行（需要调用底层 pnputil 命令控制硬件状态）。
• 依赖库： 可以通过运行以下命令安装所需依赖（主要为 wmi）：

  pip install -r requirements.txt

⚙️ 配置说明

在使用前，你需要配置项目根目录下的 config.json 文件，添加你允许的 USB Hub 的 VID 和 PID。 你可以通过“设备管理器” -> “设备属性” -> “详细信息” -> “硬件 Id” 来查看你信任的 USB Hub 标识（形如 USB\VID_1A40&PID_2549）。

{
    "authorized_hubs": [
        {
            "vid": "1A40",
            "pid": "2549"
        },
        {
            "vid": "1234",
            "pid": "5678"
        }
    ]
}

🚀 使用演示

1. 启动实时监控与拦截

确保在管理员权限下的终端（如管理员 PowerShell 或 CMD）中运行：

python usb_manager.py

(或者直接右键点击 run_admin.bat 选择“以管理员身份运行”)

预期输出日志：

2024-04-14 10:00:00,000 - INFO - USB Manager 已启动。授权 Hub 标识符: VID_1A40&PID_2549, VID_1234&PID_5678
2024-04-14 10:00:00,005 - INFO - 开始后台监控 USB 设备...
2024-04-14 10:00:05,123 - WARNING - 发现未经授权的活动设备，准备禁用: USB 闪存驱动器 (USB\VID_XXXX&PID_XXXX\...)
2024-04-14 10:00:05,500 - INFO - 成功禁用设备: USB\VID_XXXX&PID_XXXX\...

2. 一键恢复所有被禁用的 USB 设备

如果需要临时关闭管控并恢复所有之前被拦截禁用的 USB 设备，可以使用 --restore 参数：

python usb_manager.py --restore

预期输出日志：

2024-04-14 10:05:00,000 - INFO - 开始恢复所有 USB 设备...
2024-04-14 10:05:01,123 - INFO - 发现被禁用的设备，准备启用: USB 闪存驱动器 (USB\VID_XXXX&PID_XXXX\...)
2024-04-14 10:05:01,500 - INFO - 成功启用设备: USB\VID_XXXX&PID_XXXX\...
2024-04-14 10:05:02,000 - INFO - 恢复完成，共启用了 1 个设备。

⚠️ 注意事项

1. 必须拥有管理员权限：工具底层调用了 Windows 自带的 pnputil /enable-device 和 /disable-device 命令，若无管理员权限，程序将报错并退出。
2. 谨慎配置白名单：请确保配置的 VID 和 PID 是外部 USB Hub 的正确标识，切勿将鼠标键盘等基础输入设备直接拦截，以免造成无法控制电脑的情况。
3. 免责声明：本工具直接操作系统底层设备状态，建议在完全理解其拓扑机制的情况下在生产环境中使用。