USBvalve v1.0.1 — Expose USB activity on the fly

[!NOTE] USBvalve Versão 1.0.0

Uma reescrita completa da aplicação foi feita:

abandonado o ambiente Arduino IDE, agora o código é escrito para o Pi Pico SDK

as dependências de bibliotecas externas foram bastante reduzidas

o suporte a USB host para dispositivos Low Speed é agora mais robusto (ATTiny85, EvilCrow, etc)

o hardware e as funcionalidades estão quase inalterados, veja as notas abaixo para detalhes

Exponha a atividade USB em tempo real

The two models The Watch 1.2

Tenho certeza que, como eu, você já foi solicitado a colocar seu pendrive USB em um dispositivo desconhecido...e então a dúvida:

o que aconteceu com meu pobre dongle, nos bastidores? Roubando meus arquivos? Criptografando-os? Ou apenas instalando um malware? Com o USBvalve você pode descobrir isso em segundos: construído com hardware super barato de prateleira, você pode testar rapidamente qualquer atividade de sistema de arquivos USB e entender o que está acontecendo antes que seja tarde demais!

Com o USBvalve você pode ter um feedback imediato sobre o que acontece com o drive; a tela mostrará se o sistema de arquivos falso construído no dispositivo é acessado, lido ou escrito:

Selftest Readme

e a partir da versão 0.8.0 você também pode usá-lo como USB Host para detectar dispositivos BADUSB:

HID

Este é um exemplo do depurador BADUSB disponível na porta serial:

Se você prefere vídeos, também pode dar uma olhada na minha Apresentação no Insomni'hack

USBvalve Watch

A partir da versão 0.15.0 uma nova versão Pi Pico Watch é suportada. Para compilar a nova versão você deve descomentar a linha #define PIWATCH no início do código. O hardware é uma placa de relógio com display TFT de 1,28 polegadas baseada em RP2040. Você pode encontrar mais informações aqui. Isto também é totalmente compatível com o Waveshare RP2040-LCD-1.28.

Estrutura do Repositório

docs: documentação sobre o projeto, com uma apresentação onde você pode ver todas as funcionalidades

firmware: firmwares pré-compilados para o Raspberry Pi Pico. Você pode simplesmente usá-los e gravá-los na placa. Temos várias versões diferentes, para OLEDs de 32 ou 64 linhas, para Pico 1 ou Pico2, Pi Pico Watch, etc

PCB: arquivo Gerber se você quiser imprimir a PCB personalizada. Não é obrigatório, você pode usar a sua própria ou montar em uma protoboard

src e data: códigos-fonte, se você quiser modificar e compilar o firmware por conta própria

utils: alguns utilitários que você pode usar para construir um FS personalizado

pictures: imagens e recursos usados neste documento

STL: arquivos STL para a carcaça. Nas pastas 1.1 e 1.2 há carcaças completas (graças a WhistleMaster). Nas pastas 1.2_64 e 1.2_64_simple há carcaças para a tela 128x64 (graças a rtmq0227). Se você quiser algo mais leve para proteger o LCD, você pode usar o USBvalve_sliding_cover.stl.

Construir o USBvalve

Lista de peças

Se você quiser construir o seu próprio, você precisa de:

