search

x64x6a / PyBadUSB

Implementation of BadUSB written in Python
MIT License
33 stars 12 forks source link

readme

PyBadUSB

PyBadUSB was created to implement BadUSB ONLY on a Phison 2303 (2251-03) device using Python. The project is currently designed to inject USB Rubber Ducky scripts to a Phison 2303 device. The python module pybadusb was created to communicate with the specified USB device.

The project was inspired by adamcaudill/Psychson and flowswitch/phison.

Requirements

Installation

Run the setup script:

python setup.py install

Running

You can run the module as a script:

python -m pybadusb

Example using Windows:

python -m pybadusb --device H --firmware bin/fw.bin --burner bin/BN03V114M.BIN --payload rubberducky/inject.bin

Example using a Linux distro:

python -m pybadusb --device /dev/sg2 --firmware bin/fw.bin --burner bin/BN03V114M.BIN --payload rubberducky/inject.bin

Example Code

You can also use the module within a python script.

Here's some example code to get you started:

from pybadusb import badusb, phison

device_name = 'H'           # Windows
#device_name = '/dev/sg2'   # Linux

# Set firmware file names
payload  = 'rubberducky/inject.bin'
firmware = 'bin/fw.bin'
burner   = 'bin/BN03V114M.BIN'
embedded = 'hid.bin'

# Get device located at device_name
device = badusb.get_device(phison.Phison2303, device_name)

# Embed firmware
badusb.embed(payload, firmware, embedded)

# Flash new firmware using burner image
badusb.burn_firmware(device, burner, fwfile=firmware)

# Finished
device.close()

Another example can be found in example.py

Firmware

The base firmware you can use is in bin/fw.bin. You can compile your own here.

The burner image used is in bin/BN03V114M.BIN. Links for finding your own burner image:

Rubber Ducky

PyBadUSB is currently only designed to embed compiled USB Rubber Ducky scripts. The test script used can be found in rubberducky/keys.txt.

You may create your own according to the Rubber Ducky format or use one of these.

Use DuckEncoder to compile your script:

java -jar encoder.jar -i keys.txt -o inject.bin

The created binary can then be embedded into the base firmware. See example code below.

Phison Device

This project has only been developed to work with USB devices with the Phison 2303 chipset.

It doesn't seem to be documented which USB devices use the chipset, but a list of devices may be found on the Psychson wiki.

If you are looking for a device, it should be noted that the Phison 2303 chipset is only for USB3.0. It should also be noted that this project will not work with USB2.0 or lower because they do not use SCSI commands. More info on this can be found here.

You can check a device's chipset using a one of these scripts: Windows or Linux.

Module

The Python module is split up into three files: