Facedancer 3.0

本仓库承载了下一代 Facedancer 软件。它源自最初的基于 GoodFET 的 Facedancer，本仓库提供了一个 Python 模块，可提供扩展的 Facedancer 支持——包括对多种板卡的支持以及一些相当重要的新功能。

项目文档

Facedancer 的文档托管在 Read the Docs 上。原始文档源文件位于 docs/ 文件夹中。

安装

使用以下命令安装此包：

pip install facedancer

之后你可以像往常一样导入 facedancer 包：

$ python
>>> import facedancer

我的脚本在哪里？

Facedancer 3.0 是对原始仿真核心的彻底重写， 不支持旧版脚本。

如果你使用的脚本或培训材料依赖于在 v3.0.x 中已弃用的功能 或 API，你可以通过以下命令安装最新的 v2.9.x 版本的 Facedancer：

pip install "facedancer<=3"

旧版 applet 和示例可以在 v2.9.x 分支中找到。

什么是 Facedancer？

Facedancer 板卡是一种简单的硬件设备，充当“远程控制”的 USB 控制器。配合适当的软件，你可以使用这些板卡快速且 轻松地仿真 USB 设备——以及模糊测试 USB 主机控制器！

这个特定的软件仓库目前允许你轻松地用 Python 创建 USB 设备的仿真。控制粒度足够精细，你可以制造各种 USB 异常行为。:)

更多信息，请参见：

• Travis Goodspeed 关于 Facedancer 的博客文章
• Facedancer 21，最初支持的板卡

USBProxy 'Nouveau' 与协议分析

较新的 Facedancer 代码库的一个主要新功能是能够对 USB 连接进行 MITM（中间人）攻击——取代了作者之一最初的 USBProxy 项目。这开辟了一个全新的应用领域——包括协议分析 和 USB 数据包的实时操纵——并且当你无法控制 目标设备上运行的软件时（例如在嵌入式系统或游戏主机上）尤其有用。

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

此功能已完成，但还需要更多文档。欢迎提交 Pull Request。:)

我该如何使用这个仓库？

首先，你很可能需要设置 BACKEND 环境变量，它让 软件知道你希望使用哪种类型的 Facedancer 板卡。如果未设置此变量， 软件将根据已连接的设备尝试为你猜测。它并不 总能做出最佳猜测，所以最好自己设置。

接下来，你很可能想查看其中一个示例，或其中一个预制脚本。 新语法下的示例位于 examples 下。“旧”语法下的核心 Facedancer 脚本 位于 legacy-applets 中。

例如：

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

目前支持哪些板卡？

• Cynthion USB 测试仪器（BACKEND=cynthion）
• GreatFET One（BACKEND=greatfet）
• NXP LPC4330 Xplorer 板卡。（BACKEND=greatfet）
• 带有 GreatFET l0adable 的 CCCamp 2015 rad1o 徽章（BACKEND=greatfet）
• 所有基于 GoodFET 的 Facedancer，包括常见的 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

哪些板卡可能很快得到支持？

• 任何支持 gadgetfs 的 Linux 计算机（例如 Pi Zero 或 Beaglebone Black）
• 任何支持 USB-over-IP 的设备。

你计划添加哪些功能？

路线图正在制定中，但除了多板卡支持外，本仓库 最终将包含一些很酷的新功能，包括：

• 在具有 USB 2.0 PHY 的设备上进行高速（“USB 2.0”）设备仿真。
• 在 gateware 中即时生成 USB 设备控制器。

这该怪谁？

这个仓库之所以如此出色，要归功于很多人， 包括：

• Kate Temkin (@ktemkin)
• Travis Goodspeed (@travisgoodspeed)
• Sergey Bratus (@sergeybratus)
• Dominic Spill (@dominicgs)
• Michael Ossmann (@michaelossmann)
• Mikaela Szekely (@Qyriad)
• 任何名字出现在 git 历史中的人 :)

贡献？

……随时欢迎。给我们发个 PR 吧！