fuzzsociety/usbstackfuzz

This repository contains firmware projects for an ESP32-S3 microcontroller board that let security researchers test how host computers handle unusual or malformed USB devices. The basic idea is that you flash the firmware onto a cheap ESP32-S3 board, plug it into a test machine, and observe how the operating system's USB code responds to edge-case descriptors, strange device names, or unexpected packet patterns. There are two firmware projects. The first emulates a USB MIDI device, which is the class of device used for connecting electronic musical instruments to computers. It can produce unusual descriptor combinations, Unicode-heavy device names, long or short string fields, and boundary-value MIDI packet sequences. This exercises the host's MIDI driver and enumeration path in ways that normal instruments would not. The second emulates a non-keyboard HID (Human Interface Device), specifically one designed around accessibility or assistive-control use cases like Braille displays. It avoids generating keyboard keystrokes by default, which limits the risk of accidental input injection during testing. The ESP32-S3 chip was chosen because it includes a native USB hardware peripheral, making it straightforward and inexpensive to produce arbitrary USB device behavior without extra hardware. On dual-port boards, one port connects to the machine under test while the other provides a serial debug link back to the researcher's development computer, so logs can be captured even if the target machine's USB handling locks up. The README recommends using dedicated test machines or virtual machines with USB passthrough rather than production hardware. It also suggests keeping detailed records of the firmware version, host OS, and USB logs when a crash or unexpected behavior is found, so results can be reproduced with the same inputs. The repository is structured as two separate firmware directories, one for MIDI and one for HID, each with its own build configuration and documentation subfolder. Building requires Espressif's ESP-IDF toolchain and a data-capable USB cable.