# Facedancer USB 设备仿真与代理库

> 用软件实现 USB 设备的 Python 库，借助 Cynthion、GreatFET 等硬件外设充当连接目标主机的可远程控制 USB 控制器。其 USBProxy 模式位于真实设备与主机之间转发传输，并由过滤器记录、解码或修改传输内容，用于 USB 协议分析；README 指出，这适用于无法控制其软件的设备，例如嵌入式系统或游戏主机。第 3 版从头重写了仿真核心，内置键盘、大容量存储和 FTDI 串口设备模型以及 HID 与日志代理过滤器，不再支持旧版 2.9.x 脚本。

- 类型：工具
- 目标：协议
- 类别：协议分析工具
- 关联：基础工具
- 来源复核于：2026-10-27
- 收录于：2026-11-03
- 原始资源：<https://github.com/greatscottgadgets/facedancer>
- 一手来源：<https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md>
- 目录页面：<https://awesomerea.org/zh/resources/facedancer/>
- 记录 JSON：<https://awesomerea.org/resources/facedancer/record.json>
- 英文版：[English](https://awesomerea.org/resources/facedancer/index.md)

## 使用条件与局限

- 需要用 BACKEND 变量选择受支持的板卡：Cynthion（cynthion）、GreatFET One 及其他 LPC4330 板卡（greatfet）、Facedancer21 等基于 GoodFET 的 Facedancer（goodfet）、树莓派 Raspdancer 板卡（raspdancer），或 HydraDancer 与 HydraUSB3（hydradancer）。README 称基于 MAX3420/MAX3421 的板卡无法仿真较复杂的设备，也不能充当 USBProxy 中间人设备，HydraDancer 板卡不支持主机模式。
- 审阅时最新版本为 3.1.3，于 2026-05-22 发布在 GitHub 和 PyPI，与所审阅的 main 提交相同；pyproject.toml 要求 Python 3.10+，并依赖 pyusb、libusb1、pyserial、prompt-toolkit 和 hid-parser。README 称 Facedancer 3.0 无法在 Windows 上运行、仅支持 GNU/Linux，而入门指南把这一警告限定为在 Windows 控制主机上使用 GreatFET，代理指南则称在 macOS 上须以 root 身份运行 USBProxy 才能从系统接管被代理的设备。
- USBProxy 需要被代理的真实设备，并按其厂商 ID 和产品 ID 识别；由分析者编写的过滤器决定转发、记录或修改哪些内容。README 称代理功能已完成，但还需更多文档。仓库只包含 Python 源码、示例、测试和文档，不含板卡固件。只应对自己拥有或已获授权测试的主机和设备进行仿真和代理。
- 采用 BSD-3-Clause 许可。

## 一手来源

1. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md>
2. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md#L55-L77>
3. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md#L98-L117>
4. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/docs/source/using_usb_proxy.rst>
5. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/docs/source/getting_started.rst>
6. <https://github.com/greatscottgadgets/facedancer/tree/9f1298856e8ec6871cca995ded3076ab89dd72cd/facedancer/filters>
7. <https://github.com/greatscottgadgets/facedancer/tree/9f1298856e8ec6871cca995ded3076ab89dd72cd/facedancer/devices>
8. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/pyproject.toml>
9. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/CHANGELOG.md>
10. <https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/LICENSE>
11. <https://github.com/greatscottgadgets/facedancer/releases/tag/3.1.3>
12. <https://pypi.org/project/facedancer/3.1.3/>
13. <https://facedancer.readthedocs.io/en/latest/>

## 同分区更多条目：协议

- [Mirage 无线通信分析框架](https://awesomerea.org/zh/resources/mirage-wireless-framework/index.md) · 工具
- [Protobuf Decoder 无定义 Protobuf 网页解码器](https://awesomerea.org/zh/resources/pawitp-protobuf-decoder/index.md) · 工具
- [gr-lora LoRa 物理层解码模块](https://awesomerea.org/zh/resources/gr-lora/index.md) · 工具
- [termshark tshark 终端界面](https://awesomerea.org/zh/resources/termshark/index.md) · 工具
- [SigDigger 数字信号分析器](https://awesomerea.org/zh/resources/sigdigger/index.md) · 工具
- [grpc-tools gRPC 流量调试工具集](https://awesomerea.org/zh/resources/grpc-tools/index.md) · 工具

## 关于此条目

说明已依据一手来源复核。
原创说明采用 MIT 许可；外部项目、论文与素材保留各自的权利和许可。