modern FaceDancer core for multiple devices-- including GreatFET
Switch branches/tags
Nothing to show
Clone or download
ktemkin Merge pull request #7 from wchill/master
Add Pro Controller emulation for GreatFET
Latest commit 0b55603 Oct 11, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
facedancer USBProxy: always deteach the _active_ configuration, if possible Sep 13, 2018
.gitignore Ignore tags files. Mar 11, 2017
LICENSE Make the license explicit #6 Oct 10, 2018
README.md Ensure README is valid markdown Sep 12, 2017
SPIFlash.py Add Pro Controller emulation for GreatFET Oct 2, 2018
USBFtdi.py Clean up autodetection to work if not all libraries are installed. Mar 11, 2017
USBKeyboard.py Initial commit of GreatFET facedancer code. Jan 31, 2017
USBMassStorage.py USB mass storage: use correct blocking behaviour Feb 27, 2018
USBProController.py Add Pro Controller emulation for GreatFET Oct 2, 2018
USBQCEDL.py Add QC Sahara EDL support Apr 3, 2018
USBSerial.py USBProxy: expand API and add basic support for the FaceDancer21 Sep 14, 2017
USBSwitchTAS.py Add simple prototype controller replay for the Nintendo Switch. Dec 10, 2017
facedancer-edl.py Add QC Sahara EDL support Apr 3, 2018
facedancer-ftdi.py Update a few demo scripts. Feb 9, 2017
facedancer-host-enumeration.py Host: enumeration example: improve documentation slightly Sep 5, 2018
facedancer-keyboard.py Update a few demo scripts. Feb 9, 2017
facedancer-procontroller.py Add Pro Controller emulation for GreatFET Oct 2, 2018
facedancer-serial.py First attempt at a nice, multi-device Facedancer repo. Feb 9, 2017
facedancer-switchtas.py Add simple prototype controller replay for the Nintendo Switch. Dec 10, 2017
facedancer-umass.py Fix up UMS, and implement Double-Fetch proof-of-concept. Mar 31, 2017
facedancer-ums-doublefetch.py Don't print access counts on default verbosity. Oct 19, 2017
facedancer-usbproxy.py Add support for detecting NAKs issued to the host, and finish USBProxy. Sep 11, 2017
setup.py Source readme.md from correct location Feb 27, 2018
usbproxy-switch-flip-endpoints.py USBProxy: expand API and add basic support for the FaceDancer21 Sep 14, 2017
usbproxy-switch-invertx.py USBProxy: expand API and add basic support for the FaceDancer21 Sep 14, 2017

README.md

FaceDancer 2.2

This repository houses the next generation of FaceDancer software. Descended from the original GoodFET-based FaceDancer, this repository provides a python module that provides expanded FaceDancer support-- including support for multiple boards and some pretty significant new features.

What is a FaceDancer?

FaceDancer boards are simple hardware devices that act as "remote-controlled" USB controllers. With the proper software, you can use these boards to quickly and easily emulate USB devices-- and to fuzz USB host controllers!

This particular software repository currently allows you to easily create emulations of USB devices in Python. Control is fine-grained enough that you can cause all kinds of USB misbehaviors. :)

For more information, see:

USBProxy 'Nouveau' and Protocol Analysis

A major new feature of the newer FaceDancer codebase is the ability to man-in-the middle USB connections-- replacing one of the authors' original USBProxy project. This opens up a whole new realm of applications-- including protocol analysis and live manipulation of USB packets-- and is especially useful when you don't control the software running on the target device (e.g. on embedded systems or games consoles).

                 +-----------------------------------------------------------------------+
+------------+   |  +--------------------------------+   +---------------------------+   |  +--------------+
|            |   |  |                                |   |                           |   |  |              |
|  PROXIED   |   |  |         HOST COMPUTER          |   |    FACEDANCER DEVICE      |   |  |  TARGET USB  |
|   DEVICE   <------>  running FaceDancer software   <--->  acts as USB-Controlled   <------>     HOST     |
|            |   |  |                                |   |      USB Controller       |   |  |              |
|            |   |  |                                |   |                           |   |  |              |
+------------+   |  +--------------------------------+   +---------------------------+   |  +--------------+
                 |                                                                       |
                 |                    MITM Setup (HOST + FACEDANCER)                     |
                 +-----------------------------------------------------------------------+

This feature is complete, but could use more documentation. Pull requests are welcome. :)

How do I use this repository?

First, you'll likely want to set the BACKEND environment variable, which lets the software know which type of FaceDancer board you'd like to use. If this variable isn't set, the software will try to guess for you based on what's connected. It doesn't always make the best guesses, so you're probably better off setting it yourself.

Next, you can run any of the pre-made scripts, e.g. facedancer-serial.py.

For example:

export BACKEND=goodfet
./facedancer-serial.py

What boards are currently supported?

  • All GoodFET-based facedancers, including the common FaceDancer21 (BACKEND=goodfet)
  • The GreatFET One (BACKEND=greatfet)
  • The NXP LPC4330 Xplorer board (BACKEND=greatfet)
  • The CCCamp 2015 rad1o badge with GreatFET l0adable (BACKEND=greatfet)
  • RPi + Max3241 Raspdancer boards (BACKEND=raspdancer)

Note that hardware restrictions prevent the MAX3420/MAX3421 boards from emulating more complex devices-- there's limitation on the number/type of endpoints that can be set up. The LPC4330 boards-- such as the GreatFET-- don't suffer these limitations.

For a similar reason, the MAX3420/MAX3421 boards (BACKEND=goodfet or BACKEND=raspdancer) currently cannot be used as USBProxy-nv MITM devices. All modern boards (BACKEND=greatfet) should be fully functional.

What boards could be supported soon?

  • Any Linux computer with gadgetfs support (e.g. the Pi Zero or Beaglebone Black)

What features do you plan on adding?

The roadmap is hazy, but in addition to multi-board support, this repository eventually will be home to some cool new features, such as:

  • High-speed ("USB 2.0") device emulation on devices with USB 2.0 PHYS

Whose fault is this?

There are a lot of people to blame for the awesomeness that is this repo, including:

  • Travis Goodspeed (@travisgoodspeed)
  • Sergey Bratus (@sergeybratus)
  • ktemkin (@ktemkin)
  • Dominic Spill (@dominicgs)
  • Michael Ossmann (@michaelossmann)
  • anyone whose name appears in the git history :)

Contributions?

... are always welcome. Shoot us a PR!