[!NOTE] USBvalve 版本 1.0.0

该应用程序已进行完全重写：

• 已脱离 Arduino IDE 环境,现在代码为 Pi Pico SDK 编写
• 对外部库的依赖已大幅减少
• 对低速(Low Speed)设备的 USB 主机支持现在更加稳健(ATTiny85、EvilCrow 等)
• 硬件和功能几乎保持不变,详见下文说明

即时暴露 USB 活动

我相信,你一定也像我一样,曾被人要求把 U 盘插入某个未知设备……然后心中泛起疑虑：

我的可怜 U 盘在幕后到底发生了什么？是在窃取我的文件？加密它们？还是仅仅在安装恶意软件？有了 USBvalve,你可以在几秒钟内查明这一切：它基于超便宜的现成硬件构建,让你能快速测试任何 USB 文件系统活动,并在为时已晚之前弄清正在发生什么！

借助 USBvalve,你可以即时了解 U 盘发生了什么；当设备上构建的虚假文件系统被访问、读取或写入时,屏幕都会显示出来：

从 0.8.0 版本开始,你还可以将其用作 USB 主机来检测 BADUSB 设备：

这是串口上可用的 BADUSB 调试器示例：

如果你更喜欢视频,还可以观看我的 Insomni'hack 演讲

USBvalve Watch

从 0.15.0 版本开始,新增支持 Pi Pico Watch 版本。要编译新版本,你需要在代码开头取消注释 #define PIWATCH 这一行。该硬件是基于 RP2040 的 1.28 英寸 TFT 显示屏和手表板。你可以在此找到更多信息。 这也与 Waveshare RP2040-LCD-1.28 完全兼容。

仓库结构

docs：项目文档,其中包含一份演示文稿,可让你了解全部功能

firmware：为 Raspberry Pi Pico 预构建的固件。你可以直接使用这些固件并将其烧录到开发板上。我们有多个不同版本,适用于 32 或 64 行 OLED、Pico 1 或 Pico2、Pi Pico Watch 等

PCB：如果你想打印定制 PCB,这里有 Gerber 文件。这不是必需的,你可以使用自己的 PCB,或在面包板上搭建

src 和 data：源码,如果你想自行修改并构建固件

utils：一些可用于构建自定义文件系统(FS)的工具

pictures：本文档中使用的图片和资源

STL：外壳的 STL 文件。在 1.1 和 1.2 文件夹中是完整外壳(感谢 WhistleMaster)。在 1.2_64 和 1.2_64_simple 文件夹中是适用于 128x64 屏幕的外壳(感谢 rtmq0227)。如果你想要更轻量的 LCD 保护方案,可以选择 USBvalve_sliding_cover.stl。

构建 USBvalve

零件清单

如果你想自行构建,你需要：

