AwesomeREA.org

Tool

Facedancer

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.

Targets
Protocol
Category
Protocol analysis tools
Relationship
Foundation tool
Sources reviewed

Requirements & limits

  • 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. No hardware was connected and no USB traffic was captured.

About this entry

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · greatscottgadgets/facedancer · Revision 9f12988
  2. README.md#L55-L77 GitHub · greatscottgadgets/facedancer · Revision 9f12988
  3. README.md#L98-L117 GitHub · greatscottgadgets/facedancer · Revision 9f12988
  4. docs/source/using_usb_proxy.rst GitHub · greatscottgadgets/facedancer · Revision 9f12988
  5. docs/source/getting_started.rst GitHub · greatscottgadgets/facedancer · Revision 9f12988
  6. facedancer/filters GitHub · greatscottgadgets/facedancer · Revision 9f12988
  7. facedancer/devices GitHub · greatscottgadgets/facedancer · Revision 9f12988
  8. pyproject.toml GitHub · greatscottgadgets/facedancer · Revision 9f12988
  9. CHANGELOG.md GitHub · greatscottgadgets/facedancer · Revision 9f12988
  10. LICENSE GitHub · greatscottgadgets/facedancer · Revision 9f12988
  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/

More in Protocols

All 66 entries in Protocols