返回更新列表
新发布Aug 31, 2026

USBvalve v1.0.1

实时暴露 USB 活动

分享

logo, landscape, dark text, transparent background

[!NOTE] USBvalve 版本 1.0.0

应用程序已完成全面重写：

  • 已脱离 Arduino IDE 环境，现在代码基于 Pi Pico SDK 编写
  • 对外部库的依赖已大幅减少
  • 对低速设备的 USB 主机支持现在更加稳健（ATTiny85、EvilCrow 等）
  • 硬件和功能几乎未变，详情请参阅下方的说明

实时暴露 USB 活动

The two models The Watch 1.2

我相信，和我一样，你曾被要求将 U 盘插入一个未知设备……然后心生疑虑：

我那可怜的 U 盘在幕后到底遭遇了什么？窃取我的文件？加密它们？还是仅仅安装恶意软件？有了 USBvalve，你可以在几秒钟内查明真相：它基于极其廉价且现成的硬件构建，你可以快速测试任何 USB 文件系统活动，在一切为时已晚之前了解正在发生什么！

使用 USBvalve，你可以立即获得关于 U 盘所发生情况的反馈；屏幕会显示设备上构建的伪造文件系统是否被访问、读取或写入：

Selftest Readme

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

HID

以下是串口上可用的 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：Gerber 文件，如果你想打印定制 PCB。这不是必需的，你可以使用自己的 PCB 或在面包板上搭建

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

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

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

STL：外壳的 STL 文件。在 1.1 和 1.2 文件夹中有完整外壳（感谢 WhistleMaster）。在 1.2_64 和 1.2_64_simple 文件夹中有适用于 128x64 屏幕的外壳（感谢 rtmq0227）。如果你想要更轻便的东西来保护 LCD，可以使用 USBvalve_sliding_cover.stl。

构建 USBvalve

零件清单

如果你想自己构建，你需要：

关于 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 的固件（参见文件夹和发布版本）。

构建说明

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

几乎所有工作都由软件直接在板子上完成，因此你只需安排与 OLED 的连接以进行输出。

从固件 0.8.0 版本起，USBvalve 可以检测 HID 设备（用于检测 BADUSB）。这需要一个额外的 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 背面的这两个焊盘上点一团焊锡：

否则你应该反过来，将焊锡点在另外的焊盘上：

不使用 USBvalve PCB

Pico Pi

如果你使用面包板或只是接线，你只需确保将正确的引脚连接到 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 USBpipe

USBpipe 是专为此项目设计的 PCB。

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

Front Back

烧录固件

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

  • 按住 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/
//
#define USB_VENDORID       0xCAFE
#define USB_PRODUCTID      0x1337
#define USB_DESCRIPTOR     "DataStore"
#define USB_MANUF          "USB Acme"
#define USB_SERIAL         "123456789A"
#define USB_VENDORID_STR   "Acme"            // Up to 8 chars
#define USB_PRODUCTID_STR  "DataStore"       // 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 开发做出贡献的人。 以下是一份非官方/不完整/不受支持的列表：

安全警告

[!WARNING] 我收到了很多关于 USBvalve 和 USB killer 设备的问题。USBvalve 并非为测试这些设备而构建，它没有任何形式的绝缘或保护，因此如果你怀疑自己面对的是这类设备之一，请用其他东西测试，不要用 USBvalve，否则你可能会损坏设备、伤害自己或附近的物体。

阅读更多

分类

嵌入式系统安全动态分析 (沙盒)取证分析恶意软件分析硬件安全