• 一块 Raspberry Pi Pico 1 或 2(或其他基于 RP2040 的开发板)
• 一块 128x64 或 128x32 的 I2C OLED 屏幕(SSD1306)
• (可选)一块 USBvalve PCB 或面包板
• (可选)一个 3D 打印的隔离垫片,用于将屏幕与开发板隔开 (https://www.thingiverse.com/thing:4748043),但你也可以用一段电工胶带代替

关于 BOOTSEL 和版本 >= 1.0.0 的说明

在 0.x.x 版本中,BOOTSEL 用于重置设备或打印 HID 事件数量(按住 > 2 秒)。 对 BOOTSEL 的轮询给 BADUSB 检测带来了一些问题,因此从 1.0.0 版本开始移除了该功能,并替换为以下两个选项：

• 在 GP0 与 GND 之间焊接一个按钮(第 1 和第 3 焊盘,见下图示例)以获得相同的功能
• 从串口监视器使用 r(重置)和 h(HID 事件)命令

在 PCB 文件夹中,你还会找到 1.3 版本的板子,它在第 1 和第 3 焊盘上开了孔,方便安装按钮。但如你所见,你同样可以使用旧版本。

如果你不使用 BADUSB 功能,或者你希望在检测覆盖上稍作取舍但仍保留 BOOTSEL 的使用,我还提供了一个启用了 bootsel 的固件(见文件夹和 releases)。

构建说明

感谢 Tz1rf,我们还有两段很棒的视频：一段逐步讲解构建过程,另一段演示如何上传固件并使用该工具。

几乎所有工作都由软件在开发板上直接完成,因此你只需要接好 OLED 的连接用于输出即可。

从固件 0.8.0 版本开始,USBvalve 可以检测 HID 设备(用于检测 BADUSB)。这需要一个充当主机(Host)角色的额外 USB 端口。如果你对此不感兴趣,可以使用文档文件夹中的旧版说明,并使用 PCB 1.1 版本。否则请使用 PCB 1.2 版本(我们提供 USB-A 或 USB-B 两种版本,见文件夹)。

使用 USBvalve PCB

• 在 USBH 区域焊接一个 USB 母口。这适用于 A 版本,但如果你愿意,也有 USB Micro-B 版本
• 将 Raspberry Pi Pico 放置在正面的丝印位置上
• 无需焊接所有引脚,只需以下这些：
  • D4 和 D5(左侧)
  • D14 和 D15(左侧)
  • GND(右侧,从上往下数第三个引脚)
  • GND(右侧,从下往上数第三个引脚)
  • 3v3_OUT(右侧)
  • VBUS(右侧)
  • 底部的 3 个 DEBUG 引脚：SWCLK、GND 和 SWDIO
• 在 OLED 上可能触碰到 Raspberry 的部位放置 3D 打印垫片或一段胶带
• 将 OLED(带排针)焊接到 4 个 PIN 的位置上

有些 OLED 的 GND 和 VCC 引脚是颠倒的,因此我把 PCB 设计成兼容两种情况：

例如,如果你的 OLED 是 PIN1 为 GND、PIN2 为 VCC,像这样：

你需要在 PCB 背面的这两个焊盘上放置一点焊锡：

否则,你应该做相反的操作,把焊锡放在另外的 PAD 上：

不使用 USBvalve PCB

如果你使用面包板或直接接线,你只需确保将正确的引脚连接到 OLED 屏幕和主机 USB 端口即可。

引脚映射如下：

• Pi 的 PIN6 --> OLED SDA
• Pi 的 PIN7 --> OLED SCL
• Pi 的 PIN19 --> USB 主机的 D+
• Pi 的 PIN20 --> USB 主机的 D-
• Pi 的 PIN23 (GND) --> USB 主机的 GND
• Pi 的 PIN38 (GND) --> OLED 的 GND
• Pi 的 PIN36 (3V3OUT) --> OLED 的 VCC
• Pi 的 PIN40 (VBUS) --> USB 主机的 VCC

如果你想使用 DEBUG 功能,还可以在板子底部的 3 个 SWD 引脚上放置一个排针。

使用 USBpipe PCB

[!CAUTION] 此 PCB 面向经验丰富的电子制作爱好者 如果你不确定自己能驾驭它,请不要使用！

[!NOTE] R7 和 R8 实际上没有连接到任何东西。它们是为电路调试而添加的。 因此它们不会出现在物料清单(BOM)中

USBpipe 是这个项目的专用 PCB。

你可以在 ./PCB/USBpipe/ 文件夹中找到所需的一切。

烧录固件

要烧录固件,请按以下步骤操作：

• 按住 BOOTSEL 按钮(板上的白色大按钮),用 USB 线连接 Raspberry Pi Pico
• 松开按钮
• 系统上会出现一个新的驱动器,名为 RPI-RP2(在 Linux 环境下,你可能需要手动挂载它)
• 根据你使用的 OLED,将相应的固件文件(扩展名为 uf2)复制到该文件夹中
• 等待几秒钟,直到挂载的文件夹消失

大功告成！

反检测

我不知道这种情况是否会发生,但你也许想要定制固件,以避免被能识别 USBvalve 的恶意软件检测到 :-)

