<h1><img width="300" alt="logo, landscape, dark text, transparent background" src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/USBvalve_logo_scaled.png"></a></h1> > [!NOTE] > **USBvalve 版本 1.0.0** > > 应用程序已完成全面重写: > - 已脱离 Arduino IDE 环境,现在代码基于 [Pi Pico SDK](https://github.com/raspberrypi/pico-sdk) 编写 > - 对外部库的依赖已大幅减少 > - 对低速设备的 USB 主机支持现在更加稳健(ATTiny85、EvilCrow 等) > - 硬件和功能几乎未变,详情请参阅下方的[说明](https://github.com/cecio/USBvalve#notes-about-bootsel-and-version--100) ### *实时暴露 USB 活动* <p float="left"> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/versions.png" alt="The two models" width="30%" height="30%" /> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/USBvalve_PIWATCH.png" alt="The Watch" width="26%" height="26%" /> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/version1_2.png" alt="1.2" width="26%" height="26%" /> </p> 我相信,和我一样,你曾被要求将 U 盘插入一个*未知*设备……然后心生疑虑: 我那可怜的 U 盘在幕后到底遭遇了什么?窃取我的文件?加密它们?还是*仅仅*安装恶意软件?有了 **USBvalve**,你可以在几秒钟内查明真相:它基于极其廉价且现成的硬件构建,你可以快速测试任何 USB 文件系统活动,在一切为时已晚之前了解正在发生什么! 使用 **USBvalve**,你可以立即获得关于 U 盘所发生情况的反馈;屏幕会显示设备上构建的*伪造*文件系统是否被访问、读取或写入: <p float="left"> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/selftest.png" alt="Selftest" width="15%" height="15%" /> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/readme.png" alt="Readme" width="15%" height="15%" /> </p> 从 `0.8.0` 版本起,你还可以将其用作 USB 主机来检测 *BADUSB* 设备: <p float="left"> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/hid.png" alt="HID" width="15%" height="15%" /> </p> 以下是串口上可用的 *BADUSB* 调试器示例: <p float="left"> <a href="https://asciinema.org/a/NWfC9Mvzzpj3eZfsC7s5Dz1sJ" target="_blank"><img src="https://asciinema.org/a/NWfC9Mvzzpj3eZfsC7s5Dz1sJ.svg" width="65%" height="65%" /></a> </p> 如果你更喜欢视频,也可以看看我的 [Insomni'hack 演讲](https://www.youtube.com/watch?v=jy1filtQY4w) ## USBvalve Watch 从 `0.15.0` 版本起,支持新的 *Pi Pico Watch* 版本。要编译新版本,你需要在代码开头取消注释 `#define PIWATCH` 这一行。硬件是基于 RP2040 的 1.28 英寸 TFT 显示屏手表板。你可以[在此](https://www.raspberrypi.com/news/how-to-build-your-own-raspberry-pi-watch/)找到更多信息。 它也与 [Waveshare RP2040-LCD-1.28](https://www.waveshare.com/wiki/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](https://github.com/WhistleMaster))。在 `1.2_64` 和 `1.2_64_simple` 文件夹中有适用于 128x64 屏幕的外壳(感谢 [rtmq0227](https://github.com/rtmq0227))。如果你想要更轻便的东西来保护 LCD,可以使用 `USBvalve_sliding_cover.stl`。 ## 构建 USBvalve ### 零件清单 如果你想自己构建,你需要: - 一块 Raspberry Pi Pico 1 或 2(或其他基于 RP2040 的板子) - 一块 I2C OLED 屏幕 128x64 或 128x32(**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 事件) <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/reset_button.jpg" width="35%" height="35%" /> 在 `PCB` 中你还会找到板子的 `1.3` 版本,焊盘 1 和 3 上有一些孔,便于安装按钮。但如你所见,你也可以使用旧版本。 如果你不使用 *BADUSB* 功能,或者你希望降低检测覆盖率但保留 BOOTSEL 的使用,我也提供了一个启用了 *bootsel* 的固件(参见文件夹和发布版本)。 ### 构建说明 > 感谢 [Tz1rf](https://github.com/Tz1rf),我们还有两个很棒的视频:一个逐步讲解[构建](https://youtu.be/7ymk8hD7-Hc)过程,另一个展示如何[上传固件](https://youtu.be/Tp8xvrlqxUY)并使用该工具。 几乎所有工作都由软件直接在板子上完成,因此你只需安排与 OLED 的连接以进行输出。 从固件 0.8.0 版本起,**USBvalve** 可以检测 HID 设备(用于检测 *BADUSB*)。这需要一个额外的 USB 端口作为主机。如果你对此不感兴趣,可以使用[文档文件夹中](https://github.com/cecio/USBvalve/blob/main/docs/BUILDING-1.1.md)的旧说明并使用 PCB `1.1` 版本。否则请继续使用 PCB `1.2` 版本(我们有适用于 USB-A 或 USB-B 的版本,参见文件夹)。 #### 使用 USBvalve PCB <p float="left"> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/USB_valve_1-2_front.png" width="25%" height="25%" /> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/USB_valve_1-2_back.png" width="24%" height="24%" /> </p> - 在 `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,像这样: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_oled.png" width="35%" height="35%" /> 你需要在 PCB 背面的这两个焊盘上点一团焊锡: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_pads.png" width="15%" height="15%" /> 否则你应该反过来,将焊锡点在另外的焊盘上: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_pads_2.png" width="15%" height="15%" /> #### 不使用 USBvalve PCB <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/pico-pinout.svg" alt="Pico Pi" width="85%" height="85%" /> 如果你使用面包板或只是接线,你只需确保将正确的引脚连接到 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 中 <img src="https://assets.kitploit.com/production/public/readmes/48341/248d33e236b13cc7c59905288ca1e06ae7a0ff36a3b7e99d2f66c4b27e5ab2bf.jpg" alt="USBpipe PCB" width="15%" height="15%"/> <img src="https://assets.kitploit.com/production/public/readmes/48341/0159e8d6a4d68b6edcad459a6ebfcdce0f5787f2bca0ea5f06c6b3538baf75a2.jpg" alt="USBpipe" width="15%" height="15%"/> [USBpipe](https://github.com/LiPolymer/smartUSBPipe) 是专为此项目设计的 PCB。 你可以在 `./PCB/USBpipe/` 文件夹中找到所需的一切。 <img src="https://assets.kitploit.com/production/public/readmes/48341/39c4a838734e4710cfe68529931961f387b1723654d5a4d3b1243d05925aa765.png" alt="Front" width="20%" height="20%"/> <img src="https://assets.kitploit.com/production/public/readmes/48341/b34c6e01b06808aa0c21f17086d864b4b02fe4b4b453374d2840ae914aa524d6.png" alt="Back" width="20%" height="20%"/> ### 烧录固件 要烧录固件,请按照以下步骤操作: - 按住 *BOOTSEL* 按钮(板子上大的白色按钮)的同时,用 USB 线连接 Raspberry Pi Pico - 松开按钮 - 你会在系统中看到一个新驱动器,名为 `RPI-RP2`(在 Linux 环境中你可能需要手动挂载它) - 根据你使用的 OLED,将相应的固件文件(扩展名为 `uf2`)复制到该文件夹中 - 等待几秒钟,直到挂载的文件夹消失 完成了! ### 反检测 我不知道是否真的会用到,但你可能希望自定义固件,以避免被*能识别 USBvalve 的*恶意软件检测到 :-) 我将你可能想要修改的大部分变量集中在了 `usb_config.h` 的这一部分([参见下方的 Dockerfile 进行重新构建](https://github.com/cecio/USBvalve#dockerfile)) ```C // 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](https://twitter.com/red5heep) ### 社区版本 社区创建了一些分支,实现了对其他板子的支持或其他修改。**感谢每一位**为 **USBvalve** 开发做出贡献的人。 以下是一份非官方/不完整/不受支持的列表: - [USBvalve-tbfa-Mod](https://github.com/TryBreakFixAgain/USBvalve-tbfa-Mod) ## 安全警告 > [!WARNING] > 我收到了很多关于 **USBvalve** 和 *USB killer 设备*的问题。**USBvalve** 并非为测试这些设备而构建,它没有任何形式的绝缘或保护,因此如果你怀疑自己面对的是这类设备之一,请用其他东西测试,不要用 **USBvalve**,否则你可能会损坏设备、伤害自己或附近的物体。