eBPF-hid_guard

eBPF-hid_guard

请参见下文存档原因。

一个 Linux 内核空间安全监控工具，用于检测和阻止 HID 注入攻击（Rubber Ducky、O.MG Cable、基于 ESP32 的键盘模拟器），利用 eBPF HID-BPF struct_ops。

功能介绍

恶意 HID 设备会模拟键盘并以远超人类打字速度的速度注入按键。本工具检测到这种时序异常后，会在攻击完成前将恶意设备从内核 HID 驱动中解绑。

启动时，工具会快照当前所有已连接的 HID 设备并忽略它们——仅监控新连接的设备。支持 USB 和蓝牙 HID 设备。

分支结构

main — 可用的概念验证

完整的功能端到端管道，已针对基于 ESP32 的键盘模拟器进行测试：

• 启动时快照现有设备并忽略它们
• USB 和 BLE 并行发现线程——先检测到新设备的线程获胜
• 将 HID-BPF struct_ops 程序附加到发现的设备
• BPF 端通过环形缓冲区捕获原始 HID 报告字节、时间戳、厂商/产品/总线
• 用户空间计算按键间隔差值，跟踪可疑计数器，当超过阈值时通过 sysfs 解绑设备

触发重写的已知限制：

• 报告大小硬编码为 8 或 9 字节（仅适用于标准引导协议键盘）——在非标准描述符上会失败
• 没有 HID 报告描述符解析——设备类型是假设的，未经验证；会在鼠标、触摸板或复合设备上误触发
• 检测逻辑完全位于用户空间——BPF 仅用作原始数据传输管道
• hid_id 源自 sysfs 次设备号，重启后不稳定

v0.1 — 干净的重新实现（已暂停）

在重新连接 BPF 层之前构建的可移植基础：

• 通过 /sys/bus/hid/devices/ 枚举所有 HID 设备
• 从 sysfs 读取并十六进制转储原始报告描述符
• HID 报告描述符解析器正在进行中（hid_desc_parse.c）——设备类型识别尚未完成
• 内存清理（已通过 AddressSanitizer 验证）

存档原因

两个分支都遇到了同一个障碍：HID-BPF 操作的是原始字节数组，因此无论检测逻辑如何划分，所有描述符解析和设备类型验证都必须放在用户空间。为了避免从头搭建这些基础设施，我迁移到了 [udev-hid-bpf]。

功能介绍

恶意 HID 设备会模拟键盘并以远超人类打字速度的速度注入按键。本工具检测到这种时序异常后，会在攻击完成前将恶意设备从内核 HID 驱动中解绑。

启动时，工具会快照当前所有已连接的 HID 设备并忽略它们——仅监控新连接的设备。支持 USB 和蓝牙 HID 设备。

分支结构

main — 可用的概念验证

完整的功能端到端管道，已针对基于 ESP32 的键盘模拟器进行测试：

• 启动时快照现有设备并忽略它们
• USB 和 BLE 并行发现线程——先检测到新设备的线程获胜
• 将 HID-BPF struct_ops 程序附加到发现的设备
• BPF 端通过环形缓冲区捕获原始 HID 报告字节、时间戳、厂商/产品/总线
• 用户空间计算按键间隔差值，跟踪可疑计数器，当超过阈值时通过 sysfs 解绑设备

触发重写的已知限制：

• 报告大小硬编码为 8 或 9 字节（仅适用于标准引导协议键盘）——在非标准描述符上会失败
• 没有 HID 报告描述符解析——设备类型是假设的，未经验证；会在鼠标、触摸板或复合设备上误触发
• 检测逻辑完全位于用户空间——BPF 仅用作原始数据传输管道
• hid_id 源自 sysfs 次设备号，重启后不稳定

v0.1 — 干净的重新实现（活跃开发中）

在重新连接 BPF 层之前正在构建的可移植基础：

• 通过 /sys/bus/hid/devices/ 枚举所有 HID 设备
• 从 sysfs 读取并十六进制转储原始报告描述符
• HID 报告描述符解析器正在进行中（hid_desc_parse.c）——将能够在附加前识别设备类型
• 内存清理（已通过 AddressSanitizer 验证）

预期架构

┌─────────────────────────────────────────────────────┐
│                    用户空间                          │
│                                                      │
│  udev 监视 → 描述符解析 → 是否为键盘？               │
│       ↓                                              │
│  填充 BPF 配置映射（阈值、设备信息）                  │
│       ↓                                              │
│  将 HID-BPF struct_ops 附加到 hid_id                 │
│       ↓                                              │
│  环形缓冲区消费者 → 攻击时通过 sysfs 解绑            │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  BPF（内核侧）                       │
│                                                      │
│  hid_device_event → 时序计算（Welford 在线方差，     │
│  定点数）→ 每个按键的时间戳映射 → 异常时提交环形    │
│  缓冲区                                              │
└─────────────────────────────────────────────────────┘

检测逻辑移至 BPF。用户空间负责描述符解析、配置映射填充和解绑响应。设备连接到 BPF 附加之间的枚举窗口是一个有文档记录的、有界的限制——现实世界中的 HID 注入工具会包含有意的后枚举延迟，此窗口落在该延迟范围内。

要求

• Linux 内核 ≥ 6.3（HID-BPF struct_ops 稳定）
• libbpf 开发头文件
• LLVM/Clang（用于 BPF 编译）
• libelf 和 zlib 开发头文件
• Root 权限

构建

make

使用

# 自动检测：提示时插入或配对设备
sudo ./hid_guard

# 使用已知 hid_id 手动覆盖
sudo ./hid_guard <hid_id>

# 列出可用的 HID 设备
ls /sys/bus/hid/devices/

检测可调参数（main.c）

状态

测试

使用 ESP32-S2 进行 BLE 按键传输。下一步将使用像 rubber ducky 或 ESP32-S3 这样的硬件进行测试，目标是 USB 端口。

许可证

GPL v2