{
  "added_at": "2026-11-03",
  "additional_evidence_urls": [
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md#L55-L77",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md#L98-L117",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/docs/source/using_usb_proxy.rst",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/docs/source/getting_started.rst",
    "https://github.com/greatscottgadgets/facedancer/tree/9f1298856e8ec6871cca995ded3076ab89dd72cd/facedancer/filters",
    "https://github.com/greatscottgadgets/facedancer/tree/9f1298856e8ec6871cca995ded3076ab89dd72cd/facedancer/devices",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/pyproject.toml",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/CHANGELOG.md",
    "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/LICENSE",
    "https://github.com/greatscottgadgets/facedancer/releases/tag/3.1.3",
    "https://pypi.org/project/facedancer/3.1.3/",
    "https://facedancer.readthedocs.io/en/latest/"
  ],
  "category": "protocol-analysis",
  "description_en": "Python library for implementing USB devices in software, with a hardware peripheral such as Cynthion or GreatFET acting as a remote-controlled USB controller attached to the target host. Its USBProxy mode sits between a real device and a host, forwarding transfers while filters log, decode or modify them for USB protocol analysis; the README notes this suits devices whose software you do not control, such as embedded systems or game consoles. Version 3 is a ground-up rewrite of the emulation core that ships keyboard, mass-storage and FTDI serial device models plus HID and logging proxy filters, and no longer runs legacy 2.9.x scripts.",
  "description_zh": "用软件实现 USB 设备的 Python 库，借助 Cynthion、GreatFET 等硬件外设充当连接目标主机的可远程控制 USB 控制器。其 USBProxy 模式位于真实设备与主机之间转发传输，并由过滤器记录、解码或修改传输内容，用于 USB 协议分析；README 指出，这适用于无法控制其软件的设备，例如嵌入式系统或游戏主机。第 3 版从头重写了仿真核心，内置键盘、大容量存储和 FTDI 串口设备模型以及 HID 与日志代理过滤器，不再支持旧版 2.9.x 脚本。",
  "entry_url": "https://awesomerea.org/resources/facedancer/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/facedancer/",
  "evidence_url": "https://github.com/greatscottgadgets/facedancer/blob/9f1298856e8ec6871cca995ded3076ab89dd72cd/README.md",
  "group": "tools",
  "id": "facedancer",
  "json_url": "https://awesomerea.org/resources/facedancer/record.json",
  "kind": "tool",
  "markdown_url": "https://awesomerea.org/resources/facedancer/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/facedancer/index.md",
  "name": "Facedancer",
  "name_zh": "Facedancer USB 设备仿真与代理库",
  "record_type": "resource",
  "relationship": "foundation",
  "requirements": [
    "Needs a supported board selected with the BACKEND variable: Cynthion (cynthion), GreatFET One and other LPC4330 boards (greatfet), GoodFET-based Facedancers such as the Facedancer21 (goodfet), Raspberry Pi Raspdancer boards (raspdancer) or HydraDancer and HydraUSB3 (hydradancer). The README says MAX3420/MAX3421-based boards cannot emulate more complex devices or act as USBProxy MITM devices, and that HydraDancer boards do not support host mode.",
    "Latest release at review: 3.1.3, published 2026-05-22 on GitHub and PyPI and identical to the reviewed main commit; pyproject.toml requires Python 3.10+ with pyusb, libusb1, pyserial, prompt-toolkit and hid-parser. The README says Facedancer 3.0 does not work on Windows and runs only on GNU/Linux, while the getting-started guide narrows the warning to Windows control hosts with GreatFET and the proxy guide says USBProxy must run as root on macOS to claim the proxied device.",
    "USBProxy needs the real device being proxied, identified by its vendor and product IDs, and the analyst's filters decide what is forwarded, logged or changed; the README calls the proxy feature complete but in need of more documentation. The repository holds Python sources, examples, tests and documentation, with no board firmware. Emulate and proxy only hosts and devices you own or are authorized to test.",
    "BSD-3-Clause licensed."
  ],
  "requirements_zh": [
    "需要用 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 许可。"
  ],
  "targets": [
    "protocol"
  ],
  "url": "https://github.com/greatscottgadgets/facedancer",
  "verification": "source-reviewed",
  "verified_at": "2026-10-27"
}