bod09/RP2350-Storage-Bridge

# RP2350 存储桥接 **安全检查 USB 驱动器，避免电脑暴露于风险中。** 将不受信任的 USB 闪存盘插入 RP2350 —— 而不是你的电脑。RP2350 读取驱动器的文件系统，并通过串口将文件列表、预览和下载内容流式传输到浏览器。你的电脑永远不会挂载该驱动器，永远不会运行其文件系统驱动程序，也永远看不到来自设备的原始 USB 流量。 为事件响应、安全研究、隔离网络环境以及任何希望在插入前先查看内容的人而设计。 ## 安全模型 | 威胁 | 存储桥接的缓解方式 | |------|-------------------| | **自动运行 / 恶意代码执行** | 驱动器不会被电脑挂载 —— 无自动运行、无外壳扩展、无缩略图处理程序 | | **文件系统驱动程序漏洞** | 操作系统文件系统驱动（NTFS、exFAT 等）从不接触驱动器。RP2350 上的 FatFS 在隔离环境中解析文件系统 | | **恶意 USB 设备攻击** | 驱动器连接到 RP2350 的 USB 主机端口，而非你的电脑。你的电脑仅看到一个标准 HID 键盘 + CDC 串口设备 | | **内容检查** | 内置文件预览（文本、图片、音频、视频、PDF、十六进制编辑器）允许你在不下载的情况下检查内容。魔术字节不匹配检测会标记扩展名与实际内容不符的文件 | | **可疑文件检测** | 已知危险扩展名（.exe、.bat、.ps1、.vbs、.scr、autorun.inf 等）会带有警告图标标记。递归安全扫描并可导出扫描报告 | | **熵分析** | 香农熵计算可标记可能被混淆的恶意软件（如加密、压缩或打包的文件） | | **文件哈希** | 设备端 SHA-256 哈希 —— 在不下载的情况下验证文件完整性 | | **EXIF 元数据** | 查看并从 JPEG 图像中剥离 EXIF 元数据 —— 在下载前移除 GPS 坐标、相机信息等识别数据 | | **浏览器沙箱** | 所有文件渲染均在浏览器的沙箱环境中进行 —— 即使预览恶意文件，也无法突破浏览器沙箱 | ### 限制 - RP2350 固件本身会处理来自不受信任驱动器的 USB 数据包和文件系统数据。精心构造的驱动器理论上可能利用固件（TinyUSB USB 主机栈、FatFS 解析器）。这并非防病毒软件。 - 仅支持 FAT12/16/32 和 exFAT 文件系统。NTFS、ext4、HFS+ 等驱动器无法读取。 - 魔术字节检测覆盖常见文件类型，但并非穷举。这是尽力而为的启发式方法，而非特征码扫描器。 - 文件预览在浏览器中渲染内容。虽然处于沙箱环境，但预览不受信任的 HTML/SVG/JS 文件意味着在浏览器渲染器中执行这些代码。 ## 功能特性 - **文件浏览器** — 以列表或网格视图浏览目录，支持上传、下载、重命名、删除文件 - **文件预览与编辑** — 文本编辑器、带缩放功能的图片查看器、音频/视频播放器、PDF 查看器、完整十六进制编辑器（支持字节级编辑） - **多文件 ZIP 下载** — 选择多个文件并打包为单个 ZIP 存档下载 - **剪贴板粘贴上传** — 直接将图片或文件从剪贴板粘贴到文件浏览器 - **文件夹大小** — 显示目录的递归总大小（在设备上计算） - **SHA-256 哈希** — 在设备端计算文件哈希以验证完整性 - **安全扫描** — 递归威胁扫描、警告图标、熵分析、魔术字节不匹配检测、可导出扫描报告 - **EXIF 查看与剥离** — 检查并从 JPEG 图像中移除 EXIF 元数据 - **递归删除** — 一次性删除目录及其所有内容 - **格式化驱动器** — 从设置页面重新格式化驱动器 - **键盘快捷键** — 方向键、Enter、Delete、Ctrl+A、退格键导航 - **隔离网络指示器** — 视觉确认通过 RP2350 访问驱动器，而非直接连接电脑 - **PWA 支持** — 可安装为独立应用并支持离线缓存 ## 访问 Web 应用的方式 提供两种选项，均使用相同的 Web Serial 协议： 1. **托管方式**：访问 [GitHub Pages 站点](https://bod09.github.io/RP2350-Storage-Bridge) — 首次加载后支持 PWA 离线缓存。 2. **隔离网络 / 受限环境**：从 [Actions](../../actions) 工件下载 `storage-bridge.html` 并在 Chrome 中本地打开。通过 `file://` 运行，无需联网。 ## 硬件 - **开发板**：[Waveshare RP2350-USB-A](https://www.waveshare.com/rp2350-usb-a.htm) - **芯片**：RP2350（双核 Cortex-M33），520KB SRAM，2MB 闪存 - **原生 USB（端口 0）**：设备模式连接至电脑 —— 复合 HID 键盘 + CDC 串口 - **PIO USB（端口 1，GPIO 12/13）**：主机模式 —— 支持 USB 大容量存储设备 **注意：** 为可靠的 USB 主机操作，请对 D+ 引脚上的 R13（1.5k 上拉电阻）进行脱焊。 ## 架构 ``` [USB Flash Drive] --USB-A--> [RP2350-USB-A] --USB--> [PC] PIO USB Host Native USB Device FatFS filesystem CDC Serial + HID Keyboard | [Web Browser] Web Serial API File Browser UI Content Preview Security Scanning ``` RP2350 在不受信任的 USB 驱动器与电脑之间充当硬件防火墙。你的电脑仅通过标准串口协议与 RP2350 通信，永远无法直接访问驱动器的 USB 接口。 ## 构建固件 ``` # 首次：初始化子模块 git submodule update --init --recursive cd firmware mkdir build && cd build cmake .. make -j$(nproc) # 将 storage_bridge.uf2 闪存到设备 ``` 预编译的 UF2 文件也可从 [GitHub Actions](../../actions) 工件中获取。 **依赖项：** ARM GCC 工具链、CMake 3.13+ ## Web 应用 ### 开发（多文件，ES 模块） ``` cd web python3 -m http.server 8080 # 在 Chrome/Edge 中打开 http://localhost:8080 ``` ### 打包为单文件（用于发布 / 离线使用） ``` # 需要 esbuild：npm i -g esbuild python3 tools/bundle.py # 输出：web/dist/storage-bridge.html（约 37 KB） ``` **浏览器要求：** Chrome 或 Edge（支持 Web Serial API） ## CI/CD GitHub Actions 运行两个独立的工作流： - **构建固件**（`firmware/**` 变更）：编译固件并上传 `.uf2` 和打包后的 Web 应用作为工件 - **部署 Web 应用**（`web/**` 变更）：将 Web 应用部署到 GitHub Pages ## 串口协议 基于换行符分隔的 JSON，通过 CDC 串口传输。命令如下： | 命令 | 描述 | |------|------| | `{"cmd":"ls","path":"/"}` | 列出目录 | | `{"cmd":"read","path":"/file.txt","offset":0,"length":8192}` | 读取文件块（Base64 编码） | | `{"cmd":"write","path":"/file.txt","offset":0,"data":"...","done":true}` | 写入文件块（Base64 编码） | | `{"cmd":"mkdir","path":"/dir"}` | 创建目录 | | `{"cmd":"delete","path":"/file.txt"}` | 删除文件/目录 | | `{"cmd":"rename","from":"/old","to":"/new"}` | 重命名/移动 | | `{"cmd":"dirsize","path":"/dir"}` | 递归目录大小 | | `{"cmd":"hash","path":"/file.txt"}` | SHA-256 文件哈希 | | `{"cmd":"rmdir","path":"/dir"}` | 递归删除目录 | | `{"cmd":"format"}` | 格式化驱动器 | | `{"cmd":"df"}` | 磁盘可用空间 | | `{"cmd":"eject"}` | 安全卸载 | | `{"cmd":"status"}` | 驱动器状态 | | `{"cmd":"bootloader"}` | 重启至 UF2 Bootloader |

标签：EXIF元数据, FatFS, meg, RP2350, USB安全, 串行通信, 信息安全, 内容检查, 反病毒扫描, 存储设备隔离, 安全浏览, 数字取证, 文件哈希, 文件系统解析, 文件预览, 气隙环境, 熵分析, 硬件防火墙, 自动化脚本, 自定义脚本