我把你可能想要修改的大部分变量集中放在了 usb_config.h 的这一部分中(重新构建请参阅下面的 Dockerfile)

// USB anti-detection settings
//
// Set USB IDs strings and numbers, to avoid possible detections.
// Remember that you can cusotmize FAKE_DISK_BLOCK_NUM as well
// for the same reason. Also DISK_LABEL in ramdisk.h can be changed.
//
// You can see here for inspiration: https://the-sz.com/products/usbid/
//
// Example:
//             0x0951 0x16D5    VENDORID_STR: Kingston   PRODUCTID_STR: DataTraveler
//
#define USB_VENDORID       0x0951
#define USB_PRODUCTID      0x16D5
#define USB_DESCRIPTOR     "DataTraveler"
#define USB_MANUF          "Kingston"
#define USB_SERIAL         "123456789A"
#define USB_VENDORID_STR   "Kingston"        // Up to 8 chars
#define USB_PRODUCTID_STR  "DataTraveler"    // Up to 16 chars
#define USB_VERSION_STR    "1.0"             // Up to 4 chars

构建你自己的固件

显然,你也可以构建自己的固件。要构建,你需要 Raspberry Pi Pico SDK 和这个仓库。

基本重新编译说明：

export PICO_SDK_PATH=</path/to/pico-sdk>

git clone --recursive https://github.com/cecio/USBvalve.git
cd USBvalve
mkdir build && cd build
cmake -DPICO_BOARD=pico ..   # or pico2 for standard build
make -j$(nproc)
# Output: build/src/USBvalve.uf2

如果你想重新创建一个新的虚假文件系统,可以看看 utils 文件夹,我在其中放置了一些用于构建新文件系统的工具。

Dockerfile

如果你在定制后想要构建自己的固件,我提供了一个 Dockerfile,它会构建完整的编译环境并编译固件。

在主 USBvalve 文件夹中输入以下命令进行构建：

# To Build:
#       docker build -t usbvalve-sdk -f Dockerfile.sdk .
#
# To Run (default: pico, SSD1306 OLED 128x32):
#       docker run --rm -v $PWD:/mnt usbvalve-sdk
#
# Options (via environment variables):
#       BOARD=pico|pico2          Board target (default: pico)
#       OLED_HEIGHT=32|64         OLED display height (default: 32)
#       PIWATCH=1                 Use GC9A01 round TFT instead of SSD1306
#       USE_BOOTSEL=1             Enable BOOTSEL button (disrupts Low Speed USB)
#
# Examples:
#       docker run --rm -e BOARD=pico2 -v $PWD:/mnt usbvalve-sdk
#       docker run --rm -e PIWATCH=1 -v $PWD:/mnt usbvalve-sdk
#       docker run --rm -e BOARD=pico2 -e OLED_HEIGHT=64 -v $PWD:/mnt usbvalve-sdk

固件将以 uf2 扩展名输出到 USBvalve_out 文件夹中。

贡献

如果你有任何想法或改进意见,欢迎你提交 issue,让我们一起改进这个项目！谢谢！

支持

如果你有问题或需要支持,可以在此处提交 Issue,也可以在 Twitter/X 上联系我 @red5heep

社区版本

社区创建了一些分支,实现了对其他开发板的支持或其他修改。感谢每一位为 USBvalve 的开发做出贡献的人。 以下是非官方/不完整/不受支持的列表：

• USBvalve-tbfa-Mod

安全警告

[!WARNING] 我收到了很多关于 USBvalve 和 USB killer 设备 的问题。USBvalve 并不是为测试这些设备而设计的,它没有任何形式的绝缘或保护,因此如果你怀疑自己正在处理这类设备,请用其他工具测试,不要使用 USBvalve,否则你可能会损坏设备、伤害自己或附近的物品。