spidump — captura e reconstrução de traces SPI/QSPI

spidump analisa capturas de analisador lógico de um dispositivo a ler a sua flash NOR SPI/QSPI no arranque e reconstrói a imagem da flash a partir do tráfego de leitura — sem necessidade de leitura direta do chip. O conjunto de comandos da flash é modelado com Scapy, pelo que uma transação de leitura é o mesmo objeto lógico quer tenha chegado por um fio ou por quatro.

Formatos de captura suportados (detetados automaticamente pelo cabeçalho)

O plugin QSPI-Analyzer para Saleae Logic / KingstVIS descodifica o enquadramento em modo quad (p. ex. 0x6B Fast Read Quad Output, 1-1-4) que um analisador SPI simples não consegue.

Utilização

# Standard single-lane SPI capture (Logic 2 SPI analyzer export)
python main.py examples/bigger-boot.csv -o recovered_flash.bin -v

# Quad SPI capture (QSPI-Analyzer export) — same command, format auto-detected
python main.py big-quad-spi-analyzed-dump.txt -o quad.bin -v

# Merge a single-lane leg (U-Boot) with a quad leg (rootfs) into one image.
# Devices that boot single-lane then switch to QSPI leave each region in a
# different capture; --merge splices them. Reads whose data lane width doesn't
# match the opcode (e.g. quad reads a single-lane analyzer mis-decoded) are
# dropped automatically, so a mixed capture can't poison the result.
python main.py single_lane_boot.csv --merge quad_boot.txt -o full.bin -v

# Raw exports with no chip-select framing (Packet ID constant) are split on
# idle gaps automatically (4x median byte period); override the threshold with
# --gap SECONDS, or --gap 0 to force Packet ID grouping
python main.py raw_boot.csv --gap 2e-6 -o raw.bin -v

# Force a flash size / fill byte if the auto-sizing guesses wrong
python main.py capture.txt --flash-size 0x1000000 --fill 0xFF -o out.bin

-v imprime o formato detetado, um histograma de transações por opcode, o tamanho de flash escolhido e a cobertura de leitura. As regiões não lidas são preenchidas com 0xFF (o estado de NOR apagada), pelo que a saída é segura para alimentar diretamente o binwalk.

Como funciona

Uma leitura de flash é a mesma transação lógica independentemente da largura do fio: um opcode, um endereço e uma sequência de bytes de dados. Os dois traces abaixo leem os mesmos quatro bytes (a magic SquashFS hsqs em 0x2D0000, retirada de bigger-boot.csv) em modo single-lane e quad:

(Regenerar com python docs/diagrams/mkwave.py; requer wavedrom-cli, e rsvg-convert para os PNGs.)

1. Um parser de front-end transforma a captura em registos de leitura normalizados {cmd, addr, data, lines}.
2. SPIFlashCmd (Scapy) modela o cabeçalho de opcode / endereço / dummy; os opcodes de leitura (single e quad: 0x03 0x0B 0x6B 0xEB 0x6C 0x0C …) são todos apenas entradas em READ_COMMANDS.
3. reconstruct_image reproduz cada leitura num bytearray, registando a cobertura.

Um arranque só lê o que precisa, pelo que a cobertura é parcial por conceção — recupera as regiões que o dispositivo realmente tocou (bootloader, kernel, rootfs montado). Para um dispositivo que arranca em single-lane e depois muda para quad, capture ambas as fases e faça o splice.