USBvalve v1.0.1 — Expose USB activity on the fly

[!NOTE] USBvalve Version 1.0.0

Une réécriture complète de l'application a été effectuée :

abandon de l'environnement Arduino IDE, le code est désormais écrit pour le Pi Pico SDK

les dépendances à des bibliothèques externes ont été fortement réduites

la prise en charge des périphériques USB Host Low Speed est désormais plus robuste (ATTiny85, EvilCrow, etc)

le matériel et les fonctionnalités sont presque inchangés, voir les notes ci-dessous pour plus de détails

Exposez l'activité USB à la volée

Les deux modèles La Watch 1.2

Je suis sûr que, comme moi, on vous a demandé de brancher votre clé USB sur un appareil inconnu... et puis le doute :

qu'est-il arrivé à ma pauvre clé, en coulisses ? Elle vole mes fichiers ? Elle les chiffre ? Ou elle installe simplement un malware ? Avec USBvalve, vous pouvez le découvrir en quelques secondes : construit sur du matériel du commerce très bon marché, vous pouvez rapidement tester toute activité du système de fichiers USB et comprendre ce qui se passe avant qu'il ne soit trop tard !

Avec USBvalve, vous obtenez un retour immédiat sur ce qui arrive à la clé ; l'écran vous montre si le faux système de fichiers construit sur l'appareil est accédé, lu ou écrit :

Selftest Readme

et depuis la version 0.8.0, vous pouvez aussi l'utiliser comme USB Host pour détecter les périphériques BADUSB :

HID

Voici un exemple du débogueur BADUSB disponible sur le port série :

Si vous préférez les vidéos, vous pouvez aussi jeter un œil à ma Présentation à Insomni'hack

USBvalve Watch

À partir de la version 0.15.0, une nouvelle version Pi Pico Watch est prise en charge. Pour compiler la nouvelle version, vous devez décommenter la ligne #define PIWATCH au début du code. Le matériel est une carte montre avec écran TFT de 1,28 pouce basée sur RP2040. Vous trouverez plus d'informations ici. Elle est également entièrement compatible avec la Waveshare RP2040-LCD-1.28.

Structure du dépôt

docs : documentation sur le projet, avec une présentation où vous pouvez découvrir toutes les fonctionnalités

firmware : firmwares précompilés pour le Raspberry Pi Pico. Vous pouvez simplement les utiliser et les flasher sur la carte. Nous avons plusieurs versions différentes, pour écrans OLED 32 ou 64 lignes, pour Pico 1 ou Pico2, Pi Pico Watch, etc

PCB : fichier Gerber si vous souhaitez imprimer le PCB personnalisé. Ce n'est pas obligatoire, vous pouvez utiliser le vôtre ou le monter sur une breadboard

src et data : sources, si vous souhaitez modifier et compiler le firmware vous-même

utils : quelques utilitaires que vous pouvez utiliser pour construire un FS personnalisé

pictures : images et ressources utilisées dans cette documentation

STL : fichiers STL pour le boîtier. Dans les dossiers 1.1 et 1.2 se trouvent des boîtiers complets (merci à WhistleMaster). Dans les dossiers 1.2_64 et 1.2_64_simple se trouvent des boîtiers pour l'écran 128x64 (merci à rtmq0227). Si vous voulez quelque chose de plus léger pour protéger l'écran LCD, vous pouvez opter pour USBvalve_sliding_cover.stl.

Construire USBvalve

Liste des pièces

Si vous souhaitez construire le vôtre, vous avez besoin de :

Un Raspberry Pi Pico 1 ou 2 (ou une autre carte basée sur RP2040)
un écran OLED I2C 128x64 ou 128x32 (SSD1306)
(optionnel) un PCB USBvalve ou une breadboard
(optionnel) une entretoise imprimée en 3D pour isoler l'écran de la carte (https://www.thingiverse.com/thing:4748043), mais vous pouvez utiliser un morceau de ruban isolant à la place

Notes sur BOOTSEL et la version >= 1.0.0

Dans les versions 0.x.x, BOOTSEL était utilisé pour réinitialiser l'appareil ou afficher le nombre d'événements HID (appui > 2s). Le polling de BOOTSEL créait quelques problèmes pour la détection BADUSB, il a donc été supprimé à partir de la version 1.0.0 et remplacé par les deux options suivantes :

souder un bouton entre GP0 et GND (pads 1 et 3, voir la photo ci-dessous pour un exemple) pour avoir les mêmes fonctions
utiliser les commandes r (reset) et h (événements HID) depuis le moniteur série

Dans PCB, vous trouverez également une version 1.3 de la carte, avec des trous sur les pads 1 et 3 pour faciliter le montage du bouton. Mais comme vous pouvez le voir, vous pouvez aussi utiliser votre ancienne version.

Si vous n'utilisez pas les fonctions BADUSB ou si vous préférez avoir une couverture de détection moindre mais conserver l'usage de BOOTSEL, je fournis également un firmware compilé avec bootsel activé (voir le dossier et les releases).

Instructions de construction

Merci à Tz1rf pour deux excellentes vidéos : une expliquant le processus de construction étape par étape, et une autre montrant comment téléverser le firmware et utiliser l'outil.

Presque tout le travail est effectué directement sur la carte par le logiciel, vous avez donc juste besoin d'organiser la connexion avec l'OLED pour la sortie.

À partir de la version 0.8.0 du firmware, USBvalve peut détecter les périphériques HID (utilisé pour détecter les BADUSB). Cela nécessite un port USB supplémentaire agissant comme Host. Si cela ne vous intéresse pas, vous pouvez utiliser les anciennes instructions dans le dossier docs et utiliser la version 1.1 du PCB. Sinon, continuez avec la version 1.2 du PCB (nous avons une version pour USB-A ou USB-B, voir le dossier).

