Using Cynthion with Facedancer

Together with Facedancer, Cynthion can be used to quickly and easily emulate USB devices controlled from Python running on the host computer.

Before proceeding, please ensure you have completed all steps in the Getting Started with Cynthion section.

Install the Facedancer library

You can install the Facedancer library from the Python Package Index (PyPI), a release archive or directly from source.

Install From PyPI

You can use the pip tool to install the Facedancer library from PyPI using the following command:

pip install facedancer

For more information on installing Python packages from PyPI please refer to the “Installing Packages” section of the Python Packaging User Guide.

Install From Source

git clone https://github.com/greatscottgadgets/facedancer.git
cd facedancer/

Once you have the source code downloaded you can install the Facedancer library with:

pip install .

Load Facedancer Bitstream and Firmware

You can run the Facedancer Bitstream and Firmware by running:

cynthion run facedancer

You can verify that everything is working by running:

cynthion info

You should see output like:

Detected a Cynthion device!
    Bitstream: Facedancer (Cynthion Project)
    Hardware: Cynthion r1.4
    Flash UID: xxxxxxxxxxxxxxxx

Connect Hardware

Make sure that the target host is running a program that can receive keyboard input such as a terminal or text editor and that it has focus.

Run a Facedancer example

Create a new Python file called rubber-ducky.py with the following content:

import asyncio

from facedancer                   import main
from facedancer.devices.keyboard  import USBKeyboardDevice

device = USBKeyboardDevice()

async def type_letters():
    # Wait for device to connect
    await asyncio.sleep(2)

    # Type a string with the device
    await device.type_string("echo hello, facedancer\n")

main(device, type_letters())

Open a terminal and run:

python ./rubber-ducky.py

If all goes well, you should see the string hello, facedancer typed into the target host.

More Information

For further information, see the Facedancer documentation.