cecio/usbvalveEspone l'attività USB al volo
<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 Versione 1.0.0** > > È stata fatta una riscrittura completa dell'applicazione: > - abbandonato l'ambiente Arduino IDE, ora il codice è scritto per il [Pi Pico SDK](https://github.com/raspberrypi/pico-sdk) > - le dipendenze da librerie esterne sono state ridotte molto > - il supporto USB host per dispositivi Low Speed è ora più robusto (ATTiny85, EvilCrow, ecc.) > - hardware e funzionalità sono quasi invariati, vedi le [note](https://github.com/cecio/USBvalve#notes-about-bootsel-and-version--100) sotto per i dettagli ### *Esponi l'attività USB al volo* <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> Sono sicuro che, come me, ti è stato chiesto di inserire la tua chiavetta USB in un dispositivo *sconosciuto*...e poi il dubbio: cosa è successo alla mia povera chiavetta, dietro le quinte? Sta rubando i miei file? Li sta cifrando? O *semplicemente* installando un malware? Con **USBvalve** puoi scoprirlo in pochi secondi: costruito su hardware super economico disponibile in commercio, puoi testare rapidamente qualsiasi attività del file system USB e capire cosa sta succedendo prima che sia troppo tardi! Con **USBvalve** puoi avere un feedback immediato su cosa succede alla chiavetta; lo schermo ti mostrerà se il *finto* file system costruito sul dispositivo viene acceduto, letto o scritto: <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> e dalla versione `0.8.0` puoi anche usarlo come USB Host per rilevare dispositivi *BADUSB*: <p float="left"> <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/hid.png" alt="HID" width="15%" height="15%" /> </p> Questo è un esempio del debugger *BADUSB* disponibile sulla porta seriale: <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> Se preferisci i video, puoi anche dare un'occhiata alla mia [Presentazione a Insomni'hack](https://www.youtube.com/watch?v=jy1filtQY4w) ## USBvalve Watch A partire dalla versione `0.15.0` è supportata una nuova versione *Pi Pico Watch*. Per compilare la nuova versione devi decommentare la riga `#define PIWATCH` all'inizio del codice. L'hardware è una scheda orologio con display TFT da 1,28 pollici basata su RP2040. Puoi trovare maggiori informazioni [qui](https://www.raspberrypi.com/news/how-to-build-your-own-raspberry-pi-watch/). Questo è anche completamente compatibile con il [Waveshare RP2040-LCD-1.28](https://www.waveshare.com/wiki/RP2040-LCD-1.28). ## Struttura del Repository `docs`: documentazione sul progetto, con una presentazione dove puoi dare un'occhiata a tutte le funzionalità `firmware`: firmware precompilati per il Raspberry Pi Pico. Puoi semplicemente usarli e flasharli sulla scheda. Abbiamo diverse versioni differenti, per OLED da 32 o 64 righe, per Pico 1 o Pico2, Pi Pico Watch, ecc. `PCB`: file Gerber se vuoi stampare il PCB personalizzato. Non è obbligatorio, puoi usare il tuo o costruirlo su una breadboard `src` e `data`: sorgenti, se vuoi modificare e compilare il firmware da solo `utils`: alcune utilità che potresti usare per costruire un FS personalizzato `pictures`: immagini e risorse usate in questo documento `STL`: file STL per l'involucro. Nelle cartelle `1.1` e `1.2` ci sono involucri completi (grazie a [WhistleMaster](https://github.com/WhistleMaster)). Nelle cartelle `1.2_64` e `1.2_64_simple` ci sono involucri per lo schermo 128x64 (grazie a [rtmq0227](https://github.com/rtmq0227)). Se vuoi qualcosa di più leggero per proteggere l'LCD puoi usare `USBvalve_sliding_cover.stl`. ## Costruire USBvalve ### Lista dei componenti Se vuoi costruire il tuo, hai bisogno di: - Un Raspberry Pi Pico 1 o 2 (o un'altra scheda basata su RP2040) - uno schermo OLED I2C 128x64 o 128x32 (**SSD1306**) - (opzionale) un PCB **USBvalve** o una breadboard - (opzionale) uno spaziatore stampato in 3D per isolare lo schermo dalla scheda (https://www.thingiverse.com/thing:4748043), ma puoi usare un pezzo di nastro isolante invece ### Note su BOOTSEL e versione >= 1.0.0 Nelle versioni `0.x.x`, BOOTSEL era usato per resettare il dispositivo o stampare il numero di eventi HID (premere > 2s). Il polling di BOOTSEL creava alcuni problemi al rilevamento *BADUSB* quindi è stato rimosso dalla versione `1.0.0` e sostituito con le seguenti due opzioni: - saldare un pulsante tra `GP0` e `GND` (pad 1 e 3, vedi foto sotto per un esempio) per avere le stesse funzioni - usare i comandi `r` (reset) e `h` (eventi HID) dal monitor seriale <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/reset_button.jpg" width="35%" height="35%" /> In `PCB` troverai anche una versione `1.3` della scheda, con alcuni fori sui pad 1 e 3 per facilitare il montaggio del pulsante. Ma come puoi vedere, puoi anche usare la tua vecchia versione. Se non stai usando le funzioni *BADUSB* o se preferisci avere meno copertura sul rilevamento ma mantenere l'uso di BOOTSEL, fornisco anche un firmware creato con *bootsel* abilitato (vedi cartella e release). ### Istruzioni di costruzione > Grazie a [Tz1rf](https://github.com/Tz1rf) abbiamo anche due ottimi video: uno che spiega il processo di [costruzione](https://youtu.be/7ymk8hD7-Hc) passo dopo passo, e un altro che mostra come [caricare il firmware](https://youtu.be/Tp8xvrlqxUY) e usare lo strumento. Quasi tutto il lavoro è fatto direttamente sulla scheda dal software, quindi devi solo predisporre la connessione con l'OLED per l'output. A partire dalla versione 0.8.0 del firmware, **USBvalve** può rilevare dispositivi HID (usato per rilevare *BADUSB*). Questo richiede una porta USB aggiuntiva che funga da Host. Se non sei interessato a questo, puoi usare le vecchie istruzioni [nella cartella docs](https://github.com/cecio/USBvalve/blob/main/docs/BUILDING-1.1.md) e usare la versione PCB `1.1`. Altrimenti procedi con la versione PCB `1.2` (abbiamo versioni per USB-A o USB-B, vedi cartella). #### Con PCB USBvalve <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> - salda una porta USB femmina nell'area `USBH`. Questa è per la versione `A`, ma c'è anche una versione per USB `Micro-B` se preferisci - posiziona il Raspberry Pi Pico sulla serigrafia sul fronte - non hai bisogno di saldare tutti i PIN. Solo i seguenti: - D4 e D5 (lato sinistro) - D14 e D15 (lato sinistro) - GND (lato destro, terzo pin dall'alto) - GND (lato destro, terzo pin dal basso) - 3v3_OUT (lato destro) - VBUS (lato destro) - i 3 pin DEBUG sul fondo: SWCLK, GND e SWDIO - posiziona lo spaziatore stampato in 3D o un pezzo di nastro sulle parti dell'OLED che potrebbero toccare il Raspberry - salda l'OLED (con un header) sullo spazio a 4 PIN Alcuni degli OLED hanno i PIN GND e VCC scambiati, quindi ho costruito il PCB per essere compatibile con entrambe le versioni: Per esempio se il tuo OLED ha GND sul PIN1 e VCC sul PIN2 come questo: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_oled.png" width="35%" height="35%" /> Devi mettere una goccia di stagno su questi due pad sul retro del PCB: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_pads.png" width="15%" height="15%" /> Altrimenti dovresti fare l'opposto e mettere lo stagno sugli altri PAD: <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/usb_valve_pads_2.png" width="15%" height="15%" /> #### Senza PCB USBvalve <img src="https://raw.githubusercontent.com/cecio/USBvalve/main/pictures/pico-pinout.svg" alt="Pico Pi" width="85%" height="85%" /> Se stai usando una breadboard o solo dei fili, tutto quello che devi fare è assicurarti di collegare i PIN corretti allo schermo OLED e alla porta USB Host. La mappatura è la seguente: - PIN6 del Pi --> OLED SDA - PIN7 del Pi --> OLED SCL - PIN19 del Pi --> D+ dell'USB Host - PIN20 del Pi --> D- dell'USB Host - PIN23 (GND) del Pi --> GND dell'USB Host - PIN38 (GND) del Pi --> OLED GND - PIN36 (3V3OUT) del Pi --> OLED VCC - PIN40 (VBUS) del Pi --> VCC dell'USB Host Se vuoi usare le funzioni DEBUG, puoi anche posizionare un header sui 3 PIN SWD sul fondo della scheda. #### Con PCB USBpipe > [!CAUTION] > Questo PCB è per maker elettronici esperti > **NON USARLO SE NON SEI SICURO DI SAPERLO GESTIRE!** > [!NOTE] > R7 e R8 non sono effettivamente collegati a nulla. Sono aggiunti per scopi di debug del circuito. > Quindi non compaiono nella 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) è un PCB dedicato per questo progetto. Puoi trovare tutto ciò che ti serve nella cartella `./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%"/> ### Flash del Firmware Per flashare il firmware, segui questi passaggi: - Collega il Raspberry Pi Pico con il cavo USB, tenendo premuto il pulsante *BOOTSEL* (il grande pulsante bianco sulla scheda) - rilascia il pulsante - vedrai una nuova unità sul sistema, chiamata `RPI-RP2` (in ambienti Linux potresti doverla montare manualmente) - copia il file firmware appropriato (con estensione `uf2`) nella cartella, a seconda dell'OLED che hai usato - attendi qualche secondo finché la cartella montata non scompare Fatto! ### Anti-Rilevamento Non so se sarà mai il caso, ma potresti voler personalizzare il firmware per evitare il rilevamento fatto da malware *consapevoli di USBvalve* :-) Ho raggruppato la maggior parte delle variabili che potresti voler modificare in questa sezione di `usb_config.h` ([vedi il Dockerfile sotto per ricompilare](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 ``` ### Compilare il tuo firmware Ovviamente puoi anche compilare il tuo firmware. Per compilare hai bisogno del *Raspberry Pi Pico SDK* e di questo repository. Istruzioni di base per la ricompilazione: ``` 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 ``` Se vuoi ricreare un nuovo file system finto, potresti voler dare un'occhiata alla cartella `utils`, dove ho messo alcune utilità per costruirne uno nuovo. #### Dockerfile Se vuoi compilare il tuo firmware, dopo averlo personalizzato, fornisco un `Dockerfile` che costruisce un ambiente di compilazione completo e compila il firmware. Inserisci i seguenti comandi nella cartella principale `USBvalve` per compilare: ``` # 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 ``` Il firmware sarà posizionato con estensione `uf2` nella cartella `USBvalve_out`. ### Contribuire Se hai idee o miglioramenti in mente, ti incoraggio ad aprire una issue così possiamo migliorare il progetto insieme! Grazie! ### Supporto Se hai domande o hai bisogno di supporto puoi aprire una `Issue` qui o contattarmi su Twitter/X [@red5heep](https://twitter.com/red5heep) ### Versioni della community La Community ha creato alcuni fork che implementano il supporto per altre schede, o altre modifiche. **Grazie a tutti** coloro che hanno contribuito allo sviluppo di **USBvalve**. Qui sotto una lista non ufficiale/incompleta/non supportata: - [USBvalve-tbfa-Mod](https://github.com/TryBreakFixAgain/USBvalve-tbfa-Mod) ## AVVISO DI SICUREZZA > [!WARNING] > Ho ricevuto molte domande su **USBvalve** e sui *dispositivi USB killer*. **USBvalve** non è costruito per testare questi dispositivi, non ha alcun tipo di isolamento o protezione, quindi se hai il sospetto di avere a che fare con uno di questi dispositivi, testalo con qualcos'altro, NON con **USBvalve** o potresti danneggiare il dispositivo, te stesso o oggetti vicini a te.
