<iframe width= "500" height= "315" src= "https://www.youtube.com/embed/VY10xFifA50"frameborder=" 0 "allow=" accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture "allowfullscreen></iframe>
AutoGadgetFS is an open source framework that allows users to assess USB devices and their associated hosts/drivers/software without an in-depth knowledge of the USB protocol. The tool is written in Python3 and utilizes RabbitMQ and WiFi access to enable researchers to conduct remote USB security assessments from anywhere around the globe. By leveraging ConfigFS, AutoGadgetFS allows users to clone and emulate devices quickly, eliminating the need to dig deep into the details of each implementation. The framework also allows users to create their own fuzzers on top of it.
- 💻 Host machine running Linux (Debian/Ubuntu/Kali)
- 🥧 Raspberry Pi Zero with WIFI support
- 🎯 Target machine options:
- Virtual Machine
- Standalone machine
- 🔌 2 x USB micro cables
- 🔱 Target USB device
- 🐞 Hardware debugger ( Optional )
Device testing only:
Minimal agfsinthe middle setup:
Complete agfsinthe middle setup with debugging support:
[✔️] USB HID Devices fully supported (Man in the middle)
[
[⏳] Future releases... All USB devices (Man in the middle)
- Find, Select and Attach to a USB device with ease.
- Emulate any USB HID device.
- Perform AGFS in the middle sniffing for HID devices ( save communication to disk ).
- Device sniffing ( Any device ).
- Multiple Fuzzers allow you to Fuzz a device or a host.
- Random fuzzers ( with fixed or random length packets ).
- Smart Fuzzers that learn from previous USB communications.
- Describe Fuzzer to tell the Fuzzer which bytes to Fuzz leaving the rest of the packet the same.
- Gadget Fuzzer.
- Sequential Fuzzer.
- Control transfer Enumerator.
- Replay of packets from a file.
- Replay of packets from a saved USBLyzer capture.
- Visual way of presenting packets to allow ease of reverse engineering of the communication.
- Alerts for device in DFU mode, or if the device leaks information.
- USB device and host can be anywhere on the internet.
- Monitor sudden interface changes.
- Sniff control transfer requests to a device and reply to them.
- MITM and emulate all types of devices.
- Console/QT based interface.
- More Interfaces/endpoints support on the RPI zero W.
- Support more boards like the greatfet.
- Move to a custom board.
- Work on making raspberry pi have full support for usb device emulation with all interfaces.
- correlate sent and received packets via sequence numbers.
-
Note: WSL/WSL2 is not supported due to issues with USB pass-through.
-
Install Python3, ipython3,git, pip and rabbitMQ server
sudo apt install python3 ipython3 git python3-pip rabbitmq-server dfu-util sudo service rabbitmq-server start
-
Clone the repository
git clone https://github.com/ehabhussein/AutoGadgetFS cdAutoGadgetFS -
Install the requirements
sudo -H pip3 install -r requirements.txt
-
Downgrade prompt toolkit for better ipython experience:
sudo python3 -m pip install prompt-toolkit~=2.0
-
Enable the web interface for rabbitMQ
sudo rabbitmq-pluginsenablerabbitmq_management http://localhost:15672/ to reach the web interface -
login to the web interface with the credentialsguest:guest
-
NOTE: if you are not installing rabbitMQ on
localhostadd the following user and login with it:sudo rabbitmqctl add_user autogfs usb4ever sudo rabbitmqctl set_user_tags autogfs administrator
-
Upload the rabbitMQ configuration file
- In the overview tab scroll to the bottom to import definitions
- Upload the file found in:rabbitMQbrokerconfig/rabbitmq-Config.json
sudo service rabbitmq-server restart
-
-
Test the installation
sudoipython3 Python3.7.7(default,Apr12020,13:48:52) Type'copyright','credits'or'license'formoreinformation IPython7.9.0--AnenhancedInteractivePython.Type'?'forhelp. In[1]:importlibagfs In[2]:x=libagfs.agfs() *************************************** AutoGadgetFS:USBtestingmadeeasy *************************************** EnterIPaddressoftherabbitmqserver:127.0.0.1 In[3]:exit sudo`python3`agfsconsole.py *************************************** AutoGadgetFS:USBtestingmadeeasy *************************************** EnterIPaddressoftherabbitmqserver:127.0.0.1 Giveyourprojectaname?!:
-
Patch Pyusb langID ( Not needed unless you get pyusb errors for langID ):
- Edit the file
/usr/local/lib/python3/dist-packages/usb/util.py-
make changes to the
def get_stringmethod to look like below:if0==len(langids): return"Error Reading langID" #raise ValueError( "The device has no langid" ) iflangidisNone: langid=langids[0] eliflangidnotinlangids: return"Error Reading langID" #raise ValueError( "The device does not support the specified langid" )
-
If you prefer to use
patchapply the following patch to the file:AutoGadgetFS/pyusb_patches/pyusb_langid.patch
-
- Edit the file
-
Obtain a copy ofRaspian Lite Edition
- Burn the Image to the SD card usingBalenaEtcher
-
Mount the SD card on your machine and make the following changes:
-
In the
/path/to/sdcard/boot/config.txtfile add to the very end of the file:enable_uart=1 dtoverlay=dwc2
-
In the
/path/to/sdcard/boot/cmdline.txtadd right afterrootwaitmodules-load=dwc2
-
it should look like this make sure its on the same line:
console=serial0,115200 console=tty1 root=PARTUUID=6c586e13-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait modules-load=dwc2
-
-
Enable ssh:
-
in the
/path/to/sdcard/bootdirectory create an empty file name ssh:sudo touch /path/to/sdcard/boot/ssh
-
-
Enable Wifi:
-
in the
/path/to/sdcard/bootdirectory create an file namedwpa_supplicant.conf:sudo vim /path/to/sdcard/boot/wpa_supplicant.conf
-
Add the following contents:
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 country=US network={ ssid="<your wifi SSID>" psk="<your wifi password>" key_mgmt=WPA-PSK }
-
-
Unmount the SD card and place it back into the Raspberry Pi Zero and power it on.
-
Copy the content of
AutogadgetFS/Pizero/to the Pi zero:username: pi&password: raspberrycdAutogadgetFS/Pizero/ scp gadgetfuzzer.py removegadget.sh requirements.txt router.py pi@<pi-ipaddress>:/home/pi
-
SSH into the PI Zero and setup requirements for AutoGadgetFS:
ssh pi@<pi-ip-address> chmod +x removegadget.sh sudo apt update sudo apt install python3 python3-pip sudo -H pip3 install -r requirements.txt
-
Upgrading the latest kernel and adding modules (* This step is optional for the current release): ( This will take a very long time compiling on the Pi Zero, unless you choose to cross compile the kernel seeCompiling options)
sudo bash apt install git bc bison flex libssl-dev make libncurses5-dev screen screen mkdir Downloads cdDownloads/ git clone --depth=1 https://github.com/raspberrypi/linux cdlinux/ make bcmrpi_defconfig make menuconfig
- Enable the Modules and save the config:
- Build and use the kernel:
make zImage modules dtbs make modules_install cp arch/arm/boot/dts/*.dtb /boot/ cp arch/arm/boot/dts/overlays/*.dtb*/boot/overlays/ cp arch/arm/boot/dts/overlays/README /boot/overlays/ cp arch/arm/boot/zImage /boot/kernel.img reboot
In[44]:x.devSmartFuzz(engine="smart",samples=5,filename="/home/raindrop/PycharmProjects/AutoGadgetFs/binariesdb/Nud-Nuvoton-1046-20764-1590421333.5169587-Nuvoton-1046-20764-1590421600.8067
...:274-device.bin")
[+]GeneralStatistics
Fullcharset:!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
Discardedcharset:!"#$%&'()*+,-./:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`ghijklmnopqrstuvwxyz{|}~
Finalcharset:0123456789abcdef
WordLength:128
LowerCaseindexusage:92%
Lower Case index locations: [1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 121, 122, 124, 125, 127]
Upper Case index usage: 0%
Upper Case index locations: []
Digit index usage: 96%
Digit index locations: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 123, 126]
NonAN index usage: 0%
NonAN index locations: []
Counter statistics: Uppercase: 0, Lowercase: 133071, Digits:212017, NonAlphaNumeric:0
All char Frequencies:
character:5 found:5012 times
character:2 found:22563 times
character:3 found:12197 times
character:8 found:15008 times
character:4 found:13275 times
character:0 found:98056 times
character:1 found:17861 times
character:f found:87823 times
character:d found:7221 times
character:7 found:9614 times
character:a found:11148 times
character:6 found:10472 times
character:b found:8189 times
character:9 found:7959 times
character:c found:9172 times
character:e found:9518 times
***********************
generated:5 Packets
***********************
Out[44]:
['5608305852bf2ffd61770e2c827542f20be0b0fcba09db916bd07e1734b04cb0352b1d278068064d19f033bfad6fa90e53d865693fd4fee0214f00000eb0aa2c',
'3b083595f276e2f1353a535c32f0f59516fc9328f7673bb80262c4da11c93683afe6dcff8a7a83018d78f41498a0da4d141ebd39c361b1724f2b00000eb0aa2c',
'0120961963495c4dab9470738b497eddde07b0d70b357795ad9554d7964761969a6d997205e17eada6fa84eb33dcfb11412f75e04c195001283900000eb0aa2c',
'091065d52127bbc6e840e02f8e1316f1c4d9c92a23931c00cdbb8c158368852ef8fabd461b98812b51ec84e1ccc5c04aaa366fbafabec623bd3500000eb0aa2c',
'7300cc61151b7af27a578e766f49bebb2de68c48b37a00df1030ae464f456928eedd035303e697208bf58217af728a2a346fda5c8aef0335b82e00000eb0aa2c'
In [46]: x.edap.packets
Out[46]:
['5608305852bf2ffd61770e2c827542f20be0b0fcba09db916bd07e1734b04cb0352b1d278068064d19f033bfad6fa90e53d865693fd4fee0214f00000eb0aa2c',
'3b083595f276e2f1353a535c32f0f59516fc9328f7673bb80262c4da11c93683afe6dcff8a7a83018d78f41498a0da4d141ebd39c361b1724f2b00000eb0aa2c',
'0120961963495c4dab9470738b497eddde07b0d70b357795ad9554d7964761969a6d997205e17eada6fa84eb33dcfb11412f75e04c195001283900000eb0aa2c',
'091065d52127bbc6e840e02f8e1316f1c4d9c92a23931c00cdbb8c158368852ef8fabd461b98812b51ec84e1ccc5c04aaa366fbafabec623bd3500000eb0aa2c',
'7300cc61151b7af27a578e766f49bebb2de68c48b37a00df1030ae464f456928eedd035303e697208bf58217af728a2a346fda5c8aef0335b82e00000eb0aa2c']In[15]:x.help("")
Currentlysupportedmethods:
__________________________________________________________________________________________________________________________________________________________________
Method||-->Description
----------------------------------------------------------------------------------------------------------------------------
MITMproxy||-->ThismethodcreatesaconnectiontotheRabbitMQandlistenonreceivedmessagesonthetodevqueue
____________________________________________________________________________________________________________________________
MITMproxyRQueues||-->Thismethodreadsfromthequeuetodevandsendstherequesttothedeviceitsself.
____________________________________________________________________________________________________________________________
SmartFuzz||-->Thismethodisgeneratespacketsbasedonwhatithaslearnedfromasnifffromeitherthehostorthedevice
____________________________________________________________________________________________________________________________
chgIntrfs||-->Thismethodallowsyoutochangeandselectanotherinterface
____________________________________________________________________________________________________________________________
clearqueues||-->thismethodclearsallthequeuesontherabbitMQqueuesthataresetup
____________________________________________________________________________________________________________________________
clonedev||-->Thismethoddoesnotneedanyparametersitonlysavesabackupofthedeviceincaseyouneedtoshareitoruseitlater.
____________________________________________________________________________________________________________________________
createctrltrsnfDB||-->createsaSQLitedatabasecontainingvaluesthatwereenumeratedfromcontroltransferenumeration
____________________________________________________________________________________________________________________________
createdb||-->createthesqlitetableandcolumnsfromusblyzercaptures
____________________________________________________________________________________________________________________________
decodePacketAscii||-->ThismethoddecodespacketbytesbacktoAscii
____________________________________________________________________________________________________________________________
describeFuzz||-->Thismethodallowsyoutodescribeapacketandselectwhichbyteswillbefuzzed
____________________________________________________________________________________________________________________________
devEnumCtrltrnsf||-->Thismethodenumeratesallpossiblecombinationsofacontroltransferrequest
____________________________________________________________________________________________________________________________
devReset||-->ThismethodResetsthedevice
____________________________________________________________________________________________________________________________
devWrite||-->TousethiswithamethodyouwouldwritetoadevicemakesuretorunthestartSniffReadThread(self,endpoint=None,pts=None,queue=None,channel=None)
____________________________________________________________________________________________________________________________
devctrltrnsf||-->Thismethodallowsyoutosendctrltransferrequeststothetargetdevice
____________________________________________________________________________________________________________________________
deviceInfo||-->getsthecompleteinfoonlyforanyusbconnectedtothehost
____________________________________________________________________________________________________________________________
deviceInterfaces||-->getallinterfacesandendpointsonthedevice
____________________________________________________________________________________________________________________________
devrandfuzz||-->thismethodallowsyoutocreatefixedorrandomsizepacketscreatedusingurandom
____________________________________________________________________________________________________________________________
devseqfuzz||-->Thismethodallowsyoutocreatesequentialincrementedpacketsandsendthemtothedevice
____________________________________________________________________________________________________________________________
findSelect||-->ThismethodenumeratesallUSBdevicesconnectedandallowsyoutoselectitasatargetdeviceaswellasitsendpoints
____________________________________________________________________________________________________________________________
help||-->AutogadgetFSHelpmethod
____________________________________________________________________________________________________________________________
hostwrite||-->Thismethodwritespacketstothehosteithertargetingasoftwareoradriverincontrolofthedevice
____________________________________________________________________________________________________________________________
hstrandfuzz||-->thismethodallowsyoutocreatefixedorrandomsizepacketscreatedusingurandomandsendthemtothehostqueue
____________________________________________________________________________________________________________________________
monInterfaceChng||-->MethodinchargeofmonitoringinterfacesforchangesthisiscalledfromdefstartMonInterfaceChng(self)
____________________________________________________________________________________________________________________________
newProject||-->createsanewprojectnameifyouweretestingsomethingelse
____________________________________________________________________________________________________________________________
releasedev||-->releasesthedeviceandre-attachesthekerneldriver
____________________________________________________________________________________________________________________________
removeGadget||-->ThismethodremovesthegadgetfromtheraspberryPI
____________________________________________________________________________________________________________________________
replaymsgs||-->ThismethodsearchestheUSBLyzerparseddatabaseandgiveyoutheoptionreplayamessageorallmessagesfromhosttodevice
____________________________________________________________________________________________________________________________
searchmsgs||-->ThismethodallowsyoutosearchandselectallmessagesforapatternwhichweresavedfromaUSBlyzerdatabasecreation
____________________________________________________________________________________________________________________________
setupGadgetFS||-->setupvariablesforgadgetFS:LinuxOnly,onRaspberryPiZerobestoption
____________________________________________________________________________________________________________________________
showMessage||-->showsmessagesiferrororwarnorinfo
____________________________________________________________________________________________________________________________
sniffdevice||-->readthecommunicationbetweenthedevicetohosts
____________________________________________________________________________________________________________________________
startMITMusbWifi||-->StartsathreadtomonitortheUSBtargetDevice
____________________________________________________________________________________________________________________________
startMonInterfaceChng||-->ThismethodAllowsyoutomonitoradeviceevery10secondsincaseitsuddenlychangesitsinterfaceconfiguration.
____________________________________________________________________________________________________________________________
startQueuewrite||-->initiatesaconnectiontothequeuetocommunicatewiththehost
____________________________________________________________________________________________________________________________
startSniffReadThread||-->Thisisathreadtocontinuouslyreadtherepliesfromthedeviceanddependentonwhatyoupasstothemethodeitherptsorqueue
____________________________________________________________________________________________________________________________
stopMITMusbWifi||-->Stopsthemaninthemiddlethreadbetweenthehostandthedevice
____________________________________________________________________________________________________________________________
stopMonInterfaceChang||-->Stopstheinterfacemonitorthread
____________________________________________________________________________________________________________________________
stopQueuewrite||-->stopthethreadinchargeofcommunicatingwiththehostmachine
____________________________________________________________________________________________________________________________
stopSniffing||-->KillsthesniffingthreadstrtedbystartSniffReadThread()
____________________________________________________________________________________________________________________________
usblyzerparse||-->Thismethodwillparseyourxmlexportedfromusblyzerandthenimportthemintoadatabase
____________________________________________________________________________________________________________________________
In[16]:x.help("findSelect")
****
[+]HelpforfindSelectMethod:
[-]Signature:findSelect(self,chgint=None)
[+]findSelectHelp:
ThismethodenumeratesallUSBdevicesconnectedandallowsyoutoselectitasatargetdeviceaswellasitsendpoints
****
VisitAutogadgetFS Slack Channel
We're looking for developers to make this tool great! send me an 📧:[email protected]if you feel you'd like to be a part of this.