## 什么是 Rubber Ducky / BadUSB？ **Rubber Ducky**（以及诸如 Digispark、Flipper Zero 或经过重新刷机的 U 盘等 BadUSB 设备）看起来就像普通的 U 盘 —— 但它会告诉你的计算机自己是 **键盘**。在插入的瞬间，它会以**每秒数百到数千次按键**的速度“输入”预置的 payload：打开终端、粘贴反向 shell、窃取文件，所有这些在一秒钟内就能完成。 就操作系统而言，它*本身*就是一个键盘，因此杀毒软件几乎无法拦截。 **DuckHound 通过它的输入方式将其抓获。** 没有任何人类能以毫无抖动的机械 精度每秒输入 500 个按键 —— 因此 DuckHound 会监视按键流，提取该特征指纹， 并果断将其拒之门外。 ## ✨ 核心特性 - 🎯 **键盘注入检测** — 实时时序引擎，根据*速度*和*规律性*对每一次连续输入 进行评分。标记机械输入；忽略哪怕是最高速的人类操作。 - 🔌 **实时 USB / HID 监控** — 枚举 Windows、macOS 和 Linux 上连接的设备，并将 新出现的“键盘”与瞬间的连续输入（经典的 Ducky 特征）关联起来。 - 🚨 **主动响应** — 发出警报、鸣笛报警、**锁定屏幕**、吞掉注入的按键， 或标记非法设备以取消其授权。你可以自行决定拦截的激进程度。 - 📡 **精美的 SOC 仪表盘** — 动画雷达、实时威胁计、设备列表以及完整的取证 威胁日志。采用深色主题、运行流畅，并由 Qt 纯手工打造。 - 🖥️ **真正的跨平台** — 统一的 Python 代码库，每个操作系统使用原生枚举后端， 并在后端或所需权限不可用时优雅降级。 - 🔒 **100% 本地运行** — DuckHound 仅测量按键的**时间间隔**（绝不是*按下的 哪个*键），并且不会向外部发送任何数据。无账户、无云端、无遥测。 - 🧰 **GUI + 无界面 CLI** — 既可以运行图形仪表盘，也可以通过终端保护 kiosk/服务器。 ## 📸 截图 ## 🚀 安装说明 ``` # 1. Clone git clone https://github.com/at0m-b0mb/DuckHound.git cd DuckHound # 2. 创建 virtual environment python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 3. Install pip install -r requirements.txt ``` ### 平台说明 | 操作系统 | USB 后端 | 额外步骤 | |----|-------------|-------------| | **macOS** | `system_profiler` (内置) | 在 *系统设置 → 隐私与安全性* 中为你的终端/Python 授予 **输入监控** 权限，以便按键钩子能够运行。 | | **Linux** | `sysfs` (内置)；`pyudev` (可选) | 对于屏幕锁定/取消授权响应，用户必须具有运行 `loginctl` 的权限。 | | **Windows** | PowerShell `Get-PnpDevice` (内置) | 需以管理员身份运行以取消设备授权。可选执行 `pip install wmi pywin32` 获取更丰富的查询功能。 | ## ▶️ 使用说明 ``` python run.py # launch the dashboard python run.py --demo # dashboard with a simulated attack feed — no permissions needed python run.py --cli # headless terminal monitor (servers, kiosks, SSH) ``` **安全试用：** `python run.py --demo` 会每隔几秒模拟一次真实的 Rubber Ducky 攻击， 这样你就可以在不需要任何真实设备或 OS 权限的情况下，观看雷达亮起、计量表 飙升并触发响应。 ## 🩺 故障排除 — “它没有检测到我的 Rubber Ducky！” **1. 你是否处于 `--demo` 模式？** Demo 模式使用的是*模拟*数据源，根据设计会 忽略真实的按键。请使用普通的 `python run.py` 来监视真实输入。 **2. 授予键盘监控权限（最重要的一步）：** | 操作系统 | 需要授予的权限 | |----|---------------| | **macOS** | *系统设置 → 隐私与安全性* → 为你启动 DuckHound 的应用程序（终端、iTerm、VS Code 等）启用 **输入监控** *和* **辅助功能**。然后**完全退出并重新启动**该应用。当缺少此权限时，DuckHound 现在会显示一个带有 **授予访问权限** 按钮的黄色横幅。 | | **Linux** | 使用 **X11** 会话（Wayland 会限制全局按键捕获），或者在拥有 `/dev/input` 访问权限的情况下运行。 | | **Windows** | 开箱即用；仅在需要取消设备授权时才需以管理员身份运行。 | **3. 确保它能真正*阻止*攻击。** 默认情况下，DuckHound 只会**发出警报**。要 中和攻击，请打开 **设置 → 自动响应** 并启用： - **锁定屏幕** — 在 macOS 上这会调用屏幕保护程序，因此还需开启 *系统设置 → 锁定屏幕 → “需要立即输入密码”*。 - **拦截注入按键** — 吞掉约 2 秒的输入，以阻断后续的 payload 执行。 **4. Flipper Zero 注意事项。** 运行 BadUSB/DuckyScript payload 的 Flipper 会 枚举为 USB 键盘，并且输入速度远超人类 —— 一旦授予权限，它会在约 18 次按键 内触发检测器。如果你的脚本在每次按键时使用了较大的 `DELAY`，请在“设置”中 降低 **Human-speed ceiling** 以放宽拦截网。 ## 🧠 检测原理 Rubber Ducky 会在两个方面同时暴露自己。DuckHound 会在连续的按键窗口中对 这两点进行评分： | 信号特征 | 人类 | Rubber Ducky | |--------|-------|--------------| | **速度** (键/秒) | 约 6–12，峰值可达约 15 | **200–3000+** | | **规律性** (输入抖动) | 高 — 人手输入带有噪音 | **接近零** — 完美的机器精度 | | **时机** | 随时输入 | 通常**在插入后约 2 秒内开始** | ``` score = 0.45·speed + 0.25·regularity + 0.30·sustained-run ``` 只有在输入**同时**具备超人类的速度**且**具有持续性时，才会触发警报 —— 因此 即使是快速打字的人类或长按的按键也不会触发，但 19 次按键的连续注入却会被 捕捉。如果一个键盘出现后*立即*开始输入，则会被升级为**严重**级别。完整 分析请见 **[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**。 你可以在 **设置** 中实时调整任何参数： - **Human-speed ceiling** — 按键间隔小于此值则看起来像是自动化输入。 - **Burst run length** — 连续快速输入多少个按键才会触发警报。 - **Robotic-timing threshold** — 数值越低，对机器般的规律性要求越严格。 ## 🛠️ 项目结构 ``` DuckHound/ ├── run.py # launcher (GUI / --cli / --demo) ├── duckhound/ │ ├── app.py # GUI entry point │ ├── cli.py # headless terminal monitor │ ├── config.py # persisted settings │ ├── core/ │ │ ├── keystroke.py # ⭐ the timing-analysis detector │ │ ├── engine.py # orchestrates monitors, scoring & response │ │ ├── backends/ # per-OS device enumeration (mac/linux/windows) │ │ ├── responder.py # lock / notify / block actions │ │ ├── simulator.py # synthetic attack feed for demo & tests │ │ └── models.py # Device / ThreatEvent data models │ └── ui/ │ ├── theme.py # palette + global stylesheet │ ├── main_window.py # shell wiring engine ↔ pages │ ├── components/ # radar, threat meter, toggle, cards, toast… │ └── pages/ # dashboard · devices · threats · settings ├── scripts/capture_screenshots.py └── assets/ # banner, logo, screenshots ``` ## 🔒 隐私说明 DuckHound 从不记录你按下的**哪个**键 — 仅记录按键之间的**时间间隔**。 没有任何内容记录、没有网络访问、也没有遥测。所有数据都保留在你的设备上。 ## 🗺️ 路线图 - [ ] Linux 上的实时 `pyudev` 热插拔事件（亚秒级设备接入） - [ ] 带有开机自启功能的后台系统托盘守护进程 - [ ] 重启后依然生效的设备级 USB 白名单 - [ ] 在所有平台上，确认受到攻击时可选地*抑制*按键输入 - [ ] 签名的安装程序（`.dmg`, `.msi`, AppImage） ## ⚠️ 免责声明 DuckHound 是一款**防御性**安全工具，旨在保护你拥有或被授权保护的 机器。内置的模拟器仅生成*合成*攻击 — 它不包含任何 payload，也无法 攻击任何目标。 ## 📄 License MIT © [at0m-b0mb](https://github.com/at0m-b0mb) — 详见 [LICENSE](LICENSE)。

标签：AI合规, BadUSB防御, PySide6, Python, 无后门, 端点防护, 跨平台桌面应用, 逆向工具, 键盘注入检测