AutoGadgetFS

USB testing made easy

View on GitHub

PayPal Donations

Table of Contents

  1. What’s AutoGadgetFS ?

  2. Requirments

  3. The Setup

    a. Device testing only

    b. Minimal agfs in the middle setup

    c. Complete agfs in the middle setup with debugging support

  4. USB Device class support

  5. Capabilities

  6. RoadMap

  7. Installation

    a. Linux

    b. Raspberry Pi Zero with WIFI

  8. AutogadgetFS tutorial

  9. ScreenShots

  10. Youtube Playlist

  11. Slack

  12. Supported by

  13. Buy me a coffee ☕️

  14. Contact me

  15. Want to contribute ?


What’s AutoGadgetFS ?

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.


Requirments:


The Setup:

Device testing only:

Minimal agfs in the middle setup:

Complete agfs in the middle setup with debugging support:

USB Device class support:

[✔️] USB HID Devices fully supported (Man in the middle)

[⚠️] Device only testing .. All USB devices (NO Man in the middle)

[⏳] Future releases… All USB devices (Man in the middle)


Capabilities:

  1. Find, Select and Attach to a USB device with ease.
  2. Emulate any USB HID device .
  3. Perform AGFS in the middle sniffing for HID devices ( save communication to disk ).
  4. Device sniffing ( Any device ).
  5. Multiple Fuzzers allow you to Fuzz a device or a host.
  6. Random fuzzers ( with fixed or random length packets ).
  7. Smart Fuzzers that learn from previous USB communications.
  8. Describe Fuzzer to tell the Fuzzer which bytes to Fuzz leaving the rest of the packet the same.
  9. Gadget Fuzzer.
  10. Sequential Fuzzer.
  11. Control transfer Enumerator.
  12. Replay of packets from a file.
  13. Replay of packets from a saved USBLyzer capture.
  14. Visual way of presenting packets to allow ease of reverse engineering of the communication.
  15. Alerts for device in DFU mode, or if the device leaks information.
  16. USB device and host can be anywhere on the internet.
  17. Monitor sudden interface changes.

RoadMap:

  1. Sniff control transfer requests to a device and reply to them.
  2. MITM and emulate all types of devices.
  3. Console/QT based interface.
  4. More Interfaces/endpoints support on the RPI zero W.
  5. Support more boards like the greatfet.
  6. Move to a custom board.
  7. Work on making raspberry pi have full support for usb device emulation with all interfaces.
  8. correlate sent and received packets via sequence numbers.

Installation:

Linux Machine:


Raspberry Pi Zero W:

And you’re done!


AutoGadgetFS tutorial:

Click to visit the tutorial


Screenshots:

Man in the Middle:

USB device fuzzing:

Host side fuzzing with code covereage:

Fuzzer based on a selection of bytes:

Smart fuzzer based on learning traffic:

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")                                                                                                                                                                     


[+]General Statistics
Full charset                : !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
Discarded charset           : !"#$%&'()*+,-./:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`ghijklmnopqrstuvwxyz{|}~
Final charset               : 0123456789abcdef
Word Length                 : 128
Lower Case index usage      : 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']

Help method:

In [15]: x.help("")                                                                                                                                               