Avec le PCB USBvalve

souder un port USB femelle dans la zone USBH. C'est pour la version A, mais il existe aussi une version pour USB Micro-B si vous préférez
placer le Raspberry Pi Pico sur la sérigraphie à l'avant
vous n'avez pas besoin de souder toutes les broches. Seulement les suivantes :
- D4 et D5 (côté gauche)
- D14 et D15 (côté gauche)
- GND (côté droit, troisième broche depuis le haut)
- GND (côté droit, troisième broche depuis le bas)
- 3v3_OUT (côté droit)
- VBUS (côté droit)
- les 3 broches DEBUG en bas : SWCLK, GND et SWDIO
placer l'entretoise imprimée en 3D ou un morceau de ruban sur les parties de l'OLED qui pourraient toucher le Raspberry
souder l'OLED (avec un header) sur l'espace de 4 broches

Certains OLED ont les broches GND et VCC inversées, j'ai donc conçu le PCB pour être compatible avec les deux versions :

Par exemple, si votre OLED a GND sur la broche 1 et VCC sur la broche 2 comme ceci :

Vous devez déposer une goutte de soudure sur ces deux pads à l'arrière du PCB :

Sinon, vous devez faire l'inverse et déposer la soudure sur les autres pads :

Sans le PCB USBvalve

Si vous utilisez une breadboard ou un simple câblage, tout ce que vous avez à faire est de vous assurer de connecter les bonnes broches à l'écran OLED et au port USB Host.

Le mapping est le suivant :

PIN6 du Pi --> OLED SDA
PIN7 du Pi --> OLED SCL
PIN19 du Pi --> D+ de l'USB Host
PIN20 du Pi --> D- de l'USB Host
PIN23 (GND) du Pi --> GND de l'USB Host
PIN38 (GND) du Pi --> OLED GND
PIN36 (3V3OUT) du Pi --> OLED VCC
PIN40 (VBUS) du Pi --> VCC de l'USB Host

Si vous souhaitez utiliser les fonctions DEBUG, vous pouvez également placer un header sur les 3 broches SWD en bas de la carte.

Avec le PCB USBpipe

[!CAUTION] Ce PCB est destiné aux makers électroniques expérimentés NE L'UTILISEZ PAS SI VOUS N'ÊTES PAS SÛR DE POUVOIR LE GÉRER !

[!NOTE] R7 et R8 ne sont en réalité connectées à rien. Elles sont ajoutées à des fins de débogage du circuit. Elles n'apparaissent donc pas dans la BOM

USBpipe est un PCB dédié à ce projet.

Vous trouverez tout ce dont vous avez besoin dans le dossier ./PCB/USBpipe/.

Flasher le firmware

Pour flasher le firmware, suivez ces étapes :

Connectez le Raspberry Pi Pico avec le câble USB, en maintenant le bouton BOOTSEL enfoncé (le gros bouton blanc sur la carte)
relâchez le bouton
vous verrez un nouveau lecteur sur le système, nommé RPI-RP2 (dans les environnements Linux, vous devrez peut-être le monter manuellement)
copiez le fichier firmware approprié (avec l'extension uf2) dans le dossier, selon l'OLED que vous avez utilisé
attendez quelques secondes jusqu'à ce que le dossier monté disparaisse

C'est fait !

Anti-Détection

Je ne sais pas si ce sera un jour le cas, mais vous pourriez vouloir personnaliser le firmware afin d'éviter la détection par des malwares USBvalve-aware :-)

J'ai regroupé la plupart des variables que vous pourriez vouloir modifier dans cette section de usb_config.h (voir le Dockerfile ci-dessous pour recompiler)

// 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

Compiler votre firmware

Évidemment, vous pouvez aussi compiler votre propre firmware. Pour compiler, vous avez besoin du Raspberry Pi Pico SDK et de ce dépôt.

Instructions de recompilation de base :

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

Si vous souhaitez recréer un nouveau faux système de fichiers, vous voudrez peut-être jeter un œil au dossier utils, où j'ai placé quelques utilitaires pour en construire un nouveau.

Dockerfile

Si vous souhaitez compiler votre propre firmware, après l'avoir personnalisé, je fournis un Dockerfile qui construit un environnement de compilation complet et compile le firmware.

Entrez les commandes suivantes dans le dossier principal USBvalve pour compiler :

# 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

Le firmware sera placé avec l'extension uf2 dans le dossier USBvalve_out.

Contribuer

Si vous avez des idées ou des améliorations en tête, je vous encourage à ouvrir une issue afin que nous puissions améliorer le projet ensemble ! Merci !

Support

Si vous avez des questions ou besoin d'aide, vous pouvez ouvrir une Issue ici ou me contacter sur Twitter/X @red5heep

Versions communautaires

La communauté a créé quelques forks implémentant la prise en charge d'autres cartes, ou d'autres modifications. Merci à tous ceux qui ont contribué au développement d'USBvalve. Voici ci-dessous une liste non officielle/incomplète/non supportée :

USBvalve-tbfa-Mod

AVERTISSEMENT DE SÉCURITÉ

[!WARNING] J'ai reçu beaucoup de questions sur USBvalve et les USB killer devices. USBvalve n'est pas conçu pour tester ces appareils, il n'a aucun type d'isolation ou de protection, donc si vous suspectez d'avoir affaire à l'un de ces appareils, testez-le avec autre chose, PAS avec USBvalve, sinon vous risquez d'endommager l'appareil, vous-même ou des objets proches de vous.

Lire plus