Facedancer 3.0

Этот репозиторий содержит новое поколение программного обеспечения Facedancer. Являясь потомком оригинального Facedancer на базе GoodFET, этот репозиторий предоставляет Python-модуль с расширенной поддержкой Facedancer — включая поддержку нескольких плат и некоторые значительные новые функции.

Документация проекта

Документация Facedancer размещена на Read the Docs. Исходные файлы документации находятся в папке docs/.

Установка

Установите этот пакет с помощью следующей команды:

pip install facedancer

После этого вы можете импортировать пакет facedancer как обычно:

$ python
>>> import facedancer

Где мои скрипты?

Facedancer 3.0 — это полная переработка оригинального ядра эмуляции и не поддерживает устаревшие скрипты.

Если вы используете скрипты или учебные материалы, зависящие от функций или API, устаревших в v3.0.x, вы можете установить последнюю версию v2.9.x Facedancer с помощью:

pip install "facedancer<=3"

Устаревшие апплеты и примеры можно найти в ветке v2.9.x.

Что такое Facedancer?

Платы Facedancer — это простые аппаратные устройства, которые действуют как "дистанционно управляемые" USB-контроллеры. С помощью соответствующего программного обеспечения вы можете использовать эти платы для быстрого и простого эмулирования USB-устройств — а также для фаззинга USB-хостов!

Этот конкретный репозиторий программного обеспечения в настоящее время позволяет легко создавать эмуляции USB-устройств на Python. Управление достаточно детализированное, чтобы можно было вызывать всевозможные некорректные поведения USB. :)

Для получения дополнительной информации см.:

• Запись в блоге Трэвиса Гудспида о Facedancer
• Facedancer 21, оригинальная поддерживаемая плата

USBProxy 'Nouveau' и анализ протоколов

Одной из основных новых функций нового кодовой базы Facedancer является возможность MITM (Meddler-In-The-Middle) USB-соединений — заменяющая оригинальный проект одного из авторов USBProxy. Это открывает целый новый спектр приложений — включая анализ протоколов и манипуляцию USB-пакетами в реальном времени — и особенно полезно, когда вы не контролируете программное обеспечение, работающее на целевом устройстве (например, на встраиваемых системах или игровых консолях).

                 +-----------------------------------------------------------------------+
+------------+   |  +--------------------------------+   +---------------------------+   |  +--------------+

|            |   |  |                                |   |                           |   |  |              |
|  PROXIED   |   |  |         HOST COMPUTER          |   |    FACEDANCER DEVICE      |   |  |  TARGET USB  |
|   DEVICE   <------>  running Facedancer software   <--->  acts as USB-Controlled   <------>     HOST     |
|            |   |  |                                |   |      USB Controller       |   |  |              |
|            |   |  |                                |   |                           |   |  |              |
+------------+   |  +--------------------------------+   +---------------------------+   |  +--------------+

                 |                                                                       |
                 |                    MITM Setup (HOST + FACEDANCER)                     |
                 +-----------------------------------------------------------------------+

Эта функция завершена, но ей не хватает документации. Приветствуются пулл-реквесты. :)

Как использовать этот репозиторий?

Сначала вам, вероятно, захочется установить переменную окружения BACKEND, которая сообщает программному обеспечению, какой тип платы Facedancer вы хотите использовать. Если эта переменная не установлена, программное обеспечение попытается угадать на основе подключённых устройств. Оно не всегда делает лучшие предположения, поэтому вам, вероятно, лучше установить её самостоятельно.

Далее, вероятно, вы захотите ознакомиться с одним из примеров или готовых скриптов. Примеры в новой синтаксисе находятся в папке examples. Основные скрипты Facedancer в "старом" синтаксисе находятся в legacy-applets.

Например:

export BACKEND=greatfet
./examples/rubber-ducky.py

Какие платы в настоящее время поддерживаются?

• Cynthion USB Test Instrument (BACKEND=cynthion)
• GreatFET One (BACKEND=greatfet)
• Плата NXP LPC4330 Xplorer. (BACKEND=greatfet)
• Значок CCCamp 2015 rad1o с загружаемым модулем GreatFET (BACKEND=greatfet)
• Все Facedancer на базе GoodFET, включая распространённый Facedancer21 (BACKEND=goodfet)
• Платы RPi + Max3241 Raspdancer (BACKEND=raspdancer)
• Платы HydraDancer и HydraUSB3 (BACKEND=hydradancer)

Обратите внимание, что аппаратные ограничения не позволяют платам MAX3420/MAX3421 эмулировать более сложные устройства — существуют ограничения на количество/тип конечных точек, которые можно настроить. Платам на базе LPC4330, таким как GreatFET, присущи меньшие ограничения.

По аналогичной причине платы MAX3420/MAX3421 (BACKEND=goodfet или BACKEND=raspdancer) в настоящее время не могут использоваться в качестве устройств USBProxy-nv MITM. Все современные платы (BACKEND=greatfet, BACKEND=hydradancer) должны быть полностью функциональны.

Обратите внимание, что платы HydraDancer и HydraUSB3 (BACKEND=hydradancer) в настоящее время не поддерживают режим хоста. Обратите внимание, что фактический FaceDancer 3.0 не работает в Windows (некоторые проблемы с pyusb...) и только в GNU/Linux.

Какие платы могут быть поддержаны в ближайшее время?

• Любой компьютер с Linux с поддержкой gadgetfs (например, Raspberry Pi Zero или Beaglebone Black)
• Любые устройства с поддержкой USB-over-IP.

Какие функции планируется добавить?

Дорожная карта находится в разработке, но помимо поддержки нескольких платформ, этот репозиторий в будущем станет домом для ряда крутых новых функций, включая:

• Эмуляцию высокоскоростных устройств ("USB 2.0") на устройствах с USB 2.0 PHY.
• Генерацию USB-контроллеров устройств на лету в гейтвере.

Кто виноват в этом всём?

Есть много людей, которых можно винить за крутость этого репозитория, в том числе:

• Кейт Темкин (@ktemkin)
• Трэвис Гудспид (@travisgoodspeed)
• Сергей Братусь (@sergeybratus)
• Доминик Спилл (@dominicgs)
• Майкл Оссманн (@michaelossmann)
• Микаэла Секейи (@Qyriad)
• все, чьи имена встречаются в истории git :)

Вклад?

... всегда приветствуется. Присылайте пулл-реквесты!