Currently supported methods:
__________________________________________________________________________________________________________________________________________________________________
Method               ||-->Description
----------------------------------------------------------------------------------------------------------------------------
MITMproxy            ||-->This method creates a connection to the RabbitMQ and listen on received messages on the todev queue
____________________________________________________________________________________________________________________________
MITMproxyRQueues     ||-->This method reads from the queue todev and sends the request to the device its self.
____________________________________________________________________________________________________________________________
SmartFuzz            ||-->This method is generates packets based on what it has learned from a sniff from either the host or the device
____________________________________________________________________________________________________________________________
chgIntrfs            ||-->This method allows you to change and select another interface
____________________________________________________________________________________________________________________________
clearqueues          ||-->this method clears all the queues on the rabbitMQ queues that are set up
____________________________________________________________________________________________________________________________
clonedev             ||-->This method does not need any parameters it only saves a backup of the device incase you need to share it or use it later.
____________________________________________________________________________________________________________________________
createctrltrsnfDB    ||-->creates a SQLite database containing values that were enumerated from control transfer enumeration
____________________________________________________________________________________________________________________________
createdb             ||-->create the sqlite table and columns from usblyzer captures
____________________________________________________________________________________________________________________________
decodePacketAscii    ||-->This method decodes packet bytes back to Ascii
____________________________________________________________________________________________________________________________
describeFuzz         ||-->This method allows you to describe a packet and select which bytes will be fuzzed
____________________________________________________________________________________________________________________________
devEnumCtrltrnsf     ||-->This method enumerates all possible combinations of a control transfer request
____________________________________________________________________________________________________________________________
devReset             ||-->This method Resets the device
____________________________________________________________________________________________________________________________
devWrite             ||-->To use this with a method you would write to a device make sure to run the startSniffReadThread(self,endpoint=None, pts=None, queue=None,channel=None)
____________________________________________________________________________________________________________________________
devctrltrnsf         ||-->This method allows you to send ctrl transfer requests to the target device
____________________________________________________________________________________________________________________________
deviceInfo           ||-->gets the complete info only for any usb connected to the host
____________________________________________________________________________________________________________________________
deviceInterfaces     ||-->get all interfaces and endpoints on the device
____________________________________________________________________________________________________________________________
devrandfuzz          ||-->this method allows you to create fixed or random size packets created using urandom
____________________________________________________________________________________________________________________________
devseqfuzz           ||-->This method allows you to create sequential incremented packets and send them to the device
____________________________________________________________________________________________________________________________
findSelect           ||-->This method enumerates all USB devices connected and allows you to select it as a target device as well as its endpoints
____________________________________________________________________________________________________________________________
help                 ||-->AutogadgetFS Help method
____________________________________________________________________________________________________________________________
hostwrite            ||-->This method writes packets to the host either targeting a software or a driver in control of the device
____________________________________________________________________________________________________________________________
hstrandfuzz          ||-->this method allows you to create fixed or random size packets created using urandom and send them to the host queue
____________________________________________________________________________________________________________________________
monInterfaceChng     ||-->Method in charge of monitoring interfaces for changes this is called from def startMonInterfaceChng(self)
____________________________________________________________________________________________________________________________
newProject           ||-->creates a new project name if you were testing something else
____________________________________________________________________________________________________________________________
releasedev           ||-->releases the device and re-attaches the kernel driver
____________________________________________________________________________________________________________________________
removeGadget         ||-->This method removes the gadget from the raspberryPI
____________________________________________________________________________________________________________________________
replaymsgs           ||-->This method searches the USBLyzer parsed database and give you the option replay a message or all messages from host to device
____________________________________________________________________________________________________________________________
searchmsgs           ||-->This method allows you to search and select all messages for a pattern which were saved from a USBlyzer database creation
____________________________________________________________________________________________________________________________
setupGadgetFS        ||-->setup variables for gadgetFS : Linux Only, on Raspberry Pi Zero best option
____________________________________________________________________________________________________________________________
showMessage          ||-->shows messages if error or warn or info
____________________________________________________________________________________________________________________________
sniffdevice          ||-->read the communication between the device to hosts
____________________________________________________________________________________________________________________________
startMITMusbWifi     ||-->Starts a thread to monitor the USB target Device
____________________________________________________________________________________________________________________________
startMonInterfaceChng||-->This method Allows you to monitor a device every 10 seconds in case it suddenly changes its interface configuration.
____________________________________________________________________________________________________________________________
startQueuewrite      ||-->initiates a connection to the queue to communicate with the host
____________________________________________________________________________________________________________________________
startSniffReadThread ||-->This is a thread to continuously read the replies from the device and dependent on what you pass to the method either pts or queue
____________________________________________________________________________________________________________________________
stopMITMusbWifi      ||-->Stops the man in the middle thread between the host and the device
____________________________________________________________________________________________________________________________
stopMonInterfaceChang||-->Stops the interface monitor thread
____________________________________________________________________________________________________________________________
stopQueuewrite       ||-->stop the thread incharge of communicating with the host machine
____________________________________________________________________________________________________________________________
stopSniffing         ||-->Kills the sniffing thread strted by startSniffReadThread()
____________________________________________________________________________________________________________________________
usblyzerparse        ||-->This method will parse your xml exported from usblyzer and then import them into a database
____________________________________________________________________________________________________________________________

In [16]: x.help("findSelect")                                                                                                                                                                 
****
[+]Help for findSelect Method:
[-]Signature: findSelect(self, chgint=None)


[+]findSelect Help:
This method enumerates all USB devices connected and allows you to select it as a target device as well as its endpoints
****

AutoGadgetFS console. A much simpler way to use AGFS:


Youtube Playlist:

Youtube Playlist


Join Slack:

Visit AutogadgetFS Slack Channel


Supported by:


Buy me a coffee to support the development of this project

PayPal Donations


Contact me:

📧: [email protected]

🐦 : https://twitter.com/0xRaindrop


Contribute:

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.