christophe.duvernois/usb-spyПерехватывает и анализирует трафик USB Mass Storage на уровне блоков и файлов, эмулирует USB-устройства и поддерживает пользовательские заглушки Python для исследований в области безопасности, криминалистики и тестирования уязвимостей TOCTOU.
usb-spy — это анализатор трафика USB Mass Storage, построенный на микроконтроллере с поддержкой WiFi или Ethernet.
Плата представляет образ диска (FAT или любую файловую систему) как поддельное USB Mass Storage устройство для целевой системы, при этом фактические данные хранилища предоставляются удалённым сервером через WiFi или Ethernet. Такая конфигурация позволяет usb-spy перехватывать и анализировать каждый доступ к блоку, выполняемый целевой системой.
Помимо трассировки на уровне сырых блоков, usb-spy понимает файловые системы и может сопоставлять каждый доступный блок с соответствующим файлом и каталогом, что позволяет сразу видеть, какой файл читается или записывается, вместо простых номеров секторов.
Кроме того, usb-spy может эмулировать любое USB-устройство, настраивая такие свойства устройства, как идентификатор производителя, идентификатор продукта, серийный номер, производитель и название продукта, через JSON-файл конфигурации. Это позволяет выдавать себя за конкретные USB-устройства для целей тестирования и анализа.
Инструмент легко расширяется с помощью пользовательских Python-заглушек, что позволяет реализовать собственную логику обработки событий чтения/записи USB и операций на уровне блоков.
При обнаружении поддерживаемой файловой системы usb-spy:
Поддерживаемые в настоящее время файловые системы:
Поддержка дополнительных файловых систем будет добавлена в будущем.
Если файловая система не поддерживается, usb-spy всё равно можно использовать:
Это гарантирует, что usb-spy остаётся полезным даже с неизвестными, пользовательскими или проприетарными файловыми системами.
Инструкции по сборке прошивки для каждой поддерживаемой платы описаны здесь:
Исходный код находится в каталоге src. Он загружает FAT-образ, предоставляет его через TCP-порт и регистрирует каждый доступ к образу. Для вывода информации о файлах и каталогах инструмент использует библиотеку TheSleuthKit.
Для сборки выполните следующую команду в корневом каталоге
Загрузите все подмодули
git submodule update --init --recursive
Затем выполните команду настройки waf.
./waf configure
Если вы хотите собрать без поддержки встраивания Python, настройте с помощью:
./waf configure --disable-python
Будут проверены и собраны все необходимые зависимости, затем для фактической сборки проекта выполните
./waf build
Бинарный файл будет находиться в каталоге wbuild
При сборке с --disable-python параметры времени выполнения --py и --py-args недоступны.
Это легко сделать с помощью пакета утилит mtools
Создайте файл размером 2 МБ
dd if=/dev/zero of=disk.img bs=1M count=2
Поместите на него файловую систему FAT (используйте -F для FAT32, в противном случае это автоматически)
mformat -i disk.img ::
Добавьте в него файл
mcopy -i disk.img example.txt ::
Список файлов
mdir -i disk.img ::
Извлеките файл
mcopy -i disk.img ::/example.txt extracted.txt
Запустите spy с только что созданным образом
./usb-spy -v disk.img
Для принудительного использования сырого режима и пропуска автоматического определения файловой системы:
./usb-spy --raw disk.img
Для проксирования доступа непосредственно к реальному блочному устройству:
./usb-spy --proxy /dev/sda
Подключите плату к целевому USB-порту.
Для эмуляции конкретного USB-устройства параметры можно переопределить через JSON-файл конфигурации:
Следующий JSON-файл эмулирует USB-устройство Kingston DataTraveler:
{
"vendor_id": 2385,
"product_id": 5734,
"bcd_device": 272,
"product_rev": "3.0",
"manufacturer": "Kingston",
"product_name": "DataTraveler",
"serial": "509C4BBFACCDE742880C026B",
"language": 1033
}
Запустите spy с этим файлом конфигурации
./usb-spy -c config/kingston.json disk.img
Вывод dmesg для этого устройства:
usb 1-8: New USB device found, idVendor=0951, idProduct=1666, bcdDevice= 1.10
usb 1-8: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 1-8: Product: DataTraveler
usb 1-8: Manufacturer: Kingston
usb 1-8: SerialNumber: 509C4BBFACCDE742880C026B
usb-storage 1-8:1.0: USB Mass Storage device detected
scsi host6: usb-storage 1-8:1.0
scsi 6:0:0:0: Direct-Access Kingston DataTraveler 3.0 PQ: 0 ANSI: 2
Если вы хотите реализовать собственную логику для каждого события чтения/записи, вы можете легко сделать это на Python.
Реализуйте класс USBImage на Python, как этот dummy образ:
class USBImage:
def __init__(self, *args, **kwargs):
"""
Initialize the USBImage.
:param args: should contain:
- filename: The name of the file to manage.
:param kwargs: Arbitrary arguments passed from the c++ command line including:
readOnly: Whether the interface is read-only.
verbose: Whether to enable verbose logging.
block: Whether to enable block mode.
"""
pass
def getBlockNumber(self):
"""Get block number"""
return 100
def getBlockSize(self):
"""Get block size"""
return 512
def read(self, lba, buffer, size):
"""Read block"""
print(f"read block={lba} size={size}")
for i in range(size):
buffer[i] = (lba + i) % 256 # Simulate reading data
return size
def write(self, lba, buffer, size):
"""Write block"""
print(f"write block={lba} size={size}")
print(buffer)
return size
def flush(self):
"""Flush block"""
print("flush data")
И запустите spy со своим Python-модулем.
./usb-spy --py python/dummy.py disk.img
Вы также можете передавать произвольные аргументы из командной строки в свой Python-класс. Аргументы доступны в kwargs.
./usb-spy --py python/dummy.py --py-args arg1=2 --py-args arg2=Hello disk.img
Вы также можете начать с примера rawimage, который предоставляет полную реализацию (~100 строк кода) того, что реализовано в бинарном файле usb-spy нативно.
Этот проект предоставляется «как есть». Нет никаких гарантий корректности, безопасности или пригодности для каких-либо конкретных целей.
Используйте инструменты и прошивку на свой страх и риск. Автор и участники не несут ответственности за любой ущерб, потерю данных или юридические последствия, которые могут возникнуть при использовании этого программного или аппаратного обеспечения.
Вклад приветствуется! Пожалуйста, выполните следующие шаги:
Этот проект лицензирован в соответствии с GNU General Public License v3.0. Подробности см. в файле LICENSE.