Um Raspberry Pi Pico 1 ou 2 (ou outra placa baseada em RP2040)
uma tela OLED I2C 128x64 ou 128x32 (SSD1306)
(opcional) uma PCB do USBvalve ou uma protoboard
(opcional) um espaçador impresso em 3D para isolar a tela da placa (https://www.thingiverse.com/thing:4748043), mas você pode usar um pedaço de fita isolante no lugar

Notas sobre BOOTSEL e versão >= 1.0.0

Nas versões 0.x.x, o BOOTSEL era usado para reiniciar o dispositivo ou imprimir o número de eventos HID (pressione > 2s). A leitura do BOOTSEL estava criando alguns problemas para a detecção de BADUSB, então isso foi removido a partir da versão 1.0.0 e substituído pelas duas opções a seguir:

solde um botão entre GP0 e GND (pads 1 e 3, veja a imagem abaixo para um exemplo) para ter as mesmas funções
use os comandos r (reset) e h (eventos HID) do monitor serial

Em PCB você também encontrará uma versão 1.3 da placa, com alguns furos nos pads 1 e 3 para facilitar a montagem do botão. Mas como você pode ver, você também pode usar sua versão antiga.

Se você não está usando as funções BADUSB ou se prefere ter menos cobertura na detecção mas manter o uso do BOOTSEL, também estou fornecendo um firmware criado com o bootsel habilitado (veja a pasta e as releases).

Instruções de construção

Graças a Tz1rf também temos dois ótimos vídeos: um explicando o processo de construção passo a passo, e outro mostrando como enviar o firmware e usar a ferramenta.

Quase todo o trabalho é feito diretamente na placa pelo software, então você só precisa organizar a conexão com o OLED para a saída.

A partir da versão 0.8.0 do firmware, o USBvalve pode detectar dispositivos HID (usado para detectar BADUSB). Isso requer uma porta USB adicional atuando como Host. Se você não está interessado nisso, você pode usar as instruções antigas na pasta docs e usar a versão 1.1 da PCB. Caso contrário, prossiga com a versão 1.2 da PCB (temos versão para USB-A ou USB-B, veja a pasta).

Com a PCB do USBvalve

solde uma porta USB fêmea na área USBH. Esta é para a versão A, mas há uma versão para USB Micro-B também se você preferir
coloque o Raspberry Pi Pico sobre a serigrafia na frente
você não precisa soldar todos os PINs. Apenas os seguintes:
- D4 e D5 (lado esquerdo)
- D14 e D15 (lado esquerdo)
- GND (lado direito, terceiro pino de cima)
- GND (lado direito, terceiro pino de baixo)
- 3v3_OUT (lado direito)
- VBUS (lado direito)
- os 3 pinos DEBUG na parte inferior: SWCLK, GND e SWDIO
coloque o espaçador impresso em 3D ou um pedaço de fita nas partes do OLED que possam tocar o Raspberry
solde o OLED (com um header) no espaço de 4 PINs

Alguns dos OLEDs têm os PINs GND e VCC trocados, então eu construí a PCB para ser compatível com ambas as versões:

Por exemplo, se o seu OLED tem GND no PIN1 e VCC no PIN2 assim:

Você deve colocar uma gota de solda nestes dois pads na parte de trás da PCB:

Caso contrário, você deve fazer o oposto e colocar a solda nos outros PADs:

Sem a PCB do USBvalve

Se você está usando uma protoboard ou apenas fiação, tudo o que você precisa fazer é garantir a conexão dos PINs corretos na tela OLED e na porta USB Host.

O mapeamento é o seguinte:

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

Se você quiser usar as funções DEBUG, você também pode colocar um header nos 3 PINs SWD na parte inferior da placa.

Com a PCB do USBpipe

[!CAUTION] Esta PCB é para makers de eletrônica experientes NÃO A USE SE VOCÊ NÃO TIVER CERTEZA DE QUE CONSEGUE LIDAR COM ELA!

[!NOTE] R7 e R8 não estão realmente conectados a nada. Eles são adicionados para fins de depuração do circuito. Portanto, eles não aparecem na BOM

USBpipe é uma PCB dedicada para este projeto.

Você pode encontrar tudo o que precisa na pasta ./PCB/USBpipe/.

Gravar o Firmware

Para gravar o firmware, siga estes passos:

Conecte o Raspberry Pi Pico com o cabo USB, mantendo o botão BOOTSEL pressionado (o botão branco grande na placa)
solte o botão
você verá uma nova unidade no sistema, chamada RPI-RP2 (em ambientes Linux você pode ter que montá-la manualmente)
copie o arquivo de firmware adequado (com extensão uf2) na pasta, dependendo do OLED que você usou
aguarde alguns segundos até que a pasta montada desapareça

Pronto!

Anti-Detecção

Não sei se algum dia será o caso, mas você pode querer personalizar o firmware para evitar a detecção feita por malware ciente do USBvalve :-)

Agrupei a maioria das variáveis que você pode querer modificar nesta seção do usb_config.h (veja o Dockerfile abaixo para recompilar)

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

Compilando seu firmware

Obviamente você também pode compilar seu próprio firmware. Para compilar você precisa do Raspberry Pi Pico SDK e deste repositório.

Instruções básicas de recompilação:

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 você quiser recriar um novo sistema de arquivos falso, você pode querer dar uma olhada na pasta utils, onde coloquei alguns utilitários para construir um novo.

Dockerfile

Se você quiser compilar seu próprio firmware, depois de personalizá-lo, eu forneço um Dockerfile que constrói um ambiente de compilação completo e compila o firmware.

Digite os seguintes comandos na pasta principal USBvalve para compilar:

# 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

O firmware será colocado com extensão uf2 na pasta USBvalve_out.

Contribuir

Se você tem ideias ou melhorias em mente, eu encorajo você a abrir uma issue para que possamos melhorar o projeto juntos! Obrigado!

Suporte

Se você tem dúvidas ou precisa de suporte, você pode abrir uma Issue aqui ou me contatar no Twitter/X @red5heep

Versões da comunidade

A comunidade criou alguns forks implementando suporte para outras placas, ou outras modificações. Obrigado a todos que contribuíram para o desenvolvimento do USBvalve. Abaixo uma lista não oficial/incompleta/não suportada:

USBvalve-tbfa-Mod

AVISO DE SEGURANÇA

[!WARNING] Recebi muitas perguntas sobre o USBvalve e dispositivos USB killer. O USBvalve não foi construído para testar esses dispositivos, ele não possui nenhum tipo de isolamento ou proteção, então se você suspeita que está lidando com um desses dispositivos, teste-o com outra coisa, NÃO com o USBvalve ou você pode danificar o dispositivo, a si mesmo ou objetos próximos a você.

Ler mais